Lexical Elements of an Antescofo Score¶
Elements of the language can be categorised into six groups, corresponding to various constructions permitted in the language:
-
Comments: Any text starting by a semi-colon
;
or//
is considered as comment and ignored by parser until the end of line (inline comment).Block (multi-line) C-Style comments starting with
/*
and ending with*/
are allowed. -
Keywords: are reserved words introducing either Events or Action constructions. Examples include
Note
(for events) andGroup
(for compound actions). -
Simple identifiers: denote Max or PD receivers. They are also used to specify the label of a musical event or the label of an action.
-
$-identifiers: are words that start with
$
character. They correspond to user-defined variables or parameters in functions, processes, object or macro definitions. -
::-identifiers: words starting with
::
,obj::
,pattern::
ortrack::
corresponding respectively to processes, objects, patterns or tracks. -
@-identifiers: are words starting with a
@
. They eiher introduce a new definition or denote predefined and user-defined functions, user-defined macros, or action or event attributes.
User defined score elements like macros, processes, objects, tracks and
functions can only be used after their definition in the score. We
suggest putting them at the beginning of the file or to put them in a
separate file using the @insert
command. They will be discussed in
later chapters.
Case-Sensitive and case-Unsensitive Identifiers¶
Identifiers are sometimes case-sensitive and sometimes case unsensitive. The rule is simple: reserved keyword or predefined identifiers are case unsensitive. User introduced identifiers and predefined function names are case sensitive.
Comments¶
Block comments are in the C-style and cannot be nested:
/* comment split
on several lines
*/
// comment until the end of the line
; comment until the end of the line
In this document, we use railroad diagrams to give a more precise description of the syntax. The railroad diagram specifying comment's syntax is:
Comments are ignored by the interpreter but not suppressed in normal processing. That is, they act usually as separators, i.e.
$x/**/y
is read as two consecutive tokens $x
and y
. However, during
macro-expansion comments are suppressed (not ignored) in the textual
expansion: in a macro-expansion, the previous fragment is read as only
one token $xy
by the interpreter (see chapter Macros).
Indentation¶
Tabulations are handled like white spaces. Columns are not meaningful so you can indent program as you wish. However, some constructs must end on the same line as their “head identifier”: event specification, internal commands and external actions (like Max message or OSC commands).
For example, the following fragment raises a parse error:
NOTE
C4 0.5
1.0s print
"message to print"
NOTE
and because the argument of print
is
not on the same line). But this one is correct:
Note C4 0.5 myLab
Note C4 0.5 "some label with white space used to document the score"
1.0s
print "this is a Max message (to the print object)"
print "printed 1 seconds after the event Note C4..."
1.0s
but ends on the same line as its “head identifier”,
achieving one of the customary indentations used for cue lists.
Splitting a line¶
A backslash before an end-of-line can be used to specify that the next line must be considered as the continuation of the current line. It allows for instance to split the list of the arguments of a message on several physical rows:
print "this two" "messages" "are equivalent"
print "this two" \
"messages" \
"are equivalent"
Reserved Keywords¶
Reserved keywords can be divided in two groups:
-
Event Keywords including
NOTE
,CHORD
,TRILL
,BPM
, etc., introduce musical events (see chapter Events) and are used to describe the music score to be recognised. -
Action Keywords, such as
GROUP
,LOOP
and more, specify computations that can be instantaneous (Atomic actions) or containers for other actions that have a duration (Compound actions).
The current list of reserved keywords is :
abort action and atbefore bind bpmcase chord closefile curvedo duringelse event exprfalse forallgfwd grouphookif imap injumpkilllet lfwd loopmap ms multinapro_trace noteof off on openoutfile
oscoff oscon oscrecv
oscsendparfor patch ports start state stop
switch symbtab tempo transpose trill trueuntilvalue variancewhenever where while withNotice that event keywords always occur at the top-level of the text score. Reserved keywords are case unsensitive, that is,
note
NOTE
Note
NoTe
notE
refers to the same identifier. However simple identifiers which are not reserved keywords are case sensitive.
Simple Identifiers : Antescofo keywords and references to the host environment¶
Simple identifiers are sequence of characters accepted by one of the three following regular expressions and that are not reserved keywords:
[[:alpha:]_#'!~\xc3\xe2\x80-\xbf][[:alnum:]_#'/.?!+~><\-\Xc3\xe2\x80-\xbf]* [0-9]+[[:alpha:]_'\xc3\xe2\x80-\xbf-]{2,}[[:alnum:]_#?'!~*/+.\-\xc3\xe2\x80-\xbf]* [0-9]+[a-rA-Rt-zT-Z]+
[:alpha:]
represents an alphabetic character,[:alnum:]
represents an alphanumeric character, i.e.[0-9a-zA-Z]
and the hexadecimal range\xc3\xe2\x80-\xbf
represents a raisonable subset of UTF-8 accentuated characters and printable symbols.These identifiers are much more general than the identifiers
[:alpha:][:alnum:]*
usually recognized in programming language. For example they can start by a number or include a relational operator like<
, in order to represent the various Max or PD receivers found in current patches (identifier starting with a number are common when working with Max poly). It is however possible to encounter Max receivers that are not caught by the above regular expressions. In this case, just use astring
instead of a simple identifier, for the receiver. For instance"max receiver with white spaces" 1 2 3
refers to a receiver whose name includes white spaces.
$-identifiers : Variables¶
$-identifiers like
$id
,$id_1
are simple identifiers prefixed with a dollar sign. Only!
?
.
and_
are allowed as non-alphanumeric characters. $-identifiers are used to give a name to variables and for function, process and macro definition arguments. They are case-sensitive.You can learn more on expressions and variables in chapter Expressions.
::-identifiers : Processes¶
::-identifiers like
::P
or::q1
are simple identifiers prefixed with two semicolons. ::-identifiers are used to give a name to processus (see chapter Processes).Other ::-identifiers have a prefix before the
::
and are used to give a name to various entities:@-identifiers : Functions, Macros, and Attributes¶
A word preceded immediately with a ‘@’ character is called a @-identifier. Only
!
?
.
and_
are allowed as non alphanumeric characters after the@
.They have four purposes in Antecofo language. Note that in the first three cases, @-identifiers are case unsensitive, that is
@tight
,@TiGhT
and@TIGHT
are the same keyword.Parsing directives¶
Some commands affect directly the parsing of a file:
the
@insert
command is used to insert another file,the
@insert_once
command is used to insert another file if it has not been already inserted;the command
@uid
generates on-the-fly a new (fresh) variable ($-identifier)the
@lid
command generate on-the-fly the las generated identifiersDefinitions¶
The following @-identifiers are used to introduce new definitions:
@abort
specifies an abort handler linked to a compound action,
@broadcast
introduces a broadcast method in an object definition,
@fun_def
defines a new function or a function-method attached to an object,
@init
introduces a new init section in an object definition,
@obj_def
specifies a new object definition,
@pattern_def
declares a new pattern to be used in awhenever
@proc_def
starts a process or process-method definition
@track_def
declares a new track
@whenever
defines a reaction
@macro_def
is used to define new macros.Events Attributes and Actions Attributes¶
Here is a list of the reserved @-identifiers used to specify an attribute of an action or an event. These @-identifers are case unsensitive.
@abort @action @ante @back @back_in @back_in_out @back_out @bounce @bounce_in @bounce_in_out @bounce_out @circ @circ_in @circ_in_out @circ_out @coef @command @conservative @cubic @cubic_in @cubic_in_out @cubic_out @date @dsp_channel @dsp_cvar @dsp_inlet @dsp_link @dsp_outlet @dump @elastic @elastic_in @elastic_in_out @elastic_out @eval_when_load @exclusive @exp @exp_in @exp_in_out @exp_out @fermata @global @grain @guard @hook @immediate @inlet @is_undef @jump @kill @label @latency @linear_in @linear_in_out @linear_out @local @loose @modulate @name @norec @pizz @plot @post @progressive @quad @quad_in @quad_in_out @quad_out @quart @quart_in @quart_in_out @quart_out @quint @quint_in @quint_in_out @quint_out @rdate @refractory @rplot @sine @sine_in @sine_in_out @sine_out @staccato @staticscope @sync @target @tempo @tempovar @tight @transpose @type
Naming Functions and Macros¶
@-identifiers are used to give a name to predefined functions, user-defined functions or user-defined macros. These predefined or user-introduced @-identifiers are case sensitive.
@<*+!...¶
@|| @!= @% @&& @* @+ @- @/ @< @<= @== @> @>=
@A...¶
@abs @acos @active @active_mac_addresses @add_pair @aggregate @align_breakpoints [@always_next_event_except_sil_pos] @applytab @applytab_lax @approx @arch_darwin @arch_linux @arch_windows @asin @atan @atan2
@B...¶
@bach_score @base2i @beats_in_seconds_from_now @between @binary_search @bit_and @bit_or @bit_shiftl @bit_shiftr
@C...¶
@callback_all_event @callback_next_event @callback_start_fastforward @callback_start_logical_instant @callback_stop @callback_stop_fastforward @callback_stop_logical_instant @car @cdr @ceil @char_is_alnum @char_is_alpha @char_is_ascii @char_is_blank @char_is_cntrl @char_is_digit @char_is_graph @char_is_lower @char_is_print @char_is_punct @char_is_space @char_is_upper @char_is_xdigit @clear [@clone] @compilation [@compose] @concat @concat_nim @configuration_arch @configuration_audiosample [@configuration_compiler_name] [@configuration_compiler_version] @configuration_faust [@configuration_odeint] @configuration_release @configuration_target_architecture @cons @copy @cos @cosh @count @current_event @current_load_directory
@D...¶
@dim @directory_read @domain @drop @dumpvar
@E...¶
@empty @erf @erfc [@error] @event_label_position @exe_child_of @exe_parent @exp [@exp2] @explode
@F...¶
@filter_max_t @filter_median_t @filter_min_t @find @flatten @floor
@G...¶
@H...¶
[@has_apply] @host_date [@hypot] @hz2midi @hz2midicent @hz2symb
@I...¶
[@i2base] [@ideal_beat2sec] [@ideal_sec2beat] [@ideal_tempo] @info @insert [@integrate0] [@integrate_symb] [@inverse_symb] @iota [@is_applicable] [@is_applicable_exe] @is_bool @is_defined @is_exec @is_fastforward @is_fct @is_float @is_following_on [@is_fun] @is_function [@is_inf] [@is_initialized] @is_int @is_integer_indexed @is_list @is_map [@is_nan] [@is_Napplicable] @is_nim [@is_not_initialized] @is_numeric @is_obj [@is_paf] @is_paused @is_playing_on @is_prefix @is_proc @is_running @is_stopped @is_string [@is_string_or_symb] @is_subsequence @is_suffix @is_symbol @is_tab @is_undef @is_vector
@J...¶
[@j0] [@j1] @json_read @json_string @json_write
@K...¶
@knn_combine @knn_create @knn_delete @knn_rcombine @knn_rebuild @knn_rnd @knn_rscan @knn_rsearch @knn_scan @knn_search
@L...¶
@lace @last [@lgamma] [@linear_approx] @linearize @listify [@lnow] @loadvalue @loadvar @local_beat_position @local_tempo @log @log10 @log2 @logical_date
@M...¶
@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 @map @map_compose @map_concat @map_reverse @mapval @max @max_absolute_path @max_key @max_patch_path @max_val @median @member @merge @midi2hz @midi_getChannel @midi_getCommand @midi_getCommandByte @midi_getMetaType @midi_isAftertouch @midi_isController @midi_isEndOfTrack @midi_isMeta @midi_isNote @midi_isNoteOff @midi_isNoteOn @midi_isPatchChange @midi_isPitchbend @midi_isPressure @midi_isTempo @midi_read @midi_track2ascii @midicent2hz @min @min_key @min_val [@my_ip_addresses]
@N...¶
[@nan] [@next_event_except_sil_pos] [@next_event_with_sil_pos] [@next_sil_pos] @nim2vezer [@nimify] @normalize @number_active
@O...¶
@occurs [@odei_map_function] @optional_attributes
@P...¶
@parse @performance_data [@performance_tempo] @permute @pow @print [@priority] @projection @push_back @push_front @pwd
@R...¶
@r_compile @r_findall @r_match @r_search @rand @rand_int @random @range @read_file @reduce [@remainder] @remove @remove_duplicate @replace @reshape @resize @reverse @rnd_bernoulli @rnd_binomial [@rnd_cauchy] [@rnd_chi_squared] @rnd_exponential @rnd_gamma @rnd_geometric [@rnd_lognormal_distribution] [@rnd_negative_binomial] @rnd_normal [@rnd_poisson] @rnd_uniform_float @rnd_uniform_int [@rnd_weibull] @rotate @round
@S...¶
@sample @savevalue [@scale_x] [@scale_y] @scan @score_duration @score_tempi @scramble @seconds_in_beats_from_now @select_map @send_message @set_max_message_sent_instantaneously @set_osc_handling_double @set_osc_handling_int64 @set_osc_handling_tab @shape @shift_map @simplify_lang_v @simplify_radial_distance_t @simplify_radial_distance_v @sin @sinh @size @slice @solve_ode @solve_ode_dispose @solve_ode_init @solve_ode_system @sort @specified_duration @split @sputter @sqrt @string2fun @string2obj @string2proc @strip_path @stutter @succession @symb2midicent @system
@T...¶
@take @tan [@tanh] @tgamma @time @to_num @Tracing [@type_of] @typecheck
@U...¶
@UnTracing @usage_resident_memory_size @usage_statistics @usage_virtual_memory_size @user_directory
@W...¶
[@window_filter]
@X...¶
@Y...¶
@_...¶
[@_sleep] [@_yield] [@_terminate] [@_print] [@_thread_qos] [@_gotcha]