Contents

macros

Usage:

mymacro <- macro(charVar [, dollars:T])
mymacro <- macroread(fileName [,"mymacro"])
getmacros(macro1 [, macro2 ...]) (reads macro from one of files
  specified in MACROFILES)
macrowrite(fileName, mymacro)

Keywords: macros, control, syntax

A macro is a collection of commands grouped together to make it easy to
execute them all at once.  It is used (invoked) the same way as a
function, by typing its name followed by 0 or more arguments in
parentheses.  For example, y <- boxcox(x,.5) invokes macro boxcox().

A macro is stored in the MacAnova workspace as a variable similar to a
CHARACTER scalar.  You can print its text by typing its name.

                      In-line expansion of a macro
By default, when a macro is invoked it is expanded in-line, that is, its
arguments are literally substituted into the text of the macro and the
modified text is inserted in the line being executed exactly as if it
had been typed in place of the macro call.

Because an in-line macro is inserted directly in the line, a particular
instance of a macro is expanded only once, even if it is repeatedly
encountered during a loop (see 'for' and 'while').  This makes it
impossible to redefine an in-line macro in a loop and execute the new
version the next time through.  However, a macro that is expanded
out-of-line (see below) is expanded every time it is encountered,
allowing meaningful redefinition within a loop.

                       Ways macros may be defined
Macros may be read from a file by macroread() or created directly using
function macro().  There also many pre-defined macros such as readcols()
and boxcox().  Macros may be written to a file by macrowrite().

When you try to use a macro that has not been defined, the default
behavior of MacAnova is to print a warning message and then search the
standard macro files (specifically the files whose names are in
CHARACTER variable MACROFILES; see getmacros()) for the macro.  If the
macro is found, it is read in (without echoing the header lines) and
executed; if not, further execution of the command line is terminated.
Option 'findmacros' allows you to suppress the automatic search and/or
the printing of warning messages.  See topic 'options'.

A macro can be a component of a structure (see 'structures') although it
must be extracted in order to be used.  For example, if structure
boxcoxstr was created by boxcoxstr <- structure(boxcox),
boxcoxstr$boxcox(x,.5) is illegal.  You would have to use something like
@tmpboxcox <- boxcoxstr$boxcox;@tmpboxcox(x,.5).

                    Out-of-line expansion of a macro
An alternative mode of macro expansion is out-of-line.  In this mode, a
modified copy of the macro text is created, substituting macro arguments
in the text.  This is then executed without being inserted in the line
being executed.  In a loop, a particular instance of an out-of-line
macro will be expanded every time through the loop.  The value of option
'inline' (default value is True) determines the default expansion mode.
In addition a macro can be marked always to be expanded out-of-line by
keyword phrase inline:F on macro().  See topics 'options' and macro().

See also topics addmacrofile(), getmacros(), macro(), macrowrite(),
macrousage(), 'macro_files', 'macro_syntax'.

See macroread() for examples of macros.