"Sputnik" help  
Sputnik Help
Language Reference - Preprocessor - Object-like Macros

Object-like Macros

An object-like macro is a simple identifier which will be replaced by a code fragment. It is called object-like because it looks like a data object in code that uses it. They are most commonly used to give symbolic names to numeric constants.

You create macros with the ‘#define’ directive. ‘#define’ is followed by the name of the macro and then the token sequence it should be an abbreviation for, which is variously referred to as the macro’s body, expansion or replacement list. For example,

#define STR_SIZE 20

This defines a macro named STR_SIZE which expands to 20 when used. If somewhere after this ‘#define’ directive there comes a C statement of the form

#define STR_SIZE 20
say StrNew(STR_SIZE, 'a');
// PRINTS
// aaaaaaaaaaaaaaaaaaaa

The Sputnik preprocessor will recognize and expand the macro STR_SIZE. The Sputnik parser will see the same tokens as it would if you had written

say StrNew(20, 'a');
// PRINTS
// aaaaaaaaaaaaaaaaaaaa

Mmacro names are best written in uppercase so you can tell them apart from regular code. Programs are easier to read when it is possible to tell at a glance which names are macros.

The macro’s body ends at the end of the ‘#define’ line. You may continue the definition onto multiple lines, if necessary, using backslash-newline. When the macro is expanded, however, it will all come out on one line. For example,

#define NUMBERS 1, \
                2, \
                3
my $x = array(NUMBERS);
printr $x;
// PRINTS
// Array
// (
//     [0] => 1
//     [1] => 2
//     [2] => 3
// )

The most common visible consequence of this is surprising line numbers in error messages. There is no restriction on what can go in a macro body provided it decomposes into valid preprocessing tokens. Parentheses need not balance, and the body need not resemble
valid Sputnik code. (If it does not, you may get error messages from the Sputnik parser when you use the macro.)

The preprocessor scans your program sequentially. Macro definitions take effect at the place you write them. Therefore, the following input to the reprocessor

my $foo = X;
#define X 4
my $bar = X;
Produces
my $foo = X;
my $bar = 4;

When the preprocessor expands a macro name, the macro’s expansion replaces the macro invocation, then the expansion is examined for more macros to expand. For example

#define TABLESIZE BUFSIZE
#define BUFSIZE 1024
say TABLESIZE;
// PRINTS
// 1024

TABLESIZE is expanded first to produce BUFSIZE, then that macro is expanded to produce
the final result, 1024.

Notice that BUFSIZE was not defined when TABLESIZE was defined. The ‘#define’ for TABLESIZE uses exactly the expansion you specify—in this case, BUFSIZE—and does not check to see whether it too contains macro names. Only when you use TABLESIZE is the result of its expansion scanned for more macro names.

This makes a difference if you change the definition of BUFSIZE at some point in the source file. TABLESIZE, defined as shown, will always expand using the definition of BUFSIZE that is currently in effect:

#define BUFSIZE 1020
#define TABLESIZE BUFSIZE
#undef BUFSIZE
#define BUFSIZE 37
say TABLESIZE;
// PRINTS
// 37

Now TABLESIZE expands (in two stages) to 37.
If the expansion of a macro contains its own name, either directly or via intermediate
macros, it is not expanded again when the expansion is examined for more macros. This
prevents infinite recursion. See Self-Referential Macros for the precise details.


Contact
Cheryl (uberfox@hotmail.com)
Homepage
http://ubersoft.org