13.1 #def ine, $NA M E, #undef

#define

#define

#define

#define NAME # replacement text #

#define

#define

#define

#define NAME(a’ b’ c’) # replacement text #

$NAME.

$NAME.

$NAME.

$NAME.

#undef

#undef

#undef

#undef NAME

D

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 the characters # and $ to define and call macros. This can save typing, and can lead to a coherent structure and consistent style. This is similar to, but independent of, the macro system in the score language.

#define NAME – defines a simple macro. The name of the macro must begin with a letter and can consist of any combination of letters and numbers. Case is significant. This form is limiting, in that the variable names are fixed. More flexibility can be obtained by using a macro with arguments, described below.

#define NAME(a’ b’ c’) – defines a macro with arguments. This can be used in more complex situations. The name of the macro must begin with a letter and can consist of any combination of letters and numbers. 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 may be any choice of letters.

Remember that case is significant in macro names.

$NAME. – calls a defined macro. To use a macro, the name is used following a $ character. The name is terminated by the first character which is neither a letter nor a number. If it is necessary for the name not to terminate with a space, a period, which will be ignored, can be used to terminate the name. The string, $NAME., is replaced by the replacement text from the definition. The replacement text can also include macro calls.

#undef NAME – undefines a macro name. If a macro is no longer required, it can be undefined with #undef NAME.

I

# replacement text # – The replacement text is any character string (not containing a #) and can extend over multiple lines. The replacement text is enclosed within the # characters, which ensure that additional characters are not inadvertently captured.

P

Some care is needed with textual replacement macros, as they can sometimes do strange things. They take no notice of any meaning, so spaces are significant. This is why, unlike the C programming language, the definition has the replacement text surrounded by # characters. Used carefully, this simple macro system is a powerful concept, but it can be abused.

The Public Csound Reference Manual Version 4.10 Instrument Control: Macros Page 13-2

E

Simple Macro

#define

#define

#define

#define REVERB #ga = ga+a1 out

out out out a1#

instr instr instr instr 1 a1 osciloscilosciloscil $REVERB.

endin endin endin endin instr instr instr instr 2 a1 repluckrepluckrepluckrepluck $REVERB.

en en en endindindindin

This will get expanded before compilation into:

instr instr instr instr 1 a1 osciloscilosciloscil

ga = ga+a1

out out out out a1 endin endin endin endin instr instr instr instr 2 a1 repluckrepluckrepluckrepluck

ga = ga+a1

out out out

out a1 endin

endin endin endin Macro With Arguments

#define REVERB(A) #ga = ga+$A.

out $A.#

instr instr instr instr 1 a1 osciloscilosciloscil $REVERB(a1)

endin endin endin endin instr instr instr instr 2 a2 repluckrepluckrepluckrepluck $REVERB(a2)

endin endin endin endin

This will get expanded before compilation into:

instr instr instr instr 1 a1 osciloscilosciloscil

ga = ga+a1

out out out out a1 endin endin endin endin instr instr instr instr 2 a2 repluckrepluckrepluckrepluck

ga = ga+a2

out out out out a2 endin endin endin endin

A

John ffitch

University of Bath/Codemist Ltd.

Bath, UK

April, 1998 (New in Csound version 3.48)

The Public Csound Reference Manual Version 4.10 Instrument Control: Macros Page 13-3

13.2 # i n cl u d e

#include

#include

#include

#include “filename”

D

:

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. The file name can include a full path.

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

#include

#include

#include “clarinet”

#include

#include

#include

#include “flute”

#include

#include

#include

#include “bassoon”

$CLARINET(1)

$FLUTE(2)

$BASSOON(3)

It must be stressed that these changes are at the textual level and so take no cognizance of any meaning.

A

John ffitch

University of Bath/Codemist Ltd.

Bath, UK

April, 1998 (New in Csound version 3.48)

The Public Csound Reference Manual Version 4.10 Instrument Control: Macros Page 13-4 This page intentionally left blank.

The Public Csound Reference Manual Version 4.10 Instrument Control: Program Flow Control Page 14-1

14 I ^NSTRUMENT C ^ONTROL : P ^ROGRAM