inheritance tree
NonType Reflection FlagsMixin
| | |
`-----+--' |
| |
ScoreObject SMapping.mappingMixin
| |
`---------+---------'
|
Item
|
`+
|
Element TimeMixin
| |
`----+-------------------'
|
TemporalElement
|
|
|
Event
class definition
[semi abstract class or concrete class?] An event is a score element which produces sound when the score is played. An event is a very general representation for something producing sound. For instance, a note played on a piano (with a specific pitch, loudness etc.), a hand clapping (no pitch, but maybe a specific loudness), or an arbitrary sound synthesis language event (possibly with dozends of parameters) are all representable be an event.
To provide such generality, an event has the attribute parameters which points to a collection [better term?] of all parameters of the event. The parameters themself contain information about their purpose (e.g. parameters are of a certain class as pitch, or amplitude). However, as a convenience, certain parameters are additionally referenced by an extra feature (e.g. all timing related parameters have their own feature, as startTime, offsetTime, endTime or duration). Subclasses of the event class may define additional features. Nevertheless, all parameters can be accessed via the parameters feature
An event always has the timing parameters startTime, duration, endTime, and offsetTime. However, additional parameters can be specified optionally (e.g. by the feature addParameters of the init method).
For a documentation of the time unit see doc of TimeMixin.
class Event (Inheritance-free)
prop locking
feat !ScoreObjectType label
attr containers duration endTime flags id info offsetTime parameters startTime
- addContainer(Container)
[aux method] Method adds Container to list of containers self is contained in. However, method does not establish bidirectional links. Method should not be called by user.
- addFlag(F)
Adds an arbitrary flag F to self. A flag must be a literal.
- addInfo(X)
[destructive method] Adds X to list in attribute info. The tail of the list at attribute info is the info that was specified before with addInfo and was give at the init method (default is nil).
- addInfos(Xs)
[destructive method] Adds every element in list Xs to list in attribute info.
- bilinkContainers(Containers)
Calling the method bilinkItems with Containers expresses that self is contained in all Containers. The method establishes bidirectional links between both self and all Containers. Method must not be called by user (only by class designer).
- bilinkParameters(Parameters)
[aux method] Method must not be called by user.
*/
!! method removed
meth addParameters(Parameters)
{@parameters addList(Parameters)}
end
/** %% [aux method] Parameters and self are bidirectional linked. Method must not be called by user (only by class designer).
- closeExtendableLists()
[aux method]
- closeScoreHierarchy(mode:Mode)
After instantiating and initialising score objects to form a score hierarchy, the hierarchy is still extendable (i.e. the user can add items to containers and containers to items). The method closeScoreHierarchy makes a score hierarchy unextendable, which is necessary to prevent various procedures/methods from blocking.
- collect(?Xs excludeSelf:ExcludeSelf level:Level mode:Mode test:Test)
The collect methods collects (possibly all) score objects in a list to make them accessible for, e.g., various list mapping functions. The method collects objects related to self (an item) by the value of the item attributes containers, parameters and the container attribute items. The methods supports a few features to control the collecting.
If feature mode is set to tree (the default), collect recursively collects the score objects and subobjects contained in self (i.e. both the attributes items and parameters are traversed). If mode is set to graph, both objects contained in self and containers self is contained in are collected (i.e. all three attributes items, parameters, and containers are traversed).
If feature level is set to all (the default), collect collects score objects recursively into arbitrary depth. However, the depth can be controlled by specifying an integer value for level.
The feature test expects a unary function returning a boolean or an atom representing a boolean unary method understood by all objects in self. The method collect only collects score objects fulfilling the test function/method.
The feature excludeSelf expects a Boolean. If true (the default), self is not included in the result.
collect visits containers in depth-first fashion from left to right which affects the order of the objects in the returned list. E.g., collecting all events in a few nested sequentials in tree mode returns a list with all events ordered by start time.
NB: collect blocks if self is not fully initialised (e.g. created by Score.makeScore2) or if Test blocks at some object in self (e.g. because the object is only partially determined).
- constrainTiming()
After full creation of score hierarchy, method must be called with every TimeMixin subclass instance in score to init the timing attributes/features
- count(?N excludeSelf:ExcludeSelf level:Level mode:Mode test:Test)
The method count counts a number of collected score objects. The method supports the features mode, level, test, and excludeSelf. These features have the same meaning as in the method collect.
- filter(?Xs Fn excludeSelf:ExcludeSelf level:Level mode:Mode)
The method filter collects a number of score objects fulfilling Fn, a the unary function returning a boolean. The method supports the features mode, test, and excludeSelf. These features have the same meaning as in the method collect.
- filterContainers(Xs Fn)
Return a list of all direct containers of self for which Fn (unary function or method) returns true.
- filterParameters(Xs Fn)
Return a list of all direct parameters of self for which Fn (unary function or method) returns true.
- find(?Xs Fn excludeSelf:ExcludeSelf level:Level mode:Mode)
The method find returns the first score object in self fulfilling Fn, a the unary function returning a boolean. The method supports the features mode, level, and excludeSelf. These features have the same meaning as in the method collect.
NB: this implementation is inefficient (first collects all score objects).
- findContainer(X Test)
Returns the first direct container self is contained in which fulfils the boolean function or method Test.
- findContainerRecursively(X Test)
Returns the first direct or indirect container of self, which fulfils the boolean function or method Test.
- findParameter(X Test)
Returns the first direct parameter of self which fulfils the boolean function or method Test.
- findSimultaneousItem(X cTest:CTest test:Test toplevel:Top)
[Deterministic method] Returns the first score object found which is simultaneous to self and fulfilling the optional boolean function or method test.
If a toplevel Top (a temporal container) is given, then only within that container is searched for simultaneous items to self. Otherwise the temporal top-level of self is searched (i.e. usually the whole score).
The implementation uses LUtils.cFind and the reified constraints method isSimultaneousItemR. X is return as soon as the score contains enough information to tell for any score object that it is simultaneous to self (i.e. rhythmic structure of the whole score must not necessarily be fully determined).
NB: Test must be a deterministic function/method which does not block (e.g., checks on score object types or their position in the score topology are OK) and which is used for pre-filtering score objects. The argument cTest has the same format (optional Boolean function or method), but it is applied within the concurrent filtering of LUtils.cFilter, together with isSimultaneousItemR. Computationally very expensive tests and in particular tests which can block are better handed to cTest.
- forAll(Proc excludeSelf:ExcludeSelf level:Level mode:Mode test:Test)
The method forAll maps the procedure Proc to a number of collected score objects. Proc may also be an atom representing a method of no arguments and understood by all objects in self fulfilling Test. The method supports the features mode, level, test, and excludeSelf. These features have the same meaning as in the method collect.
- forAllContainers(Proc)
Applies Proc (unary procedure or method) on all direct containers in self.
- forAllParameters(Proc)
Applies Proc (unary procedure or method) on all direct parameters in self.
- forAllThreaded(Proc excludeSelf:ExcludeSelf level:Level mode:Mode test:Test)
The method traverses all score objects in self (i.e. items and parameters) and applies unary procedure (or null-ary method) Proc on every object returning true for the unary function (or unary method) Test. However, the method does not effect the object self itself -- only the parameters and (if self is a container) items of self are effected recursively. Traversing happens concurrently -- the method does not suspend even if the result of getItems or getParameters is not yet fully determined.
- getAttr($ A)
Returns the value at attribute A.
- getAttrNames($)
Returns a list of all attributes (atoms) defined for self.
- getAttrSources($)
Alias for getAttrNames.
*/
meth getAttributes($) {self getAttrNames($)} end
/** %% Returns a record where the features are the attributes defined for self and the values are the classes which define these attributes.
- getClass($)
- getClassName($)
Returns the print name of the class of self as specified in its definition. The name is an atom derived from a variable and thus starting with a capital letter, e.g., 'ScoreObject'.
- getContainers(X)
- getContainersRecursively($)
Returns all direct and indirect containers of self.
- getDuration(X)
- getDurationInBeats(X)
- getDurationInSeconds($)
- getDurationParameter(X)
- getEndTime(X)
- getEndTimeInBeats(X)
- getEndTimeInSeconds(X)
- getEndTimeParameter(X)
- getFeat($ F)
Returns the value at feature F.
- getFeatNames($)
Returns a list of all features (atoms) defined for self.
- getFeatSources($)
Returns a record where the features are the features defined for self and the values are the classes which define these features.
- getFeatures($)
Alias for getFeatNames.
- getID(X)
- getInfo(X)
- getInfoRecord($ L)
Returns first record with label L in the list in attribute info.
- getInitArgDefaults($)
Returns a record where the features are all supported arguments of the init method of self with their default as value (_ indicates that no default exist).
NB: this method relies on the correct implementation of the method getInitArgs for its class and all its superclasses.
- getInitArgSources($)
- getInitClasses(Classes)
Collects all classes of the objects in self in the format expected by the second argument of Score.makeScore, i.e., a record of the form unit(label1:Class1 ... labelN:ClassN)
- getInitClassesVS($)
Like getInitClasses, getInitClassesVS collects all classes of the objects in self in the format expected by the second argument of Score.makeScore. However, the result record is returned as a VS (e.g., for outputting into Oz source text files). The Strasheela classes are specified by accessing them in Strasheela functors (e.g., Strasheeala.score.note). The toplevel Strasheela functors are taken from {Init.getStrasheelaEnv strasheelaFunctors}.
NB: getInitClassesVS examines every class in these functors (and their subfunctors) and requires that whenever a class defines an init method, all init method arguments must be optional.
- getInitInfo($ ...)
- getMethNames($)
Returns a list of all methods (atoms) defined for self.
- getMethSources($)
Returns a record where the features are the methods defined for self and the values are the classes which define these methods.
- getOffsetTime(X)
- getOffsetTimeInBeats(X)
- getOffsetTimeInSeconds(X)
- getOffsetTimeParameter(X)
- getParameters(X)
- getPosRelatedItem(?X N Container)
Returns the item in Container which is the Nth in relation to self (i.e. self too is an item in Container). N may be a negative integer (returns an item before self) or a positive integer (returns an item after self). For example, {X positionOffset($ 1 C)} returns the item just after self in C.
- getPosition(?Pos Container)
Returns the index of self in Container.
- getPredecessor(?X Container)
Returns predecessor item of self in Container.
- getPredecessors(X N Container)
Returns a list of the N items that precede self in Container, the item closes to self first. If N goes beyond the number of items available then on the available items are returned (i.e. the returned list is shorter than N).
- getPredecessorsUpToRest($)
Returns a list of the items that precede self in its TemporalAspect up to any rest (i.e. a pause object or an item with an offset time > 0). A pause object would be excluded, but an item with an offset time > 0 would be included.
Note: method delayed until offset times are sufficienly determined.
- getSimultaneousItems(?Xs cTest:CTest test:Test toplevel:Top)
[Deterministic method] Returns list of score items simultaneous to self and fulfilling the optional Boolean function or method test.
If a toplevel Top (a temporal container) is given, then only within that container is searched for simultaneous items to self. Otherwise the temporal top-level of self is searched (i.e. usually the whole score).
See the documentation of GetItemsInTimeframe for further details (e.g., on the argument cTest).
- getSimultaneousItemsOffset(Xs Offset cTest:CTest test:Test toplevel:Top)
[Deterministic method] Generalised version of getSimultaneousItems where the offset time Offset (FD int) is taken into account. See the doc of InTimeframeOffsetR for the meaning of the Offset.
- getStartTime(X)
- getStartTimeInBeats(X)
- getStartTimeInSeconds(X)
- getStartTimeParameter(X)
- getSuccessor(?X Container)
Returns successor item of self in Container.
- getSuccessors(X N Container)
Returns a list of the N items that succeed self in Container. If N goes beyond the number of items available then on the available items are returned (i.e. the returned list is shorter than N).
- getSuccessorsUpToRest($)
Returns a list of the items that succeed self in its TemporalAspect up to any rest (i.e. a pause object or an item with an offset time > 0). A pause object would be excluded, and so would be an item with an offset time > 0.
Note: method delayed until offset times are sufficienly determined.
- getTemporalAspect(X)
Returns the TemporalAspect self is contained in. A score object must be contained in only a single temporal aspect.
- getTemporalContainer($)
Alias for getTemporalAspect.
- getTemporalPosition(?Pos)
Returns the index of self in its temporal container (temporal aspect).
- getTemporalPredecessor(X)
Returns the predecessor of object in its TemporalAspect. NB: method returns positional and not a temporal predecessor.
- getTemporalPredecessors(X N)
Returns a list of the N items that precede self in its TemporalAspect, the item closes to self first. If N goes beyond the number of items available then on the available items are returned (i.e. the returned list is shorter than N).
- getTemporalSuccessor(X)
Returns the successor of object in its TemporalAspect. NB: method returns positional and not a temporal successor.
- getTemporalSuccessors(X N)
Returns a list of the N items that succeed self in its TemporalAspect. If N goes beyond the number of items available then on the available items are returned (i.e. the returned list is shorter than N).
- getTemporalToplevel(Xs test:Test)
Returns the first top level of self which is a temporal item
(cf. doc to getTopLevels).
- getTimeUnit(X)
- getTopLevels(?Xs test:Test)
Returns list of all top level items in score hierarchy graph of self which fulfil the optional boolean function or method test.
NB: This method even collects top-levels which are not (indirect) container of self but only of some of its (indirect) contained items.
- hasAbsoluteTimeUnit(B)
Returns true if the timeUnit is either seconds or milliseconds, and false otherwise.
- hasFlag(?B F)
Tests whether self has flag F. Method returns a boolean.
- hasPosRelatedItem(B N Container)
!! doc missing
- hasPredecessor(?B Container)
Returns a boolean whether self has a predecessor in Container.
- hasSuccessor(?B Container)
Returns a boolean whether self has a successor in Container.
- hasTemporalContainer($)
- hasTemporalPredecessor(B)
- hasTemporalSuccessor(B)
Checks whether object has a successor in its TemporalAspect. NB: method checks for a positional and not a temporal successor.
!!?? Rename to hasSuccessorInTemporalAspect ?
- hasThisInfo(B Info)
Returns boolean whether the list at the attr info of self contains Info. In case some info value is a record, then it is checked whether its label is Info.
- init(duration:Duration endTime:EndTime offsetTime:OffsetTime startTime:StartTime timeUnit:TimeUnit ...)
The timing parameter units are specified by timeUnit.
- initDomains(Spec)
Initialises all parameters of item to FD variables (if still free). This method is called by MakeScore. For item subclasses it should be overwritten as necessary.
- initFlags()
[aux method] Method must not be called by user.
- initTiming(duration:Duration endTime:EndTime offsetTime:OffsetTime startTime:StartTime timeUnit:TimeUnit)
[aux method] Method must not be called by user.
- isAbstractElement(B)
- isAmplitude(B)
- isAspect(B)
- isContainer(B)
- isDet($)
Are all parameter values determined? NB: isDet can return false simply because constraint propagation did not finish to determine some parameter. You may want to use the method wait instead.
- isElement(B)
- isEvent(B)
- isExactlySimultaneousItemR(?B X)
[0/1 Constraint] Returns 0/1-integer whether self and X are exactly simultaneous in time (i.e. start and end at the same time).
This relation defines the Allen's Interval Algebra relation equal.
- isFirstItem(?B Container)
Returns a boolean whether self is the first item in Container.
- isItem(B)
- isLastItem(?B Container)
Returns a boolean whether self is the last item in Container.
- isModifier(B)
- isNote(B)
- isParameter(B)
- isPause(B)
- isPitch(B)
- isScoreObject(B)
- isSequential(B)
- isSimultaneous(B)
- isSimultaneousItem(?B X)
[Deterministic method] Returns boolean whether self and X are simultaneous in time.
This relation defines a conjunction of the following Allen's Interval Algebra relations: overlaps, starts, during, finishes and equal; only meets and before/after are excluded.
- isSimultaneousItemOffset(B X Offset)
[Deterministic method] Generalised version of isSimultaneousItem where the offset time Offset is taken into account (see InTimeframeOffset).
- isSimultaneousItemOffsetR(B X Offset)
[0/1 Constraint] Generalised version of isSimultaneousItemR where the offset time Offset is taken into account.
- isSimultaneousItemR(?B X)
[0/1 Constraint] Returns 0/1-integer whether self and X are simultaneous in time (i.e. somehow overlap in time).
This relation defines a conjunction of the following Allen's Interval Algebra relations: overlaps, starts, during, finishes and equal; only meets and before/after are excluded.
- isTemporalAspect(B)
- isTemporalElement(B)
- isTimeInterval(B)
- isTimeMixin(B)
- isTimeParameter(B)
- isTimePoint(B)
- isTopLevel(?B)
Returns boolean whether self is a top level item in the score hierarchy graph.
- makeInitRecord(X Attrs)
[aux method for toInitRecord]: returns a record intended to facilitate the init method creation of an object for archive purposes. Attrs has the form [Key1#Accessor1#Default1 ...], keys are the record features of the init record, accessors the respective accessor for some object attributes (unary function or method), defaults are the respective attribute default values (the special default value noMatch matches nothing).
- makePPrintRecord(X Features Slots Excluded functions:Fns)
[aux method for toPPrintRecord] Returns a record with the label of self (the value at the feature label of self) and the values of selected features/attributes of self at record labels. All atoms in the list Features which are member in the list Slots are features of the returned record.
Usually, the record feature is just bound to the value at the features/attributes of self. However, for certain features/attributes there are special access functions defined. The return value of these functions will be bound to the record features. These features and their functions are either given in a record to the optional method feature functions. Other features and their functions are predefined in the variable PPrintRecordFns.
- map(?Xs Fn excludeSelf:ExcludeSelf level:Level mode:Mode test:Test)
The method map maps the function Fn to a number of collected score objects and returns a list with all results. Fn may also be an atom representing a unary method understood by all objects in self fulfilling Test. The method supports the features mode, level, test, and excludeSelf. These features have the same meaning as in the method collect.
- mapContainers(Xs Fn)
Maps Fn (unary function or method) over all direct containers in self.
- mapParameters(Xs Fn)
Maps Fn (unary function or method) over all direct parameters in self.
- mappend(?Xs Fn excludeSelf:ExcludeSelf level:Level mode:Mode test:Test)
The method map maps the function Fn (which must return a list) to a number of collected score objects and returns a list with all results appended. Fn may also be an atom representing a unary method understood by all objects in self fulfilling Test. The method supports the features mode, level, test, and excludeSelf. These features have the same meaning as in the method collect.
- partiallyUnify(ScoreObject Percent test:Test)
Unifies the percentage Percent of the parameter values of self with the corresponding parameter values of ScoreObject. This is useful, for example, for manually controlling the search process by saying that a given percentage of the solution of a CSP is the same as in a given previous solution (e.g., from a pickled score), and then -- given suitable continuations of this solutions -- by and by increasing this percentage.
Blocks if self or ScoreObject are not fully determined.
Args:
test (default fun {$ X} true end): a Boolean function or method which parameters to include in unification and the percentage count.
- percentageIsDet($ exclude:Exclude)
Returns a float how many percent parameters of self and its contained items are determined. The Boolean function/method Exclude can be used to exclude parameters from considering. By default, time point parameters are excluded.
- pmApply(Xs PatternMatchingExpr P)
Apply unary procedure P (expecting a list) to the sublist from Xs (a list) matching PatternMatchingExpr (a list of atoms: a single 'x' and any number of 'o' in any order). PatternMatchingExpr expresses a sublist of Xs positionally related to self (an element of Xs). The atom 'x' in PatternMatchingExpr reprents self and one or more 'o' atoms around 'x' express predecessors or successors of self in Xs. For instance, {Self patternMatchingApply([o o x] Xs P) applies P to the list consisting in the two predecessors of Self in Xs and Self itself (in that order).
PatternMatchingApply reduces to skip in case there is no matching sublist in Xs (e.g. the PatternMatchingExpr = [o x] and self is already the first element in Xs).
An exeception is raised in case self is not contained in Xs or there is no 'x' in PatternMatchingExpr.
BTW: pmApply allows to easily apply rules across container bounderies. For instance, local MyNotes={Flatten {MyMotifSeq mapItems($ getItems)}} in {ForAll MyNotes proc {$ N} {N pmApply(MyNotes [o x] MyRule)} end} end applies MyRule to all neighbouring notes nested in a sequence of motifs.
See also SMapping.patternMatchingApply.
- pmApply2(Xs PatternMatchingExpr P ElseP)
Generalised variant of pmApply: in case no sublist in Xs matches PatternMatchingExpr, PatternMatchingApply2 does _not_ reduce to skip (as pmApply) but instead applies the null-ary procedure ElseP.
See also SMapping.patternMatchingApply2.
- pmApplyTemporalAspect(PatternMatchingExpr P)
Variant of pmApply: applies P to the sublist of the elements of the temporal aspect of self which match PatternMatchingExpr.
- pmApplyTemporalAspect2(PatternMatchingExpr P ElseP)
Generalised variant of pmApplyTemporalAspect2: in case no sublist in Xs matches PatternMatchingExpr, PatternMatchingApply2 does _not_ reduce to skip (as pmApplyTemporalAspect2) but instead applies the null-ary procedure ElseP.
- removeAllFlags()
[aux method] Method should not be called by user (method removes all flags from self).
- removeFlag(F)
Removes flag F from self.
- setAllParameterUnits(ParameterAccessor Unit test:Test)
For all score objects in self (including self itself) which fulfil Test (a function or method name), the method sets the parameter unit accessible by ParameterAccessor (a function or method name) to Unit. Test defaults to isItem.
NB: ParameterAccessor must return the parameter, not the parameter value (e.g. use getPitchParameter instead of getPitch)
- setAttribute(A X)
[destructive method] Statefully sets attribute A to value X. The method is indented for editing a score after search, the search itself is indented to be fully stateless.
- setParameterValue(Param X)
[destructive method, for experts only] Statefully sets the value of parameter Param to value X (there must be an attribute Param). Remember that the search itself is indented to be fully stateless.
- toFullRecord(X exclude:Exclude unbind:Unbind)
Outputs the whole score object tree as a record with the the object label as record label and with all the object attributes and object features as record features. All attributes/features containing score objects themself are called recursively, dictionaries and extendable lists (see LUtils) are transformed to records resp. lists.
Args:
'exclude' (default nil): list of attribute names (list of atoms) recursively excluded in the output.
'unbind' (default nil): list of attribute names (list of atoms) which are output, but whose value is set to a free variable.
!! Temp: The attributes 'item' and 'containers' are always excluded to avoid endless loops. Therefore, score graphs with items having more then a single container can not be shown.
- toInitRecord($ clauses:Clauses exclude:Excluded)
Outputs the full init record for self which allows to re-create the score.
Excluded is a list of arguments (atoms) which must be excluded concurrently.
Clauses is a list of pairs TestI#FunI which can be used to overwrite the default init record creation (defined by the class' method getInitInfo) of specific score objects. TestI is a Boolean function or method, and FunI is a unary function expecting a score object and returning a record. For each object for which some TestI returns true, the corresponding FunI will be used for creating the init records for this object.
NB: toInitRecord depends on correct definitions of the method getInitInfo for all subclasses with specific inialisiation arguments.
NB: toInitRecord presently only works properly for tree-form score topologys (e.g. score graphs are not supported yet).
*
- toPPrintRecord(?X excluded:Excluded features:Features)
Method returns a record with essential data of self. The method is intended to view self uncluttered. The method feature features allows to freely select a list of score object features/attributes to include.
- unify(ScoreObject derive:Derive exclude:Exclude overwrite:Overwrite)
Effectively unifies self and ScoreObject. This method is useful for constraining various forms of repetitions. Stateful data (including class instances) can not be unified in Oz. So, unify transforms self and ScoreObject to records (using toFullRecord) and unifies those records.
Args:
'exclude' (default [startTime endTime]): list of attribute names (list of atoms) to ignore, see arg 'exclude' for toFullRecord. (The internal attributes 'parameters' and 'flags' are always excluded.)
'overwrite' (default nil): list of attribute names (list of atoms) to keep as declared in self (i.e. the setting in ScoreObject is quasi overwritten).
'derive' (default nil): for unifying derived score information (e.g., exclude the pitches, but unify pitch intervals, see example below). List of unary functions expecting the full score (self or ScoreObject) and returning a data structure to unify.
Example:
{Score1 unify(Score2
exclude:[pitch]
derive:[proc {$ MyScore Intervals}
Ps = {MyScore mapItems($ getPitch)}
in
Intervals = {Pattern.map2Neighbours Ps
proc {$ P1 P2 ?Interval}
Interval = {FD.decl}
P2 - P1 + 100000 =: Interval
end}
end])}
NB: only works properly for tree-form score topologys (because of limitation of toFullRecord).
- wait(unless:Unless)
Wait (blocks) until all parameter values of self are determined. The only exception are parameters for which the optional arg Unless -- a boolean unary function -- returns true (per default, Unless always returns false).
end
