.BG
.FN options
.TL
Set or Print Options
.CS
options(...)
.AG ...
to set options, provide arguments in the `name=value' form.
Options corresponding to these names will be set and remembered for
the rest of the session, or until another call to `options' resets them.
For example,
.Cs
options(digits=3, check=T)
.Ce
sets the `digits' option to `3' and the `check' option to `TRUE'.
A list of the previous values of these
options is returned.
In the example, it would be a list of length 2, with components `digits'
and `check'.
This list
can be used in a subsequent call to reset the
options.
.sp .25
If an unnamed character vector is given as the only argument,
a list will be returned,
whose components contain the current values of the options named by
the character vector.
If no argument
is given, `options' returns the entire current options list.
.sp .25
If an unnamed object of mode
`list'
is given as the only argument, its components will be copied in as
the values for options with the corresponding names.  This is what makes
the resetting of options work as described above.
.PP
While any option names can be used, the following have special meaning.
.AG echo
if `TRUE', each complete expression will be echoed before
it is evaluated.
.AG width
the width (in print positions) of the user's
terminal.
.AG length
the length (in lines) of an output page.
.AG prompt
the string to be printed by the S parser to prompt for
an expression.
.AG continue
the string to be printed by the S parser to prompt for the continuation of
an expression.
.AG digits
number of significant digits to use in `print' (and therefore in automatic
printing).
.AG check
if `TRUE' S performs various internal checks during evaluation.
This provides more information
about warning messages and reloading, and
may help track down mysterious bugs (such as S
terminating abnormally).
Evaluation will be substantially slower with this option turned on.
.AG memory
the maximum total size (in bytes) for all in-memory data.
If this limit is exceeded, the session will be terminated (to
avoid runaway computations that may slow down or crash the computing system).
If total memory reaches half the allowed limit, S will automatically reload
at the completion of the next expression, to get rid of garbage.
Generally, it is unwise to rely on this mechanism; a better way
is to check for memory growth by calling the function `memory.size()' to
see how big things are, and calling the function `reload()' if things are
getting out of hand.
.AG object.size
the maximum size (in bytes) for any single S object.
If this limit is exceeded, an error is generated, but the session continues.
.AG keep
determines what mode of objects are to be kept in an internal table once
accessed in a session.
Default strategy is `keep="functions"', so that future calls will be faster
from not having to find the functions on the system database.
The most likely other strategy is `keep=NULL' which turns off keeping,
and might be a good idea if you were about to access a large number of
functions sequentially.
S also recognizes `keep="any"' saying to hash anything that is read; you
might want to do this briefly when first reading some object that will
be re-used extensively; otherwise, beware the memory growth that may result!
.AG error
function (with no arguments) to be called when an error or interrupt occurs.
S provides `dump.calls', `dump.frames' to dump the outstanding
function calls or the entire associated frames.
See the documentation for these functioins for details.
The option `error=NULL' eliminates all error actions.
.AG audit.size
the maximum size (in characters) for the audit file.
If this limit is exceeded at the beginning of a session, a warning message
will be printed.
You should then use the shell-level utility
.Co "S TRUNC_AUDIT"
to reduce the size of the audit file.
.AG show
should graphics be shown directly or returned as a graphics object?
.AG editor
default text editor command; used in `history', for example.
Whatever editor you choose will be invoked in the style of `ed', `vi', etc;
that is, by a command of the form
.Cs
ed filename
.Ce
followed by the reading of editing commands from the terminal.
Do not supply editors that expect a different invocation or a different
form of user interaction.
.AG warn
the level of strictness at which the system should warn you about  non-fatal
blemishes.
At level `0', the warnings are collected and at the end of the evaluation
these will be printed or (if there are too many) a notice will be printed
saying how many warnings were generated.
At level `1' warning messages are printed just as they happen, however
many there are.
At level `2', warnings are converted into errors that terminate the evaluation
of the expression.
In the other direction, any negative value for `warn' suppresses all warning
messages.
Fatal errors, like those generated by calling `stop', are inescapable
and  unaffected by the `warn' option.
.AG compact
Internal memory built up during a loop (`for', `while', or `repeat') will
be compacted when the possibly recoverable amount exceeds this number of bytes.
Giving a value of `0' (or `FALSE') to compact turns off compacting.
This choice, or a large value for `compact' trades off more memory growth
for less time spent in compacting.
While the best value depends somewhat on the problem you are working, it
depends more on the configuration and load of the computer system.
Your local S administrator may have chosen a reasonable value for
your system; if so, you usually should not change it yourself.
.AG scrap
The internal memory management allocates atomic objects using more than
this number of bytes as individual blocks.
The only reason you care is that such blocks are recoverable during evaluation.
As with the previous option, large values trade off more memory growth
for less time spent managing the memory.
Also as previously, pretty good values can be set for all users of a
particular computer installation.
.AG free
If `TRUE', S will make an attempt to recover space whenever an assignment
occurs (inside functions as well as at the top level), and once again
this is a trade-off between the time spent trying to recover space and
the extra memory growth if no attempt is made.
.AG expressions
The maximum depth to which expressions can be nested.
This exists primarily to catch runaway recursive calls of a function to itself,
directly or indirectly.
.PP
The initial values for these options are as follows:
.Cs
audit.size=5e5	 error=dump.calls  prompt="> "
check=F		 expressions=256   scrap=500
compact=1e5	 free=T		   show=T
continue="+ "	 keep="function"   warn=0
digits=7	 length=48	   width=80
echo=F		 memory=5e7
editor="ed"	 object.size=5e6
.Ce
.RT
`options' returns a list,
whose components give either the previous or the current options, as
determined by the arguments supplied.
Thus, the expression
.Cs
options()$show
.Ce
gives the current value of the option `show'.
Options that have never
been set have the value `NULL'.
Note that the value of `options' is
.I always
a list, even when a single option is returned.
.SE
Options set via options are set in the session frame;
the mechanism is to assign an object named `.Options',
whose components are all the  currently defined options.
.SH NOTE
The special options recognized internally are driven from the
object `.Options'; the `options' function is relevant only in that
it provides a convenient way (and for most applications the best way)
to set and reset the components of this object.
However, for some purposes working with the object directly is better;
in particular,  to set options temporarily in a function and in 
the functions called from that function, just replace components in `.Options'.
The last example below illustrates the technique.
Contrast it with the example above it, which turns off all warnings
before evaluating its argument.
If as in that example you used `options' inside a function, this temporarily
changes options globally, and you should guarantee that the
options would be correctly reset, say by calling `on.exit'.
.EX
options(width=50)   # 50-character wide line

temp \(<- options(prompt="Say something! ",continue="\\t")
   # some computations, then
options(temp) #restore prompt and continue

silent.eval \(<- function(expr) {
	old \(<- options(warn = -1)
	on.exit(options(old))
	expr
}

silent.divide \(<- function(x,y) {
	.Options$warn \(<- -1 #turn off NA warnings
	x/y
}
.KW error
.WR
