Language Specific M4 Macros

lang_m4

@(@\newcommand{\B}[1]{ {\bf #1} } \newcommand{\R}[1]{ {\rm #1} }@)@ Language Specific M4 Macros
Purpose
For each scripting language, Python, Octave, and Perl, there is corresponding m4 file python.m4, octave.m4, and perl.m4. These files define macros that convert the *.xam files to examples (and tests) in the corresponding language. This is the specifications for the macros in an arbitrary scripting language.

Convention
All macro names are an upper case letter, following by lower and upper case letters, and end with an under-bar.

No Arguments

Ext_
This is the file extension (without the .) used for scripting language; e.g., py for Python files.

True_
This is a constant representing the value true in the scripting language; e.g. True for Python.

False_
This is a constant representing the value false in the scripting language; e.g. False for Python.

And_
This is the logical binary and operator; e.g. and for Python.

Not_
This is the logical unary operator not; e.g. ! for Perl.

End_
This is the text that goes on a line, by itself, to terminate a block of code; e.g., end for Octave. Note that in Python, the comment symbol # is used. This suffices because the level of indentation (by tabs) is reduced by one when the block terminates.

C_
This is the text that starts a comment that lasts for the current line; e.g., # for Python.

Eos_
All statements will be following by a newline in the input text. This macro provides any characters, beside the newline, that are required to terminate a statement. For example, in C++ it could be ;. Note that this text use automatically included by macros that are documented as statements.

Try_
This text starts an exception try block. It is assumed that the block will be terminated by a Catch_.

Catch_
This text terminates a try block and starts an exception catch block. It is assumed that the block will be terminated by an End_.

Eof_
This is extra text that should be added at the end of file. (For some strange reason, perl requires a true value at the end of each *.pm file.)

Module_

No Arguments
If Module_ has no arguments, it is the Cppad Swig module name for scripting language; e.g., py_cppad for Python.

One Argument
The text corresponding to



     Module_(name)

references the specified name in the swig module. For example, in Octave it might be



     m_cppad.name

Constructor
The text corresponding to



     ModuleCtor_(name)

references the specified constructor in the swig module. For example, in Octave it might be



     m_cppad.name

while in Perl it could be



     new pm_cppad::name

Macro With Arguments That are Not Statements

Var_
The text corresponding to



     Var_(variable)

retrieves the value of the specified variable. For example, in Python it could be variable while in Perl it could be $variable . Note that this text is automatically included for macro arguments that are documented as being a variable ; e.g., seen Member_ below.

Member_
The text corresponding to



     Member_(variable, name)

references the specified member function or data in the context of the specified variable. For example, in Perl it might be



     $variable->name

StringEqual_
The text corresponding to



     StringEqual_(left, right)

results in true (false), if the string left is equal (not equal) to the string right . (Note that in C++, left operand must be a std::string while the right might be a char*.)

Assignment Statements

NewVar_
The text corresponding to



     NewVar_(type, variable, value)

declares the new specified variable with the specified type and assigns it the specified value. For example, in Octave it could be



     variable = value;

Note the semi-colon at the end which suppressed printing the value (in the Octave language). In C++, it could be



     type variable = value;

Assign_
The text corresponding to



     Assign_(variable, value)

assigns the specified value to an existing variable. For example, in Python it could be



     variable = value

AndAssign_
The text corresponding to



     AndAssign_(variable, value)

assigns the specified logical variable to the binary expression of itself and the value. For example, in Octave it could be



     variable = variable && value;

Vector Operations

VecSet_
The text corresponding to



     VecSet_(vector, index, value)

sets the element with the specified index, in the specified vector, to the specified value. For example, in Python it might be



     vector[index] = value

VecGet_
The text corresponding to



     VecGet_(vector, index)

gets the value of the element with the specified index, in the specified vector. For example, in Perl it might be



     $vector->get(index)

Function Statements

BeginBoolFun_
The text corresponding to



     BeginBoolFun_(return_variable, FunctionName_)

is placed at the beginning of function that has zero arguments and a boolean return value. This must initialize return_variable as true. For example, in Octave it might be



     function return_variable = FunctionName_()

          %

          % load the Cppad Swig library

          m_cppad

          %

          % initialize return value

          return_variable = true;

Note that this begins a block of code that will be terminated by a corresponding End_. The argument FunctionName_ should be related to the xam input file as follows: FunctionName_ .

Return_
The text corresponding to



     Return_(return_variable)

terminates the current function block with the specified return value a matching End_ . For example, in Python it might be



     return return_variable

Control Flow Statements

For_
The text corresponding to



     For_(variable, upper)

starts a for loop the specified integer index variable. The initial value of the variable is zero. The variable increases by one each time through the loop. The value of the index the last time through the loop is upper-1 . The block inside the loop is terminated by a matching End_ .

If_
The text corresponding to



     If_(expression)

starts an if block that is executed when the expression is true. The block is terminated by a matching End_ .

Input File: lib/xam/lang_m4.omh