File Structure of an Antescofo Score¶
Writing an augmented score through multiple files¶
A simple Antescofo augmented score is written in a single text file. However, for large scores, places where one wants to make underlying organization explicit, or places some procedures or score elements are reused in several pieces, an Antescofo augmented score may be specified in several scores.
There is always a main file from which the additional files will be loaded. The file loaded in Max/PD or used as the last argument in a standalone command task will be read as the main file.
From the main, other files are loaded using the @insert
directive:
@insert macro.asco.txt
@insert "file name with white space must be quoted"
The @insert
keyword can be capitalized (@INSERT
) as can
any other predefined @
-keyword (@local
, @target
, etc.). Beware not to confuse the @insert
directive used to include a text file at score loading time and
the @insert function.
The @insert
command is often used to store definitions
and initializations of the main Antescofo score in alternate files. So
several setups may coexist with the main score.
The @insert_once
command is similar to @insert
directive except that the file is included only once in the
current score, when the directive is encountered the first time. This
behavior makes possible to include a library of primitives in set of
files without the burden to take care of the dependencies.
Conditional parts¶
A directive
#if
; ...
#endif
#if
; ...
#else
; ...
#endif
is available to control conditionnal parsing. They delimit blocks of program text that are parsed only if a specified condition is true. These directives can be nested. The program text within the blocks is arbitrary and may consist of musical event specification, function or process definition, etc.
The condition is written after the #if
. The condition is
statically evaluated during the parsing time. If the value of the
expression is not a constant (e.g. if it depends of a variable), an
error is raised. If the condition is false (or equivalent to false),
then all lines between the #if
and the
#endif
(if the first form is used) or the
#else
(if the second form is used) are ignored.
This mechanism can be used to have several version of the same program in the same file, for instance, to initialize different setups:
@macro_def @current_setup { "SCALA" }
; ...
#if @current_setup == "SCALA"
; initialization specific to Scala
#endif
The mechanism can also be used to include some functionality depending
of the presence or the absence of a function. For example, differential
curve are not implemented in all Antescofo versions. This can be tested
by the existence of the function @ode_system
:
#if @ode_system
; here we can use differential curve
#else
; here we cannot rely on differential curve
#endif
Load and Preload Command¶
A file is loaded through a load
message sent to the Antescofo object
(in Max or PD). The argument of this message is the path of the file to
load. The effect of this command is to abort the current computations
(if any) and to load the specified file which becomes the current
score. The previous score, if any, is simply thrown away with all of its
definitions: definitions are not shared between two score loads.
A file can also be preloaded using the command preload file name
. The
file
argument is the path of a file while name
is a simple identifier
to refer to the score in future command.
NOTA BENE:
the use of the preload command is deprecated. For new pieces, it is better
to use file inclusion facilities and commands antescofo::visitlabel
or antescofo::startfromlabel
to
move into the score.
Preloaded scores are used to defines functions, processes, actors, data structures: the definitions in a preloaded score are added to the currently known definitions. So they are in use for the next preloads and for the (final) load. A preload does not define a current score. So, the usual workflow is to preload a set of files with a final load.
Preloaded scores can also contain definitions of musical events to
follow. During the program execution, one can switch from the current
score to the score defined by a preloaded score using the start name
command with name
refering to a preloaded score. A
start
command without name simply starts the current score.
The start name
command can be issued from the Antescofo program
itself using the antescofo::start
action. This will keep
the program state (variables values, processes, etc.) but divert the
listening machine to follow the new specified score.