Contents

macro_files

Keywords: macros, files, input, output

This topic describes the format of a file to be read by macroread().
See topics 'data_files', 'vecread_file' and 'matread_file' for
information on data files, and topic 'files' for more technical
information on file names, default directories or folders, and
abbreviated file names of the form "~/filename".

A file that can be read by macroread() must be a plain text or ascii
file.  If you create it in a word processor, be sure to save it as a
text or ascii file.  On the file can be any number of macros, each with
a header line, followed by optional comment lines and macro text lines.
The header line must contain keyword MACRO and may contain one or more
keywords INLINE, OUTOFLINE, NOTES, ENDED or DOLLARS.  MACRO must be the
first keyword but the order of others is irrelevant.

There are two possible formats for macros that can be read by
macroread().  Both can include descriptive notes (see topic 'notes').

Form A is terminated by a special line:
   Name MACRO [other keywords]
   ) 0 or more descriptive comment lines starting with ')'
   ) .......
   Line 1 of macro
   . . . . .
   Line Nlines of macro
   %Name%

Form B, requires a count of the lines and is considered obsolete:
   Name Nlines MACRO [other keywords]
   ) 0 or more descriptive comment lines starting with ')'
   ) .......
   Line 1 of macro
   . . . . .
   Line Nlines of macro

Name is the macro name to be searched for.  Case is ignored in searching
for the name, so that matread(FileName,"mymacro") will find mymacro(),
MyMacro(), or MYMACRO(), for example.

The text of the macro immediately follows the header and comment lines.

In form A, the line immediately after the last line of macro text must
be %macroname%, where macroname must be identical, including use of
upper and lower case letters, to the name on the name line.

In form B, Nlines must be an integer and there must be exactly Nlines of
text.  The count includes lines starting with "#" but not the
descriptive comment lines, if any.

It is good practice to include both header comment lines starting with
")" and macro comment lines starting with "#" describing the usage of
the macro.  See also macrousage().

It is permissible for there to be no lines of macro text (%macroname%
immediately following comment lines for form A or Nlines = 0 for Form
B).  When macroread() reads such a "macro", only the descriptive
comments are printed (if 'quiet:T' is not present).  It is a useful
convention to make the first macro on a file have 0 length with the
header describing the contents of the file, since then
'macroread(FileName)' will print the contents.

                   Optional keywords on the name line
When the name line is of the form
   Name MACRO OUTOFLINE [other keywords]
or
   Name MACRO Nlines OUTOFLINE [other keywords]
the macro will be marked so that it will always be expanded out-of-line.
When INLINE appears instead of OUTOFLINE, it will not be so marked.
Simply OUT or IN can be used instead of OUTOFLINE or INLINE.  Since in-
line expansion is the default, INLINE is never required.

When the name line is of the form
   Name MACRO NOTES [other keywords]
or
   Name MACRO Nlines NOTES [other keywords]
the macro should be followed by a data set named "Name$NOTES" containing
a CHARACTER vector of descriptive usage notes.  See topic 'matread_file'
for the format.

When the name line is of the form
   Name MACRO DOLLARS [other keywords]
or
   Name MACRO Nlines DOLLARS [other keywords]
'$$' will be appended to any temporary variable names (names starting
with '@') that don't already end with '$$'.  When DOLLARS is on the name
line of macro myMacro(), macroread(fileName,"myMacro") is equivalent to
macro(macroread(fileName,"mymacro"),dollars:T).  See topics macro() and
'macro_syntax'.

When a form B name line has the form
   Name MACRO Nlines ENDED [other keywords]
it signals that the macro is followed by a line starting '%macroname%',
where 'macroname' exactly matches the name on the name line.  In some
cases, this can prevent matread() or macroread() from erroneously
recognizing a line of the macro as the header for another macro.  ENDED
may also be used on form A macros, but is unnecessary since they are
required to have an ending line.

When the name line is of the form
   Name MACRO LOCKED [other keywords]
or
   Name MACRO Nlines LOCKED [other keywords]
and the result of macroread() or read() is assigned to create a macro,
that macro will be locked.  See topic 'locks'.

  Cmd> doit <- macroread("macrofile.txt","doit")
  doit  MACRO LOCKED

  Cmd> list(doit)
  doit            MACRO  (in-line) (locked)

A line starting _E_N_D_O_F_M_A_C_R_O_S_ terminates the reading of macros
or data from a file.  You can put help information for the macros after
this line.  See file macanova.hlp for a description of the required
format for the help that would follow this line.

Example of macro file containing a 0 length, information only, macro and
three genuine macros:

   info      MACRO
   ) This file contains macros median(), rm(), and means()
   %info%

   median    MACRO
   ) median(x) computes medians of columns of x
   # usage: median(x) [it's helpful to include usage in body of macro]
   describe($1,median:T)
   %median%

   rm        2 MACRO
   ) rm(a,b,...) alias for delete for Unix/Linux lovers
   # usage: rm(a,b,...) equivalent to delete(a,b,...)
   delete($0)

   means      MACRO NOTES DOLLARS
   ) means(x1,x2,...) computes means of vector arguments
   # usage: means(x1,x2,...) computes means of vector arguments
   @args <- structure($0) # make structure of all arguments
   for(@i,1,$N){
       if(!isvector(@args[@i])){
           error("Arguments to macro $S must be vectors")
       }
   }
   @result <- rep(0,$N) #create vector of right length
   for(@i,1,$N){
       @result[@i] <- sum(@args[@i])/nrows(@args[@i])
   }
   @result
   %means%

   means$NOTES  CHARACTER
   ) Two lines of usage notes for macro means()
   means(x1,x2,...) computes means of its vector arguments, returning
   them in a vector.
   %means$NOTES%

   _E_N_D_O_F_M_A_C_R_O_S_

The _E_N_D_O_F_M_A_C_R_O_S_ line is optional but recommended.  It must
be used if anything else other than data sets, for example help
information, follows the macros in the file.

Note: Form A was new with Version 4.04 of MacAnova.  Keywords ENDED and
DOLLARS were new in February 1999.