Next: macros Up: MacAnova Help File Previous: macro_syntax   Contents

macroread()

Usage:
mymacro <- macroread(FileName,macroName [,quiet:T or F, echo:T or F,\
  silent:T, printname:F, notfoundok:T, nofileok:T, prompt:F,\
  badkeyok:T]), FileName and macroName CHARACTER scalars; FileName can
  also be CONSOLE or have the form string:charVal where charVal is a
  CHARACTER scalar or vector.



Keywords: macros, files, input
mymacro <- macroread(FileName,macroName) searches the named file for a
macro whose name matches macroName.  If the macro is found, it is read
and made available under the name mymacro().  FileName and macroName
must be quoted strings or CHARACTER scalars.

Usually the name to the left of '<-' will be the same as the name of the
macro read as in
  Cmd> density <- macroread("densities.mac","density")

In searching the file for a matching name, case is ignored so that, so
that macroread(FileName, "mymacro") will find mymacro(), MyMacro(), or
MYMACRO(), for example.  See topic 'macro_files' for a description of
the required file format.

In a version with windows (Macintosh, Windows, Motif), when FileName is
the null string "", you will be able to select the file using a dialog
box.

The header and comment lines are normally echoed to output, but this can
be suppressed by keywords;  see below.

If the macro has keyword LOCKED on the header line, and the result is
assigned to a variable, that variable will be locked.  See topic
'locks'.

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

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

mymacro <- macroread(FileName) with no macro name reads the first macro
on the file.  The first non-empty, non-blank line in the file is assumed
to be the start of the macro as described in topic 'macro_files'.  It is
an error if it is not in the right format for the first header line of a
macro or data set.

Just reading a macro does not make it available; you must assign the
value of macroread() using '<-'.  You can usually use getmacros() to
simultaneously read a macro and make it available.

When you are reading a macro from one of the standard macro files
(arima.mac, design.mac, graphics.mac, macanova.mac, math.mac,
mulvar.mac, regress.mac and tser.mac) pre-defined macro getmacros() is
more convenient to use than macroread().  An example of its use is

  Cmd> getmacros(covar)

This replaces to 'covar <- macroread("macanova.mac","covar")', except
that you don't even need to know which file covar() is located in.

Use of macroread() or getmacros() is sometimes not necessary, since the
default behavior of MacAnova is to search the files in MACROFILES (see
getmacros()) for any undefined macro you try to use.  For example, even
if macro covar() has not previously been read from file "MacAnova.mac",
either by getmacros() or macroread(),

  Cmd> cov <- covar(x)

will read covar() and then execute it.  However, both macroread() and
getmacros() normally echo the header lines on macros; these often
contain details about usage which you otherwise might miss.

See below for discussion of keywords 'quiet', 'echo', 'silent',
'notfoundok' and 'nofileok'.

If 'OUTOFLINE' or simply 'OUT' appears on the first header line of the
macro, it will be marked to be always expanded out-of-line.  Otherwise,
the expansion of the macro will be determined by the value of option
'inline'.  See topics 'macros', 'options'.

macroread(CONSOLE [,prompt:F]) reads from the regular input stream
allowing you to type in the macro using the format described under topic
'macro_files'.

On the Macintosh, type one line at a time in the dialog box that is
opened.

On Unix/Linux and DOS, type the necessary lines after the prompt.  The
value of CONSOLE is ignored.  The first line must be of the form 'Name
nLines MACRO', where nLines is the number of lines in the macro.

On any machine, when macroread(CONSOLE) is used in a batch file, it
reads the macro from the lines immediately following the macroread()
command.  See batch().  No prompt is printed when prompt:F is an
argument.

Any blank lines at the end of a macro are trimmed off when it is read.

There are several keywords, 'quiet', 'echo', 'silent', 'notfoundok' and
'nofileok' which control what will be printed by macroread().

  Keyword phrase        Meaning
   quiet:T          Header and descriptive comments will not be printed
   quiet:F          All header and descriptive comments will be printed
   echo:T           Lines of the macro itself will be printed as they
                    are read
   silent:T         Only error messages will be printed; incompatible
                    with quiet:F or echo:T
   printname:F      The name of the file read will not be printed;
                    printname:T is ignored with silent:T
   notfoundok:T     Failure to find the macro is not considered an error
                    so no error message is printed.
   nofileok:T       Failure to open the file is not considered an error
                    so no error message is printed.
   badkeyok:T       Unrecognized or duplicate keywords are silently
                    ignored.

Without quiet:T or quiet:F, the header and comment lines not starting
with '))' preceding the macro will be echoed to output.

Even without echo:T, header lines are printed when FileName is CONSOLE
and the macroread() command is in a batch file.  (In windowed versions,
a macro will be echoed if FileName is CONSOLE whether or not the command
is in a batch file.)  Such echoing can be suppressed by 'echo:F'.

When notfoundok:T is an argument and the macro is not found or
nofileok:T is an argument and the file cannot be opend, macroread()
returns NULL as value.  When used in a macro, this feature allows
special action to be taken if macroName is not found.  See topic 'NULL'.

macroread(file:FileName,...) is equivalent to macroread(FileName,...).

macroread(string:CharVar,...) where CharVec is a CHARACTER scalar or
vector, does not read from a file.  Instead, it "reads" CharVar as if
each element were a line (or several lines if there are embedded
end-of-line characters) read from a file.  The first element or line of
CharVar must be a header line with a name and number of lines.  In
particular, mymacro <- macroread(string:CLIPBOARD) would read the first
macro on a replica of a data file in the special variable CLIPBOARD.  In
the Macintosh, Windows and Motif versions this would be taken from the
Clipboard.  In the Motif version, you can also "read" from special
variable SELECTION in a similar way.  See topic 'CLIPBOARD'.

If either keyword 'file' or 'string' is used, they can appear in any
position in the argument list, as can setName which must be the only
non-keyword argument.  For example,
  Cmd> macroread(quiet:T,"mymacro",file:"myfile.dat")
is equivalent to
  Cmd> macroread("myfile.dat","mymacro", quiet:T).

A predefined CHARACTER variable MACROFILES contains the names of files
containing macros.  A pre-defined macro getmacros() allows easy
retrieval of macros from the files whose names are in MACROFILES.  At
startup, MACROFILES is initialized to vector("graphics.mac",
"regress.mac", "design.mac", "tser.mac", "arima.mac", "mulvar.mac",
"math.mac", "macanova.mac"), but you can change it if desired.  See
topics getmacros() and addmacrofile().

See also topics 'macros', macro(), read(), matread(), inforead(),
'macro_files', 'files'


Gary Oehlert 2003-01-15