\Header{options}{Options Settings}
\alias{.Options}{options}
\alias{getOption}{options}
\keyword{environment}{options}
\keyword{error}{options}
\keyword{print}{options}
\begin{Description}\relax
\code{options} allows the user to set and examine a variety of global
``options'' which affect the way in which \R{} computes and displays
its results.\end{Description}
\begin{Usage}
\begin{verbatim}
options(...)
getOption(x)
.Options
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{...}] any options can be defined, using \code{name = value}.
However, only the ones below are used in ``base \R''.

Further, \code{options('name') == options()['name']}, see the example.

\item[\code{prompt}] a string, used for \R's prompt; should usually end in a
blank (\code{" "}).
\item[\code{continue}] a string setting the prompt used for lines which continue
over one line.
\item[\code{width}] controls the number of characters on a line.  You may
want to change this if you re-size the window that \R{} is running in.
\item[\code{digits}] controls the number of digits to print when printing
numeric values.  It is a suggestion only.
\item[\code{editor}] sets the default text editor, e.g., for
\code{\Link{edit}}. Set from the environment variable \code{VISUAL}
on UNIX.
\item[\code{pager}] the (stand-alone) program used for displaying ASCII files on
\R's console.
Defaults to \file{\$R\_HOME/bin/pager}.

\item[\code{browser}] default HTML browser used by \code{\Link{help.start}()}
on UNIX.
\item[\code{mailer}] default mailer used by \code{\Link{bug.report}()}. can
be \code{"none"}.
\item[\code{contrasts}] the default \code{\Link{contrasts}} used in model
fitting such as with \code{\Link{aov}} or \code{\Link{lm}}.  A
character vector of length two, the first giving the function to be
used with unordered factors and the second the function to be used
with ordered factors.
\item[\code{expressions}] sets a limit on the number of nested expressions that
will be evaluated.  This is especially important on the Macintosh
since stack overflow is likely if this is set too high.
\item[\code{keep.source}] When \code{TRUE}, the source code for functions
(newly defined or loaded) is stored in their \code{"source"}
attribute (see \code{\Link{attr}}) allowing comments to be kept in
the right places.

The default is \code{\Link{interactive}()}, i.e., \code{TRUE} for
interactive use.
\item[\code{keep.source.pkgs}] As for \code{keep.source}, for functions in
packages loaded by \code{\Link{library}} or \code{\Link{require}}.
Defaults to \code{FALSE} unless the environment variable
\code{R\_KEEP\_PKG\_SOURCE} is set to \code{yes}.
\item[\code{na.action}] the name of a function for treating missing values
(\code{\Link{NA}}'s) for certain situations.
\item[\code{papersize}] the default paper format used by \code{\Link{postscript}};
set by environment variable \code{R\_PAPERSIZE} when \R{} is started
and defaulting to \code{"a4"} if that is unset or invalid.
\item[\code{printcmd}] the command used by \code{\Link{postscript}} for
printing; set by environment variable \code{R\_PRINTCMD} when \R{} is
started. This should be a command that expects either input to be piped
to \file{stdin} or to be given a single filename argument.
\item[\code{latexcmd, dvipscmd}] character strings giving commands to be used
in off-line printing of help pages.
\item[\code{show.signif.stars, show.coef.Pvalues}] logical, affecting P value
printing, see \code{\Link{print.coefmat}}.
\item[\code{ts.eps}] the relative tolerance for certain time series
(\code{\Link{ts}}) computations.
\item[\code{error}] an expression governing the handling of non-catastrophic
errors such as those generated by \code{\Link{stop}} as well as by
signals and internally detected errors. The default expression is
\code{NULL}: see \code{\Link{stop}} for the behaviour in that case.
The function \code{\Link{dump.frames}} provides one alternative that
allows post-mortem debugging.
\item[\code{show.error.messages}] a logical. Should error messages be
printed?  Intended for use with \code{\Link{try}} or a
user-installed error handler.
\item[\code{warn}] sets the handling of warning messages.  If \code{warn}
is negative all warnings are ignored.  If \code{warn} is zero
(the default) warnings are stored until the top--level function
returns.  If fewer than 10 warnings were signalled they will be printed
otherwise a message saying how many (max 50) were signalled.  A
top--level variable called \code{last.warning} is created and can be
viewed through the function \code{\Link{warnings}}.  If \code{warn} is
one, warnings are printed as they occur.  If \code{warn} is two or
larger all warnings are turned into errors.
\item[\code{echo}] logical. Only used in non-interactive mode, when it
controls whether input is echoed. Command-line options
\code{--quiet} and \code{--slave} set this initially to \code{FALSE}.
\item[\code{verbose}] logical. Should \R{} report extra information on
progress? Set to \code{TRUE} by the command-line option
\code{--verbose}.
\item[\code{device}] a character string giving the default device for that
session. This defaults to the normal screen device (e.g. \code{x11},
\code{windows} or \code{gtk}) for an interactive session, and
\code{postscript} in batch use or if a screen is not available.
\item[\code{X11colortype}] The default colour type for \code{\Link{X11}} devices.
\item[\code{CRAN}] The URL of the preferred CRAN node for use by
\code{\Link{update.packages}}. Defaults to
\url{http://cran.r-project.org}.
\item[\code{unzip}] the command used unzipping help files.

\item[\code{de.cellwidth}] integer: the cell widths (number of  characters)
to be used in the data editor \code{\Link{dataentry}}.  If this is
unset, 0, negative or \code{NA}, variable cell widths are used.
\item[\code{x}] a character string holding one of the above option names.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Invoking \code{options()} with no arguments returns a list with the
current values of the options.  To access the value of a single
option, one should use \code{getOption("width")}, e.g., rather than
\code{options("width")} which is a \emph{list} of length one.

The default settings of some of these options are
\Tabular{llll}{
\code{prompt} & \code{"> "} &
\code{continue} & \code{"+ "}\\
\code{width}  & \code{80} &
\code{digits} & \code{7}\\
\code{expressions} & \code{500} &
\code{keep.source} & \code{TRUE}\\
\code{show.signif.stars} & \code{TRUE} &
\code{show.coef.Pvalues} & \code{TRUE}\\
\code{na.action} & \code{na.omit} &
\code{ts.eps} & \code{1e-5}\\
\code{error} & \code{NULL} &
\code{warn} & \code{0}\\
\code{echo} & \code{TRUE} &
\code{verbose} & \code{FALSE}
}
Others are set from environment variables or are platform-dependent.\end{Details}
\begin{Value}
A list (in any case) with the previous values of the options changed,
or all options when no arguments were given.\end{Value}
\begin{Examples}
\begin{ExampleCode}
options() # printing all current options
op <- options(); str(op) # nicer printing

# .Options is the same:
all(sapply(1:length(op), function(i) all(.Options[[i]] == op[[i]])))

options('width')[[1]] == options()$width # the latter needs more memory
options(digits=20)
pi

# set the editor, and save previous value
old.o <- options(editor="nedit")
old.o

options(op)     # reset (all) initial options
options('digits')

## set contrast handling to be like S
options(contrasts=c("contr.helmert", "contr.poly"))

## on error, terminate the R session with error status 66
options(error=quote(q("no", status=66, runLast=FALSE)))
stop("test it")

## set an error action for debugging: see ?debugger.
options(error=quote(dump.frames()))
## A possible setting for non-interactive sessions
options(error=quote({dump.frames(to.file=TRUE); q()}))
\end{ExampleCode}
\end{Examples}

