Next: arimahelp() Up: MacAnova Help File Previous: arginfo_fun   Contents

argvalue()

Usage:
argvalue(var, argName, [, Properties]), var any variable, argName
  CHARACTER scalar, Properties CHARACTER scalar or vector whose elements
  are one or more of "array", "character", "count", "graph", "integer",
  "logic", "macro", "matrix", "nonmissing", "nonnegative", "notnull",
  "number", "positive", "real", "scalar", "square", "string",
  "structure", "TF" and "vector"



Keywords: syntax, macros
argvalue(Var, argName, Properties), where argName is a quoted string or
CHARACTER scalar and Properties is a CHARACTER scalar or vector, checks
Var to see if satisfies the restrictions specified by Properties.  When
Var does satisfy the restrictions, the value of Var is returned and
argName is ignored.  Otherwise, it is an error and the resulting error
message incorporates argName.

Var can be any defined variable but cannot be a built-in function.

Properties is usually a quoted string or CHARACTER scalar such as
"nonmissing real", made up of one or more words separated by spaces or
tabs.  Alternatively, Properties can be a CHARACTER vector like
vector("nonmissing", "real"), each element of which contains one or more
words.

Properties recognized are "array", "character", "count", "graph",
"integer", "logic", "macro", "matrix", "nonmissing", "nonnegative",
"notnull", "number", "positive", "real", "scalar", "square", "string",
"structure", "TF" and "vector".

Not all combinations or words are permitted.  See keyvalue() for
details.

The following properties are abbreviations for combinations of other
properties specifying types of scalars:
  "number" means  "nonmissing real scalar"
  "count"  means  "nonnegative integer scalar"
  "TF"     means  "nonmissing logical scalar"
  "string" means  "character scalar"

Any 3 character or longer initial segment of a property will match it,
except that "nonnegative", "nonmissing", "string" and "structure"
require 4.  For example, "vec", "vect", "vecto", ... all match "vector".

y <- argvalue(var, argName), with no Properties argument, is
essentially equivalent to y <- var except that argName is used in an
error message if var is not defined.

argvalue() is designed to be used in writing macros.  It allows easy
checking of non-keyword macro arguments with automatic printing of
informative error messages.  As a typical example of its use, here is
the text of macro gamma() that uses lgamma() to compute the gamma
function of a REAL array of positive elements:

  if ($v != 1 || $k > 0){error("usage is gamma(x)")}
  @x <- argvalue($1,"$1","positive array")
  exp(lgamma(@x))

Instead of "$1" as argument 2 to argvalue(), you might use "argument 1".
Either choice is likely to yield an informative error message.

When gamma() executed, $1 is replaced by argument 1 to gamma(), $v and
$k are replaced by the number of keyword and non-keyword arguments,
respectively, and $S is replaced by the name of the macro, here 'gamma'.
See topics 'macros', 'macro_syntax' and macro() for details.

  Cmd> gamma(run(4))
  (1)            1            1            2            6

  Cmd> gamma(run(0,2))
  ERROR: run(0,2) is not an array of positive REALs

The second line of the macro was expanded to
  @x <- argvalue(run(0,2),"run(0,2)","positive array")

See also keyvalue(), nameof(), getkeywords(), isscalar(), isvector(),
ismatrix(), isarray(), isreal(), ischar(), islogic(), ismacro(),
isstruc(), isnumber(), isgraph(), isdefined(), 'macros'.


Gary Oehlert 2003-01-15