Brain Imaging & Analysis Center

When CIGAL command lines are read, before they are passed to the command line parser (where they are checked for syntax and deciphered) they first go to the program's preprocessor. The preprocessor's only task is to check whether any words on the command line are in the table of words created by the DEFINE command (see DEFINE(2)). The DEFINE table contains pairs of character strings; when the first string in the pair appears in a command, it is replaced by the second string. These substitutions can involve simply replacing one whole string for another, or they can take the form of pseudo-functions in which case arguments to the first string may be rearranged during the substitution.

For example, if you define:

     define 'cwindow'      '^^7'          ; alias for the cursor window
     define 'pi'           '3.14159'
     define 'func(a,b)'    'sqrt(a*2)*sin(a)+b'

then the preprocessor would perform the following substitutions:

     cwindow = ^^2            -->    ^^7 = ^^2
     a = cwindow(1,0)         -->    a = ^^7(1,0)
     rotate vecs pi/2 0 0     -->    rotate vecs 3.14159/2 0 0
     func(x,3*pi)             -->    sqrt(x*2)*sin(x)+3*3.14159
     func 20 cwindow(1,1)     -->    sqrt(20*2)*sin(20)+^^7(1,1)

Notice in the last example that the parentheses for pseudo-functions are Optional. The preprocessor knows how many arguments a string should have, so if there are no parentheses it just assumes that the next words on the line are the arguments it needs.

Using the preprocessor to substitute defined strings has several advantages. First, the substitutions provide useful mnemonics, allowing you to assign names to values or phrases that make them easier to remember. Second, naming a parameter with a DEFINE statement makes it easy to change every instance of that parameter simply by changing the DEFINE; this is particularly useful when writing macro programs. Third, the preprocessor is an efficient way of defining short functions. It is faster than running a specialized macro and doesn't require creating an extra file.

The one disadvantage with the preprocessor is that every word on every command line must be looked up in the table of DEFINE'd strings. If you define a lot of strings this can bog down command execution, particularly when running interpreted macros. This is not a problem when you define strings within a macro that is to be compiled, because the preprocessor substitutions are all taken care of when the lines are parsed during compilation; these steps are skipped during macro execution (see COMPILER(1)). The solution therefore is to only create as many global DEFINE strings as you are really likely to use, and to compile macros that you want to run efficiently.

See Also:
CIGAL Home, CIGAL Manual, Topics List, Manual Help