Set or Return Options
DESCRIPTION:
Provides a means to control some of the behavior of S-PLUS such as the number of digits printed, the maximum number of characters to place on a line, and strategies for memory management.
USAGE: 
options(...)
OPTIONAL ARGUMENTS:
...:
a list may be given as the only argument, or a vector of character strings given as the only argument, or any number of arguments may be in the name=value form , or no argument at all may be given. See the VALUE and SIDE EFFECTS sections for explanation.

While any option names can be used, the following have special meaning:

OPTIONS CONCERNING THE SESSION ENVIRONMENT

contrasts=:
vector of two character strings naming the default contrasts to use for factors and for ordered factors, respectively. This is primarily used in analysis of variance models.
echo=:
if TRUE, each complete expression will be echoed before it is evaluated.
width=:
the width (in characters) of the user's terminal.
length=:
the length (in lines) of an output page.
prompt=:
the string to be printed by the S-PLUS parser to prompt for an expression.
continue=:
the string to be printed by the S-PLUS parser to prompt for the continuation of an expression.
digits=:
number of significant digits to use in print (and therefore in automatic printing). Setting digits to 17 will give the full length of double precision numbers.
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 ed filename 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.
pager=:
default pager program; used in various places, including the help and page functions. Examples of pagers are the UNIX programs more or view. Whatever pager you choose will be invoked as pager filename and should read from filename. The default for pager is the value of environment variable S_PAGER, which in turn defaults to the value of environment variable PAGER, or "less" if that is not set.
interactive=:
logical flag: it is TRUE if S-PLUS is running interactively. The S-PLUS process itself will normally decide whether it is running interactively. (You can test this decision within a function by calling interactive.) Occasionally, you might need to lie about this situation; e.g., to run a normally interactive function like browser in a non-interactive way. If so, use this option, but with caution. Many side-effects, such as prompting for expressions, depend on whether S-PLUS is running interactively.
keep=:
determines what mode of objects are to be kept in an internal table once accessed in a session. The default strategy is keep="function", so that future calls will be faster since these functions will be found more efficiently. The most likely other strategy is keep=NULL which turns off keeping, and might be a good idea if you are about to access a large number of functions sequentially. S-PLUS 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. Beware the memory growth that may result with keep="any".
show=:
should graphics be shown directly or returned as a graphics object?
gui=:
character string giving the preferred graphical user interface. Choices are "Motif" and "OpenLook" (Sun machines only). The help.start and data.ed functions use this.
ts.eps=:
time series comparison tolerance. This small number is used throughout the time series functions for comparison of their frequencies. Frequencies are considered equal if they differ in absolute value by less than ts.eps.

OPTIONS CONCERNING ERROR HANDLING

check=:
if TRUE, S-PLUS 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-PLUS terminating abnormally), but, on the other hand, this has been known to introduce strange behavior. Evaluation will be substantially slower with this option turned on.
error=:
function (with no arguments) to be called when an error or interrupt occurs. S-PLUS provides dump.calls and dump.frames to dump the outstanding function calls or the entire associated frames. See the documentation for these functions for details. The option error=NULL eliminates all error actions.
interrupt=:
function (with no arguments) to be called when an interrupt occurs. The function is called in the frame active when the interrupt happens and can be used, for example, to examine current objects, to change values, etc. If two interrupts occur in a row, the interrupt action is not executed; instead the error action is carried out. The option interrupt=NULL eliminates interrupt actions.
warn=:
the level of strictness at which the system should warn you about non-fatal blemishes. At level 0, the first 50 warnings are collected and at the end of the evaluation these will be printed or (if there are more than 50) 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.
warning.expression=:
an expression to evaluate when there is a warning to report. This is more flexible than the use of options(warn=). If options("warning.expression") is not NULL then options(warn) is ignored. The C call .C("get_last_message","")[[1]] gives the warning message itself and sys.calls() gives the call stack at the time of the warning. For example, options(warning.expression=expression(cat("Warning in", substring(deparse(sys.calls()[[sys.nframe()]])[1], 1, 40), ":", .C("get_last_message","")[[1]], "\n"))) is very similar to using options(warn=1).
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.

OPTIONS CONCERNING MEMORY USAGE

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 Splus TRUNC_AUDIT to reduce the size of the audit file.
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-PLUS administrator may have chosen a reasonable value for your system; if so, you usually should not change it yourself.
free=:
if TRUE, S-PLUS 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.
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). You may want to check for memory growth by calling the function memory.size and if things are getting out of hand, quit and re-invoke S-PLUS.
object.size=:
the maximum size (in bytes) for any single S-PLUS object. If this limit is exceeded, an error is generated, but the session continues.
reference=:
if TRUE, the evaluator will use references to objects in other evaluation frames without copying them. This improves performance. Recent experiments indicate that there is no reason to use reference=FALSE.
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 compact 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.

The default values for these options are as follows: audit.size=5e5 check=FALSE compact=1e5 continue="+ " contrasts=c("contr.helmert", "contr.poly") digits=7 echo=FALSE editor="vi" error=dump.calls expressions=256 free=TRUE gui=NULL interrupt=NULL pager="less" keep="function" length=48 memory=2147483647 object.size=5e6 prompt="> " reference=TRUE scrap=500 show=TRUE ts.eps=1e-5 warn=0 width=80

VALUE:
options always returns a list - even if of length 1 (it differs from par in this respect). If no argument is given, the list of the current values of all options is returned.

If a character vector is given as the only argument, a list of the current values of the options named by the character vector is returned. Options that have never been set have the value NULL.

If an 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 (the side effect) and a list of the previous values of those options are returned. Generally, the list given as an argument is the value of a previous call to options.

Otherwise, arguments must be given in the name=value form, and a list is returned of the previous values of the options with these names.

SIDE EFFECTS:
when options are set, options changes a list named .Options in the session frame (frame 0). The components of .Options are all of the currently defined options.

If options is called with either a list as the single argument, or with one or more arguments in the name=value form, then options specified by the names in the argument(s) are changed or created.

NOTE:
If there are particular options that you usually want to be different than the default values, use options in your .First function.
DETAILS:
The special options recognized internally are driven from the object .Options; the options function 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 .Options 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 "silent log" 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.

In the last example an object called .Options is produced in the frame of the function. Functions that use an option get the value of the option from the first .Options object that is found.

There may be special options that do not exist by default but that are recognized by various functions when set. For example, options(core.dump=T) will cause S-PLUS to create a file named core if S-PLUS should terminate abnormally.

SEE ALSO:
help.start , data.ed . dump.calls , .First , memory.size , object.size , par , page, TRUNC_AUDIT.
EXAMPLES: 
amp;# sets the maximum length of line to 50 characters and returns a length
1 list
options(width = 50)
options(digits = 3, check = T)
options(c("compact","scrap"))  # view two particular options
temp <- options(prompt = "Say something! ", continue="\t")
   amp;# some computations, then
options(temp) # restore prompt and continue
silent.eval <- function(expr) {
        old <- options(warn = -1)
        on.exit(options(old))
        expr
}
silent.log <- function(x) {
        .Options$warn <- -1 #turn off NA warnings
        log(x)
}