Input File Preprocessing

Macros (Text-Based)

Format:

#define MacroName #body#
OR
#define MacroName(argument1'argument2'...'argumentN) #$argument1 $argument2, etc.#
OR
#define MacroName(argument1#argument2#...#argumentN) #$argument1 $argument2, etc.#

Description

nGen includes a text-based macro pre-processor that is modeled on that found in the canonical version of Csound. Like Csound's macros, this implementation is text only (doesn't recognize numerical values as such). Macros are evaluated before the main program parses any information and can be quite complex. Because of their potential complexity, macros can be expanded and written to an output file (use the -x option). This file is a valid text input file for nGen -- if your macros get complicated you may wish to refer to the expansion file (or even use it as input to the program...). Here are some macro examples followed by general comments on syntax.

You can define a macro using the #define directive. Macros may be deleted from memory using the #undef directive (you only need to do this if you would like to use the macro name again but with new contents).


#define V1                   #0# 
#define V2                   #100# 
#define Range1               #[g $V1 $V2]# 
#define Range2               #[b $V1 $V2]# 
#define mo(percent'low'high) #mo(T*$percent 1. $low $high)#

Now to call the "mo" macro:

$mo(.5'$Range1'$Range2) 
/* can also be called like this:$mo(.5#$Range1#$Range2) */

Expands to:

mo(T*.5 1. [g 0 100] [b 0 100])

Now, to remove the macro from memory (you need only do this when redefining the contents of a predefined macro name):

#undef mo

Notes on Macro Syntax:

Macro names are case sensitive, must start with a character and may contain alpha-numeric characters as well as the underscore (_).
Macros may contain other macros, but these must be defined before the current macro.
Macros must be declared using the "#define" directive.
The macro body must be enclosed in #s (note that the macro is replaced by the text with #s (including white space)).
Macros are called using the name preceded by the "$" character (e.g., $macro).
Macro names and bodies may be up to 1024 characters. The body may contain newlines (hard returns).
You may format anyway you wish between the "#define", name, body, and argument names (white space or returns).
Macros may have up to 30 arguments (these may be up to 1024 characters each and may include macro names but may not include other macros with arguments).
Macro arguments must be separated by the ' or # characters.

Include Files

Often it is nice to put frequently used items in a separate "include" file. When specifying an existing file name with the #include directive, nGen will copy the file directly into the current file before parsing the current file. For example:

#include |macros.txt|

will copy the file "macros.txt" (in the current directory or folder) and will insert it starting at the # sign. Include files may also contain their own include directives (recursion). When recursive includes are used, there is a limit of 12 files on the depth of the recursion. The file- or path-name must be enclosed in |s.

Path names

Include files may reside anywhere on your computer. Under DOS, for example, the following includes the file "macros.txt" residing in a separate directory or folder:

#include |C:/ngen/includes/macros.txt|

On the Macintosh this will look something like this:

  #include |Macintosh HD:ngen stuff:includes:macros.txt|

On all platforms except the Macintosh GUI, the "/" character is used to separate directories (folders). On these systems the forward slash (/)should be used but under DOS/Windows the backslash (\) may also be used. If a path name does not precede the file name, it will attempt to look for it in the current working directory.

Spaces are allowed in file names, which can be up to 255 characters (spaces must match the actual path and/or file name exactly as it is on your system). For extremely long file names you may put a carriage return in the file name but it must be an extra character (in addition to any spaces).

Macintosh GUI version (Mac-nGen)

On the Macintosh the ":" character is used to separate folders. In the Macintosh version, the full path must always be specified. Unfortunately, this means that several of the example files will have to be hand-edited with machine-specific path names in order for them to run properly.