"Sputnik" help  
Sputnik Help
Language Reference - Preprocessor - Multi-Line Macros

Multi-Line Macros

A normal multi-line macro is just a normal macro but using \ at the end of each line (aside from the last) to signal the macro should continue onto the next lines. For example,

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

Suppose we want to create a multi-line macro called "multi" that expands to a code block with three statements. We can use the '' character to split the macro definition into multiple lines. Here's what the macro definition might look like:

#define multi \
    say "Statement 1"; \
    say "Statement 2"; \
    say "Statement 3";

The macro definition begins with the "#define" directive followed by the name of the macro, "multi". The backslash ("") character at the end of each line tells the preprocessor to continue the macro definition on the next line. The macro definition ends with a semicolon.

Now, let's say we want to use the "multi" macro in our code. We can simply invoke it by typing its name, like this:

multi

When the preprocessor encounters this line, it will expand the macro into its definition, which will look like this:

say "Statement 1"; say "Statement 2"; say "Statement 3";
As you can see, the backslashes are gone and the macro has been expanded into its definition. The preprocessor will replace the macro invocation with the code block defined in the macro.

This is just a simple example of how multi-line macros work using the '' character. In practice, macros can be much more complex and can be used to define entire code structures.

Dedicated Multi-Line Macros

Sputnik introduces a dedicated multiline macro called #definem to simplify the creation of macros with multiple lines of code. This feature is especially useful for defining arrays, functions, or blocks of code within a macro. The syntax involves using a ^ at the end of the macro definition and another ^ on a line by itself to denote the start and end points of the multiline macro.

In this example, the definem macro is used to define an array of numbers. The resulting array, when printed, displays:

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

Here, the definem macro defines a block of code with multiple statements. This can be useful for encapsulating complex logic or repetitive code into a single macro:

#definem multi^
    say "Statement 1";
    say "Statement 2";
    say "Statement 3";
^

The definem macro is not limited to arrays or code blocks; it can also define function-like macros. In this example, the cat macro takes an argument x and outputs multiple statements:

#definem cat(x)^
    say x . " - meow!";
    say x . " - hehe!";
^

cat("kitten");
// PRINTS
// kitten - meow!
// kitten - hehe!

The definem feature enhances code readability and maintainability by providing a clean and structured way to define macros with multiple lines of code. This is particularly advantageous for complex or repetitive tasks where encapsulating functionality into a macro is beneficial.

Finally we can use a Block Macro to achieve this:

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

For more powerful Multi-Line macros see the Block Macros.


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