Next: keywords Up: MacAnova Help File Previous: isvector()   Contents

keyvalue()

Usage:
keyvalue(keyname1:val1, [keyname2:val2, ...] targetkey [, properties]\
  [,default:defVal]), targetkey a CHARACTER scalar, Properties a
  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", and
  defVal arbitrary.
keyvalue(str, targetkey [, properties] [,default:defVal), str a
  structure
keyvalue(, targetkey [, properties] [,default:defVal])



Keywords: syntax, macros
keyvalue(keyname1:val1, keyname2:val2, ... , TargetKey) attempts to
match keyname1, keyname2, ... with CHARACTER scalar or quoted string
TargetKey.  If no match is found, keyvalue() returns NULL.  If a match
is found, the corresponding keyword value is returned.

keyvalue(keyname1:val1, keyname2:val2, ... , TargetKey, default:defVal)
does the same except that defVal is returned if no matching keyword is
found.

keyvalue(keyname1:val1, keyname2:val2, ..., TargetKey, Properties
[,default:defVal) does the same, except that the value of a matched
keyword is returned only if it has the properties specified by CHARACTER
scalar or vector Properties.  When TargetKey is not matched and
'default:defVal' is an argument, defVal value is returned only if it has
all the properties specified by Properties.  See below for an
explanation of Properties.

The principal use of keyvalue is in a macro when keyname1:val1,
keyname2:val2, ... are supplied by $K as in
  @nsig <- keyvalue($K,"nsig","positive integer scalar", default:5)
See below for another example and topic 'macro_syntax' for an
explanation of $K.

TargetKey, the second argument, is usually a legal keyword name such as
"nsig".  In this case an exact match of one of the keyword names is
needed.

However, TargetKey can also contain the "wild card" characters '*' and
'?' so that it provides a pattern used to match a keyword name.  '*'
will match any 0 or more successive characters and '?' will match any
single character.  For example, if TargetKey = "pow*", it matches
keywords 'pow', 'power' and 'powers', among others, but does not match
'polar'.  Similarly, if targetKey = "m??imum", it matches both keywords
'maximum' and 'minimum', among others.  See match() for more information
about inexact matching using '*' and '?'.

You can use structure(keyname1:val1, keyname2:val2, ...) instead of
keyname1:val1, keyname2:val2, ... .

keyvalue(, TargetKey [,Properties]) is legal and returns NULL.
Arguments TargetKey and Properties are checked for appropriateness.

The principal use for keyvalue() is in writing macros that expect
keyword phrase arguments.  It allows easy retrieval and checking of
keyword values.  A key point is that it is an error when the value of a
matched keyword value or the default value does not have the specified
property or properties.  When this occurs in a macro, execution of the
macro is terminated.

Here is a fragment of a macro that recognizes an optional macro argument
of the form 'weights:w' where w must be a REAL vector with positive
elements.

  @weights <- keyvalue($K,"weights","real positive vector",\
    default:rep(1,@n))

If 'weights:w' is an argument to the macro, @weights is set to w;
otherwise @weights is set to the default rep(1,@n).  Presumably @n was
set previously.  If w is not a REAL vector with positive elements the
macro will be terminated with the message
  ERROR: value of keyword 'weights' is not a vector of positive REALs

If "weights" were replaced by "weight*", keyvalue() would return w if
'weight:w' or 'weights:w' were an argument.  This is helpful in writing
a more user friendly macro, that recognizes both 'weight' or 'weights'
when 'weights' is expected.

In a macro, keyvalue(structure($K),...) is almost equivalent to
keyvalue($K,...), except that a warning message is printed when there
are no keyword arguments to the macro ($K expands to nothing).

                        Description of Properties
Properties is usally a CHARACTER scalar or quoted string containing one
or more of the following, separated by blanks or tabs (not commas):
  "array"     "integer"   "matrix"      "notnull"   "scalar"    "vector"
  "character" "logic"     "nonmissing"  "positive"  "square"
  "graph"     "macro"     "nonnegative" "real"      "structure"

An example would be "nonmissing real vector".  Properties can also be a
CHARACTER vector with each element containing one or more properties
from this list, for example, vector("nonmissing","real","vector").

In addition, there are properties thats are abbreviations for
combinations of properties specifying types of scalars:
  "number" means  "nonmissing real scalar"
  "count"  means  "nonnegative integer scalar"
  "TF"     means  "nonmissing logical scalar"
  "string" means  "character scalar"

Not all combinations of properties are permitted.  See below for
details.

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".

Each recognized property (other than the abbreviations "TF", "number",
"count and "string") is classified as to whether it describes the type,
shape, value or sign of a variable:
  Kind of property            Property names
     Type           "real", "logic", "character", "macro", "graph",
                    "notnull"
     Shape          "scalar", "vector", "matrix", "array", "structure",
                    "square"
     Value          "integer", "nonmissing"
     Sign           "positive", "nonnegative"

Combinations of properties are restricted as follows:
  No more than one of each of the 4 kinds of property can be specified
    except that "square" and "matrix" can be used together
  Property "structure" is illegal with any Sign or Value property and
    with "macro", "graph" and "notnull"
  Properties "positive", "nonnegative" and "integer" imply properties
    "real" and "nonmissing" and are illegal with any Type property
    except "real". They are legal with property "number"
  Property "nonmissing" is illegal with any Type property except "real"
    and "logical".
  Properties "macro", "graph" and "notnull" cannot be combined with any
    other properties.

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


Gary Oehlert 2003-01-15