@optional_attributes() => [ [position, attribute, val]* ]
@optional_attributes("string") => [ [position, val]* ]
@optional_attributes("string", val) => [position]*
@optional_attributes(position) => [ [string, val]* ]
@optional_attributes(position, string) => [val] or [] if no such attribute
This is an experimental feature
Arbitrary attributes may be defined on a musical event. These attributes
associates a value (defined by an arbitrary expression) to an arbitrary
name (in the form of a symbol or a string). The function @optional_attributes()
is used to query these attributes.
The syntax to define these optionnal attribute is as folows:
NOTE C4 1 @attribute key1
NOTE B2 1/2 @attribute "key2"
CHORD (B2 C4 D3) 1/4 @attribute key3 := expression
TRILL (B2 C4 D3) 3/2 @attribute "key4" := expression
EVENT 3 @attribute{ key, "key2", keyWithValue := val2, "kkk" := VAl3, ... }
<undef>
. Form 3 and 4 associate a value to a
key and the last line shows the general syntax used to associates
several attributes to an event.
The function @optional_attributes()
is used to retrieve
the key/value. The event is specified through its position (in
beat). The expression defining the values are evaluated when the score
is loaded and a call to @optional_attributes()
may
appears anywhere.
Example:
// Optional attribute can be query at any time during
// the execution: the association of an attribute to an
// event is done when the score is loaded, i.e. before
// the execution.
$res := @optional_attributes()
@assert $res.size() == 6
@assert $res.member([0, "RED", <undef>])
@assert $res.member([2, "BLUE", <undef>])
@assert $res.member([2, "RED", <undef>])
@assert $res.member([3, "BLUE", <undef>])
@assert $res.member([3, "first coloratur", "none"])
@assert $res.member([3, "octave", 1])
$res := @optional_attributes("RED")
@assert $res.size() == 2
@assert $res.member([0, <undef>])
@assert $res.member([2, <undef>])
$res := @optional_attributes("octave")
@assert $res.size() == 1
@assert $res.member([3, 1])
$res := @optional_attributes("octave", 0)
@assert $res.empty()
$res := @optional_attributes("octave", 1)
@assert $res.size() == 1
@assert $res.member(3)
$res := @optional_attributes(1)
@assert $res.empty()
$res := @optional_attributes(2)
@assert $res.member([2.0, "BLUE", <undef>])
@assert $res.member([2.0, "RED", <undef>])
$res := @optional_attributes(3, "first coloratur")
@assert $res == ["none"]
$res := @optional_attributes(3, "octave")
@assert $res == [1]
$res := @optional_attributes(3, "BLUE")
@assert $res == [<undef>]
$res := @optional_attributes(3, "TicToc")
@assert $res == []
NOTE C1 1.0 @attr::RED
NOTE D4 1
NOTE C2 1 @attr::{RED, BLUE}
NOTE C3 1 @attr::{ octave := 1, "first coloratur" := "none", BLUE }
NOTE D5 1
See also: Score Introspection
[@always_next_event_except_sil_pos] @bach_score @current_event @event_label_position @make_bpm_map @make_bpm_tab @make_duration_map @make_duration_tab @make_label_bpm @make_label_duration @make_label_pitches @make_label_pos @make_pitch_tab @make_score_map [@next_event_except_sil_pos] [@next_event_with_sil_pos] [@next_sil_pos] @optional_attributes @performance_data @score_duration @score_tempi @specified_duration