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) and Group (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:: or track:: 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
          */
Line-comments are in the C-style and also in the Lisp style: 
          // 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 $xand 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"
(because the pitch and the duration of the note does not appear on the same line as the keyword 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..."
Note that the first 'print' message is indented after the specification of its delay 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   at  
before   bind   bpm  
case   chord   closefile   curve  
do   during  
else   event   expr  
false   forall  
gfwd   group  
hook  
if   imap   in  
jump  
kill  
let   lfwd   loop  
map   ms   multi  
napro_trace   note  
of   off   on   openoutfile  
oscoff   oscon   oscrecv  
oscsend  
parfor   patch   port  
s   start   state   stop  
switch   symb  
tab   tempo   transpose   trill   true  
until  
value   variance  
whenever   where   while   with  

Notice 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 a string 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:

  • obj:: identifies Objects

  • track:: identifies Tracks

  • pattern:: identifies Patterns]

@-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 identifiers

Definitions

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 a whenever

  • @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.

@<*+!...

@!=

@%

@&&

@!=

@%

@&&

@*

@+

@-

@<

@<=

@==

@>

@>=

@div

@||

@+

@-

@<

@<=

@==

@>

@>=

@div

@||

@A

@abs

@acos

@active

@add_pair

@aggregate

@align_breakpoints

@approx

@arch_darwin

@arch_linux

@arch_windows

@asin

@atan

@atan2

@B

@bach_score

@between

@bit_and

@bit_or

@bit_shiftl

@bit_shiftr

@bounded_integrate

@bounded_integrate_inv

@C

@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

@compilation

@concat

@configuration_arch

@configuration_audiosample

@configuration_debug

@configuration_faust

@configuration_host

@configuration_release

@configuration_target_architecture

@cons

@copy

@cos

@cosh

@count

@current_load_directory

@D

@dim

@directory_read

@domain

@drop

@dump

@dumpvar

@E

@empty

@exe_child_of

@exe_parent

@exp

@explode

@F

@filter_max_t

@filter_median_t

@filter_min_t

@find

@flatten

@floor

@G

@gnuplot

@gshift_map

@H

@history_length

@host_date

@hz2midi

@hz2midicent

@hz2symb

@I

@insert

@integrate

@iota

@is_bool

@is_defined

@is_exec

@is_fastforward

@is_fct

@is_float

@is_following_on

@is_function

@is_int

@is_integer_indexed

@is_interpolatedmap

@is_list

@is_map

@is_nim

@is_numeric

@is_obj

@is_obj_xxx

@is_paused

@is_playing_on

@is_prefix

@is_proc

@is_running

@is_stopped

@is_string

@is_subsequence

@is_suffix

@is_symbol

@is_tab

@is_undef

@is_vector

@J

@json_string

@json_read

@json_write

@K

@knn_create

@knn_rebuild

@knn_delete

@knn_rnd

@knn_search

@knn_rsearch

@knn_scan

@knn_rscan

@knn_combine

@knn_rcombine

@L

@lace

@last

@linearize

@listify

@loadvalue

@loadvar

@log

@log10

@log2

@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_score_map

@map

@map_compose

@map_concat

@map_history

@map_history_date

@map_history_rdate

@map_normalize

@map_reverse

@mapval

@max

@max_absolute_path

@max_patch_path

@max_key

@max_val

@median

@member

@merge

@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

@midi2hz

@midicent2hz

@min

@min_key

@min_val

@N

@nim2vezer

@normalize

@number_active

@O

@occurs

@ode_solve

@P

@parse

@permute

@plot

@pow

@projection

@push_back

@push_front

@pwd

@R

@r_compile

@r_findall

@r_match

@r_search

@rand

@rand_int

@random

@range

@read_file

@reduce

@remove

@remove_duplicate

@replace

@reshape

@resize

@reverse

@rnd_bernoulli

@rnd_binomial

@rnd_exponential

@rnd_gamma

@rnd_geometric

@rnd_normal

@rnd_uniform_float

@rnd_uniform_int

@rotate

@round

@rplot

@S

@sample

@savevalue

@scan

@score_duration

@score_tempi

@scramble

@select_map

@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

@sort

@specified_duration

@sputter

@sqrt

@string2fun

@string2proc

@strip_path

@stutter

@succession

@symb2midicent

@system

@T

@tab_history

@tab_history_date

@tab_history_rdate

@take

@tan

@tgamma

@time

@to_num

@Tracing

@typecheck

@U

@UnTracing

@usage_resident_memory_size

@usage_statistics

@usage_virtual_memory_size

@user_directory

@W

@window_filter_t

@X

@xml_read

@xml_string