Next: macro_files Up: MacAnova Help File Previous: macintosh   Contents


macro(text [, dollars:T, inline:T or F ,notes:Notes]), text a CHARACTER
  scalar, Notes CHARACTER scalar or vector

Keywords: macros, control, syntax
macro(Text) creates a macro from the commands contained in the CHARACTER
variable or quoted string Text.  Text can also be an existing macro.

Here is a short example of the use of macro().

  Cmd> vhat <-\
    macro("@x <- argvalue($1,\"argument 1\",\"real matrix nonmissing\")
    @n <- nrows(@x); @p <- ncols(@x) #get dimensions
    @x <- @x - sum(@x)/@n # compute residuals from mean
    @v <- if (@n > 1){(@x %c% @x)/(@n*(@n-1))}else{
        matrix(rep(0,@p*@p),@p)} # 0 matrix when n = 1
    delete(@n,@x,@p) # cleanup

vhat(x) returns S/n, where S is the sample variance/covariance matrix of
matrix x.  See topics 'macros', 'macro_syntax' and argvalue() for
interpreting the text.

When you use macro() to define a macro, you should type any quotes
'"' as '\"', as in the example.  Similarly to include a backslash '\'
you must type '\\'.  In particular, quoted quotes in a macro must
be typed as '\\\"' as in
  Cmd> quotedecho <- macro("print(\"\\\"$0\\\"\")")

  Cmd> quotedecho(The answer is 42)
  "The answer is 42"

macro(Text,dollars:T) creates a macro from Text, adding "$$" to every
temporary name (name starting with '@') that (a) is not in a quoted
string, (b) is not in a comment starting with '#' and (c) does not
already end in "$$".  When the macro is executed, "$$" is replaced by a
2 digit number unique to the particular macro invocation so that the
actual name is unique to the macro.  The length of any temporary name
you use must be no more than 10 characters, counting '@'.  The following
appends '$$' to all temporary variable names in vhat:

  Cmd> vhat <- macro(vhat, dollars:T)

The first line of vhat now starts '@x$$ <-' instead of '@x <-.  See
topic 'macro_syntax' for more information about using '$$' in macros.

You can attach explanatory notes to a macro using keyword phrase
'notes:Notes', where Notes is a CHARACTER vector.  See topic 'notes' for

macro(Text,inline:F [,dollars:T]) marks the macro being created as one
to be expanded out-of-line instead of having the expansion inserted into
the input line.  This primarily means that the macro will be freshly
expanded every time it is encountered, even on multiple trips through a
loop.  An instance of an in-line macro is expanded just once.  See topic
'macros'.  inline:T marks the macro as to be expanded in-line, even if
the value of option 'inline' is False.  See subtopic 'options:"inline"'.
You can mark an existing macro myMacro() to be expanded out-of-line by

  Cmd> myMacro <- macro(myMacro, inline:F)

Within quotes ("..."), any characters other than "\n" and "\t" whose
ASCII codes are either 127 or less than 32, are replaced by their
escaped octal representation of form \nnn.  For example,
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\001\",$K)")
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\x01\",$K)")
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\\001\",$K)")
are completely equivalent.

Non-standard characters with ASCII codes >= 128 are not treated
specially.  For example,
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\201\",$K)")
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\x81\",$K)")
are equivalent, producing a macro containing whatever character has
ASCII code 129, which has a computer specific interpretation.

See topic 'macros' for details on writing macros, including the use of
special symbols '$0, '$1', '$2', ..., '$N', '$V', '$v', '$K', '$k', '$S'
and '$$'.

  Cmd> median <- macro("describe($1,median:T)")
  Cmd> myread <- macro("matrix(vecread(\"$1\"),$2)'") #note transpose
  Cmd> greetings <- macro("print(\"\\\"Hello\\\"\")")
  Cmd> xlogx1 <- macro("@x <- $1; @x*log(@x)")
  Cmd> xlogx2 <- macro("@x$$ <- $1; @x$$*log(@x$$)")
  Cmd> xlogx3 <- macro("@x <- $1; @x*log(@x)", dollars:T)

median(x) would compute the medians of the columns of x.  See

y <- myread(family.dat,23) would create a matrix with 23 columns from
data from file family.dat, assumed to have a total of n*23 data items
arranged in n rows.

greetings() prints "Hello", complete with the quotation marks.

xlogx1(x), xlogx2(x) and xlogx3 all compute x*log(x).  However, use of
xlogx1 might lead to a problem if some other macro also used @x as a
temporary variable.  xlogx2 avoids this problem because the temporary
variable name @x$$ will be expanded to @x51, say, a name that should not
conflict with any other temporary name.  xlogx3 is identical to xlogx2
because each instance of @x is converted to @x$$.

See also topics 'macros', 'macro_syntax', macroread(), macrowrite().

Gary Oehlert 2003-01-15