Starting with the 3.48 version, Csound introduces a number of changes in the language in which scores are presented to the system. These are all upward compatible, and so do not require any changes in existing scores. These changes should allow for simpler score writing, and provide an elementary alternative to the full score-generation systems. Similar changes have been made in the orchestra language.
Macros are textual replacements which are made in the score as it is being read. The macro system in Csound is a very simple one, and uses two special characters to indicate the presence of macros, the characters # and $.
To define a macro one uses the # character.
#define NAME # replacement text#
The name of the macro can be any made from letters, upper or lower case. Digits are not allowed. The replacement text is any character string (not containing a #) and can extend over more than one line. The replacement text is enclosed within the # characters, which ensures that additional characters are not inadvertently captured.
To use a macro the name is used following a $ character. The name is terminated by the next non-letter. If the need is to have the name without a space a period can be used to terminate the name, which is ignored. The string $NAME. is replaced by the replacement text from the definition. Of course the replacement text can also include macro calls.
If a macro is not required any longer it can be undefined with
#undef NAME
If a note-event has a set of p-fields which are repeated
#define ARGS # 1.01 2.33 138#
i1 0 1 8.00 1000 $ARGS
i1 0 1 8.01 1500 $ARGS
i1 0 1 8.02 1200 $ARGS
i1 0 1 8.03 1000 $ARGS
This will get expanded before sorting into:
i1 0 1 8.00 1000 1.01 2.33 138
i1 0 1 8.01 1500 1.01 2.33 138
i1 0 1 8.02 1200 1.01 2.33 138
i1 0 1 8.03 1000 1.01 2.33 138
This can save typing and is easier to change if for example one needed to change one of the parameters. If there were two sets of p-fields one could have a second macro (there is no real limit on the number of macros one can define).
#define ARGS1 # 1.01 2.33 138#
#define ARGS2 # 1.41 10.33 1.00#
i1 0 1 8.00 1000 $ARGS1
i1 0 1 8.01 1500 $ARGS2
i1 0 1 8.02 1200 $ARGS1
i1 0 1 8.03 1000 $ARGS2
An alternative would be to use the second form of the macro, described below.
Note: some care is needed with textual macros as they can sometimes do strange things. They take no notice of any meaning, and so spaces are significant, which is why the definition has the replacement text surrounded by # characters, unlike that in the C programming language. Used carefully simply macros are a powerful concept, but they can be abused.
Macros can also be defined with parameters. This can be used in more complex situations. In order to define a macro with arguments the syntax is
#define NAME(A#B#C) #replacement text#
Within the replacement text the arguments can be substituted by the
form $A. In fact the implementation defines the arguments as simple
macros. There may be up to 5 arguments, and the names can be any
choice of letters. Case is significant in macro names. In use the
argument form for example:
#define ARG(A) # 2.345 1.03 $A
234.9#
i1 0 1 8.00 1000 $ARG(2.0)
i1 + 1 8.01 1200 $ARG(3.0)
which expands to
i1 0 1 8.00 1000 2.345 1.03 2.0
234.9
i1 + 1 8.01 1200 2.345 1.03 3.0
234.9
As with the simple macros, these macros can also be undefined with
#undef NAME
When writing a complex score it is sometimes all too easy to forget to what the various instrument numbers refer. One can use macros to give names to the numbers. For example
#define Flute #i1#
#define Whoop #i2#
$Flute. 0 10
4000 440
$Whoop. 5 1
It is sometimes convenient to have the score in more than one file. This use is supported by the #include facility which is part of the macro system. A line containing the text
#include :filename:
where the character : can be replaced by any suitable character. For most uses the double quote symbol will probably be the most convenient.
This takes input from the named file until it ends, when input reverts to the previous input. There is currently a limit of 20 on the depth of included files and macros.
A suggested use of #include would be to define a set of macros which
are part of the composer's style. It could also be used to provide
repeated sections.
s
#include :section1:
;; Repeat that
s
#include :section1:
However there is an alternative way of doing repeats, described below.
Sections can be repeated by using #include or by editing the text. An alternative is the new r directive in the score language.
r3 NN
starts a repeated section, which lasts until the next s, r or e directive. The section is repeated 3 times in this example. In order that the sections may be more flexible than simple editing, the macro NN is given the value of 1 for the first time through the section, 2 for the second, and 3 for the third. This can be used to change p-field parameters, or indeed ignored.
Warning: because of serious problems of interaction with macro expansion,
sections must start and end in the same file, and not in a macro.
In earlier versions of Csound the numbers presented in a score were
used as given. There are occasions when some simple evaluation would
be easier. This need is increased when there are macros. To
assist in this area the syntax of an arithmetic expressions within square
brackets [] has been introduced. Expressions built from the operations
+, -, *, and / are allowed, together with grouping with (). The expressions
can include numbers, and naturally macros whose values are numeric or arithmetic
strings. All calculations are made in floating point numbers.
Note that unary minus is not yet supported.
r3 CNT
i1 0
[0.3*$CNT.]
i1 +
[($CNT./3)+0.2]
e
As the three copies of the section have the macro $CNT. with the
different values of 1, 2 and 3, this expands to
s
i1 0
0.3
i1 0.3 0.533333
s
i1 0
0.6
i1 0.6 0.866667
s
i1 0
0.9
i1 0.9 1.2
e
This is an extreme form, but the evaluation system can be used to ensure
that repeated sections are subtly different.