mmpp macro processor

Topics covered in this chapter:

The mmpp Mosel program is a general purpose macro processor. A macro preprocessor operates as a text-replacement tool: it is employed to re-use text templates, typically in computer programming applications, but also in text editing and text-processing applications.

The main features of mmpp include:

• single and multi-line macros
• macros with fixed-number and variable number of parameters
• overloading (depending on the number of parameters)
• recursive macro expansion
• file inclusion
• conditional evaluation
• bounded loops
• arithmetic and textual expressions

Running mmpp

The program expects a file name as input: it will process this file and write the result to the standard output. Use the file name '-' to process the standard input and option '-o' to select an output file. For instance, the following command will process its standard input and save the result into 'myfile.mos':

mmpp -o myfile.mos -

The following options are supported:

-V

display banner and exit

-h

display help and the list of supported predefined operators then exit

-Idir

add 'dir' to the list of paths for inclusion

-Dname[=val]

define macro 'name' with value 'val' (default: empty)

-Uname

undefine macro 'name'

-s

generate '#line NUM "FILE"' lines

-L lim

set nesting limit to 'lim' (default:100)

-LS lim

set macro stack limit to 'lim' (default:1000)

-LR lim

set maximum size for lists to 'lim' (default:100)

-r file

process file 'file' before input (no output)

-o file

save output to 'file' (default: output stream)

Using mmpp with mosel

The Mosel compiler will process its source file with mmpp before compilation when option -m is stated.

From the command line tool, 3 compiler options are dedicated to the preprocessor (using any of them implies -m):

-mI dir

add 'dir' to the list of paths for inclusion

-mD name[=val]

define macro 'name' with value 'val' (default: empty)

-mU name

undefine macro 'name'

For instance, to process mysrc.mos with mmpp and define the macros DOIT (as an empty string) and ThisVal (with value 456):

mosel compile -mD DOIT -mD ThisVal=456 mysrc.mos

Note that the compiler will automatically define the macro MC_DEBUG when the file is compiled with debug information (compiler options -g or -G)

Macro definition

Macros can be defined either on the command line using the -D option (e.g. -Dmymacro=10), or with the $def (for single line macro) and $define (for multi-line macros) constructs in the input file.

A single line macro is defined with the following syntax (macroname is the name of the macro, it follows the conventions of Mosel identifiers):

$def(macroname[,nba]) value

For a multi-line macro:

$define(macroname[,nba])
 value
$end(define)

The optional parameter nba is the number of parameters required by the macro (the macro does not take any parameter if it is not specified). The value nba must be a non-negative integer possibly followed by the + sign that indicates that the macro can take at least nba parameters (otherwise it is exactly the specified number). The same macro might be defined several times with different numbers of parameters and the processor will select the actual macro depending on the number of parameters provided.

The constructs $def$ and $define..$end(define) are replaced by empty strings in the result file.

In the body of the macro the parameters are referenced using $n where n is the order number of the parameter (i.e. $1 for first parameter, $2 for second parameter etc.). The total number of parameters is given by $# and all parameters (separated by spaces) is the result of the expansion of $*.

The following example defines 2 versions of the same macro:

$def(info) I got not parameter
$define(info,1+)
I have $# parameters
The first parameter is "$1"
All their values are $*
$end(define)

The constructs $redef and $redefine$ are similar to $def and $define except that an existing definition of the target macro is replaced by the new value ($def and $define will fail if a definition already exists).

The constructs $Def, $Define, $Redef and $Redefine$ are similar to the constructs with a name without a first capital letter except that the body of the macro is expanded before creating the macro (by default the body of the macro is saved unchanged). This makes it possible to extend the content of a macro as in the following example:

$def(mylist) 1 2
$Redef(mylist) $(mylist) 3 4

Indeed, using $redef instead of $Redef would result in an infinite loop here.

The definition of a macro can be removed using $undef:

$undef(info)

Note that if no number of parameters is specified (like in the above example), all versions of the macro are removed. Deleting only the definition without any parameters would be written $undef(info,0)

The construct $conddef works like $def except that the definition will be executed only if it does not exist yet.

$conddef(info,1+) some default value

Macro expansion

In the input file, expanding macro mymacro will be achieved using either $(mymacro) or $mymacro. When the macro requires parameters the syntax becomes $(mymacro,param1,param2) or $mymacro(param1,param2).

The actual expansion consists in processing each parameter individually, replacing each occurrence of these parameters in the macro body by the corresponding values and then replacing the macro reference itself (e.g. $mymacro(param1,param2)) by this updated block of text. When the expansion fails (e.g. the macro does not exist) the macro reference is copied unchanged to the output file and an error message is emitted. For instance, assuming the definitions of the preceding sections are active, the following text:

$info
$info(a,b,c)

will result in:

I got not parameter
I have 3 parameters
The first parameter is "a"
All their values are a b c

All predefined operators of mmpp are introduced by the $ symbol and can be seen as predefined macros.

File inclusion

Switching to a different file is obtained with the following syntax:

$include filename

Where filename results from the expansion of the end of the line, the processing continues with the content of this file.

Inline file expansion can be achieved with:

$include(filename[,sep])

In this case the file filename is read, its lines are concatenated and separated by spaces (or the provided separator sep), and the $include statement is then replaced by the resulting block of text.

Files are searched in a list of directories defined via the -I command line option (each occurrence of this option adds a new directory to the list).

Additional entries can also be a appended using the $addpath construct:

$addpath some/path
$addpath another/one

Expression evaluation

mmpp embeds a basic expression evaluator working on numerical values (encoded as Mosel real numbers) and text strings. It supports the arithmetic operators +,-,\* and /; the comparators <,>,<>,=,>= and <=; and the logical operators and,or and not. The usual order of evaluation is respected and subexpressions might be grouped using parentheses. Any sequence of characters that is not a numerical constant is interpreted as a text string, but it is also possible to quote a text string using `` and '' (e.g. an empty string is noted ``''). The value of a logical operation is the constant 0 (false) or 1 (true); the logical value of a text string is 'false' if it is empty and 'true' otherwise.

The builtin macro $eval expands to the evaluation of its parameter (after this parameter has been itself expanded). For instance:

$def(b) 3
$b+3=$eval($b + 3) and $b>0? $eval($b>0)

Is expanded to:

3+3=6 and 3>0? 1

Conditional expansion

The $if construct allows developers to select blocks of text:

$if cond1
 value1
[$elif cond2
 value2
...]
[$else
 valuen]
$end(if)

The first condition is expanded and evaluated using the evaluator of the previous section: if it is true (i.e. it is a non-zero numerical value or a non-empty text string), the expansion of the entire block is replaced by value1; otherwise the second condition is tested etc. If no condition is validated, the valuen will replace the entire block. If no $else value is defined the block is replaced by an empty string.

Inline conditions are also possible:

$if(cond,value1,value0)

The expansion of this macro will be value1 if the condition is validated, value0 otherwise.

Bounded loops

A loop is specified with the following construct:

$forall(vname[,sep]) values
 body
$end(forall)

Where vname is the name of a new macro that will take sequentially each of the values values for which the block body will be expanded. Individual items of the values list are separated by spaces (or the specified separator sep). All of vname, sep and values are expanded before the loop is executed.

For instance:

$forall(i) 1 2 3
 i=$i
$end(forall)

Results in:

 i=1
 i=2
 i=3

Local definition

The constructs $pushdef and $popdef make it possible to redefine locally a macro:

$pushdef(macroname[,new_value])
...
$popdef(macroname)

The first operator saves all definitions of the specified macro and, optionally, creates a new version of the macro with the specified value. The second operator restores the definitions of the macro.

For instance:

$def(nb) initial value
$nb
$pushdef(nb,new value)
$nb
$popdef(nb)
$nb

Gives:

initial value

new value

initial value

Other builtins

$char(c)

character corresponding to code point c

$defined(m)

1 if m is a defined macro, 0 otherwise

$dnl

delete end of line

$dumpdef(m)

send the definition of macro m to the error stream

$empty(m)

1 if m is an empty string, 0 otherwise

$env(var)

value of environment variable var

$error(m)

report error m

$file

current file name

$index(i,l)

ith element of the list l (items separated by spaces)

$line

current line number

$match(l,s,[,o])

1 if expression s is found in l using regmatch, 0 otherwise. Flags o can be 'e' (extended expression) and/or 'i' (case insensitive)

$message(m)

display message m to the error stream (no error reported)

$noexp(value)

value without macro expansion

$quote(l[,q])

l as a quoted string according to conversion q (see quote)

$range(l,u)

l and u being integer values with l u gives: l l+1 l+2... u

$replace(l,s,r,[,o])

replace s by r in l using regreplace. Flags o can be '1' (once) and/or 'e' (extended expression) and/or 'i' (case insensitive)

$sysinfo(w)

system information (w=name,version,release,proc,arch,node,ram,endian,pid)

$version(m)

version number of module/package m