On line help is available for many of the functions in XLISP-STAT
.
As an example, here is how you would get help
for the function
median
:
> (help 'median) MEDIAN [function-doc] Args: (x) Returns the median of the elements of X. NIL >Note the quote in front of median . help is itself a function, and its argument is the symbol representing the function median . To make sure help receives the symbol, not the value of the symbol, you need to quote the symbol.
If you are not sure about the name of a function you may still be able to get some help. Suppose you want to find out about functions related to the normal distribution. Most such functions will have ``norm'' as part of their name. The expression
(help* 'norm)will print the help information for all symbols whose names contain the string ``norm'':
> (help* 'norm) ------------------------------------------------------------------------------ Sorry, no help available on NORM ------------------------------------------------------------------------------ Sorry, no help available on NORM-2 ------------------------------------------------------------------------------ Sorry, no help available on NORMAL ------------------------------------------------------------------------------ NORMAL-CDF [function-doc] Args: (x) Returns the value of the standard normal distribution function at X. Vectorized. ------------------------------------------------------------------------------ NORMAL-DENS [function-doc] Args: (x) Returns the density at X of the standard normal distribution. Vectorized. ------------------------------------------------------------------------------ NORMAL-QUANT [function-doc] Args (p) Returns the P-th quantile of the standard normal distribution. Vectorized. ------------------------------------------------------------------------------ NORMAL-RAND [function-doc] Args: (n) Returns a list of N standard normal random numbers. Vectorized. ------------------------------------------------------------------------------ NIL >The symbols norm , norm-2 and normal do not have function definitions and thus there is no help available for them. The term vectorized in a function's documentation means the function can be applied to arguments that are lists or arrays; the result will be a list or array of the results of applying the function to each element of its arguments.
A related term appearing in the documentation of some functions is
vector reducing
. A function is vector reducing if it is applied
recursively to its arguments until a single number results. The
functions
sum
,
prod
,
max
and
min
are
vector reducing.
The first time a help function is used will take some time -- the help file is scanned and the positions of all entries in the file are recorded. Subsequent calls will be faster.
Let me briefly explain the notation used in the information printed by
help
to describe the arguments a function expects
. Most functions expect a fixed
set of arguments, described in the help message by a line like
Args: (x y z)Some functions can take one or more optional arguments. The arguments for such a function might be listed as
Args: (x &optional y (z t))This means that x is required and y and z are optional. If the function is named f , it can be called as (f x-val) , (f x-val y-val) or (f x-val y-val z-val) . The list (z t) means that if z is not supplied its default value is T . No explicit default value is specified for y ; its default value is therefore NIL . The arguments must be supplied in the order in which they are listed. Thus if you want to give the argument z you must also give a value for y .
Another form of optional argument is the keyword argument . The histogram function for example takes arguments
Args: (data &key (title "Histogram"))The data argument is required, the title argument is an optional keyword argument. The default title is "Histogram" . If you want to create a histogram of the purchases data set used in Section 3.1 with title "Purchases" use the expression
(histogram purchases :title "Purchases")Thus to give a value for a keyword argument you give the keyword
for the argument, a symbol consisting of a colon
followed by the argument name, and then the value for the argument. If
a function can take several keyword arguments then these may be
specified in any order, following the required and optional arguments.
Finally, some functions can take an arbitrary number of arguments. This is denoted by a line like
Args: (x &rest args)The argument x is required, and zero or more additional arguments can be supplied.
In addition to providing information about functions help also gives information about data types and certain variables. For example,
> (help 'complex) COMPLEX [function-doc] Args: (realpart &optional (imagpart 0)) Returns a complex number with the given real and imaginary parts. COMPLEX [type-doc] A complex number NIL >shows the function and type documentation for complex, and
> (help 'pi) PI [variable-doc] The floating-point number that is approximately equal to the ratio of the circumference of a circle to its diameter. NIL >shows the variable documentation for pi
.
Anthony Rossini