In version 3.48 a macro and multiple file system has been incorporated into the orchestra language. This is similar to the macro system in the score language, but is independent.
Macros are textual replacements which are made in the orchestra 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
Example:
#define REVERB #ga = ga+a1
out a1#
instr 1
a1
oscil $REVERB. endin
instr 2
a1
repluck $REVERB. endin
This will get expanded before compilation into
instr 1
a1
oscil ga = ga+a1
out a1 endin
instr 2
a1
repluck ga = ga+a1
out a1 endin
This can save typing, and in the case, for example, of a general effects processing sequence, it can lead to a coherent and consistent use.
This form is limiting in at least having the variable names fixed. 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 REVERB(A) #ga = ga+$A.
out $A.#
instr 1
a1
oscil $REVERB(a1) endin
instr 2
a2
repluck $REVERB(a2) endin
to which expands
instr 1
a1
oscil ga = ga+a1
out a1 endin
instr 2
a2
repluck ga = ga+a2
out a2 endin
As with the simple macros, these macros can also be undefined with
#undef NAME
It is sometimes convenient to have the orchestra arranged in a number of files, for example with each instrument in a separate file. This style 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.
Another suggested use of #include would be to define a set of macros which are part of the composer's style.
An extreme form would be to have each instrument defines as a macro, with the instrument number as a parameter. Then an entire orchestra could be constructed from a number of #include statements followed by macro calls.
#include :clarinet:
#include :flute:
#include :bassoon:
$CLARINET(1)
$FLUTE(2)
$BASSOON(3)
It must be stressed that these changes are at the textual level and
so take no cognisance of any meaning.