\Header{options}{Options Settings}
\alias{.Options}{options}
\alias{getOption}{options}
\keyword{environment}{options}
\keyword{error}{options}
\keyword{print}{options}
\begin{Description}\relax
Allow the user to set and examine a variety of global \dQuote{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 \dQuote{base \R}.

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

\item[\code{x}] a character string holding an option name.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Invoking \code{options()} with no arguments returns a list with the
current values of the options.  Note that not all options listed below
are set initially.  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.

\code{.Options} also always contains the \code{options()} list, for
S compatibility.  You must use it \dQuote{read only} however.
\end{Details}
\begin{Value}
For \code{options}, a list (in any case) with the previous values of
the options changed, or all options when no arguments were given.
\end{Value}
\begin{Section}{Options used in base \R}
\describe{
\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.  Valid values are 10\dots10000 with default normally
80.  (The valid values are in file \file{Print.h} and can be
changed by re-compiling \R.)

\item[\code{digits}:] controls the number of digits to print when
printing numeric values.  It is a suggestion only.  Valid values
are 1\dots22 with default 7.  See \code{\Link{print.default}}.

\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, also used by \code{\Link{file.show}} and
sometimes \code{\Link{help}}.
Defaults to \file{\$R\_HOME/bin/pager}.


\item[\code{browser}:] default HTML browser used by
\code{\Link{help.start}()} on UNIX, or a non-default browser on
Windows.

\item[\code{pdfviewer}:] default PDF viewer.  Set from the
environment variable \env{R\_PDFVIEWER}.

\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{defaultPackages}:] the packages that are attached by
default when \R{} starts up.  Initially set from value of the
environment variables \env{R\_DefaultPackages}, or if that is unset
to \code{c("utils", "stats", "graphics", "methods")}.  (Set
\env{R\_DEFAULT\_PACKAGES} to \code{NULL} or a comma-separated list
of package names.)  A call to \code{options} should be in your
\file{.Rprofile} file to ensure that the change takes effect
before the base package is initialized (see \code{\Link{Startup}}).

\item[\code{expressions}:] sets a limit on the number of nested
expressions that will be evaluated.
Valid values are 25\dots100000 with default 500.

\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 \env{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
\env{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 \env{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{printCoefmat}}.

\item[\code{ts.eps}:] the relative tolerance for certain time series
(\code{\Link{ts}}) computations.

\item[\code{error}:] either a function or 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.  If the option is a function, a call to that function,
with no arguments, is generated as the expression.  The default
value 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{warning.length}:] sets the truncation limit for error
and warning messages.  A non-negative integer, with allowed values
100--8192, default 1000.

\item[\code{warning.expression}:] an \R{} code expression to be called
if a warning is generated, replacing the standard message.  If
non-null is called irrespective of the value of option
\code{warn}.

\item[\code{check.bounds}:] logical, defaulting to \code{FALSE}.  If
true, a \link{warning} is produced whenever a \dQuote{generalized
vector} (atomic or \code{\Link{list}}) is extended, by something
like \code{x <- 1:3; x[5] <- 6}.

\item[\code{echo}:] logical.  Only used in non-interactive mode,
when it controls whether input is echoed.  Command-line option
\option{--slave} sets 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
\option{--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{repositories}:] A function that when evaluated returns a
named vector of URLs which can be used to specify the set and
order of any online repositories the user would like used in
functions such as \code{\Link{packageDepends}}.  The default
return value for the function is a vector with two components, one the 
value of \code{contrib.url(getOption("CRAN"))} and the second
\code{contrib.url(getOption("BIOC"))}.

\item[\code{download.file.method}:] Method to be used for
\code{download.file}.  Currently download methods
\code{"internal"}, \code{"wget"} and \code{"lynx"} are available.
There is no default for this option, when \code{method = "auto"}
is chosen: see \code{\Link{download.file}}.

\item[\code{unzip}:] the command used for unzipping help files.
Defaults to the value of \env{R\_UNZIPCMD}, which is set in
\file{etc/Renviron} if an \code{unzip} command was found during
configuration.

\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{encoding}:] An integer vector of length 256 holding an
input encoding.  Defaults to \code{native.enc} (= \code{0:255}).
See \code{\Link{connections}}.

\item[\code{timeout}:] integer.  The timeout for some Internet
operations, in seconds.  Default 60 seconds.
See \code{\Link{download.file}} and \code{\Link{connections}}.

\item[\code{internet.info}:] The minimum level of information to be
printed on URL downloads etc.  Default is 2, for failure causes.
Set to 1 or 0 to get more information.

\item[\code{scipen}:] integer.  A penalty to be applied
when deciding to print numeric values in fixed or exponential
notation.  Positive values bias towards fixed and negative towards
scientific notation: fixed notation will be preferred unless it is
more than \code{scipen} digits wider.

\item[\code{locatorBell}:] logical.  Should selection in \code{locator}
and \code{identify} be confirmed by a bell.  Default \code{TRUE}.
Honoured at least on \code{X11} and \code{windows} devices.
\item[\code{X11fonts}:] character vector of length 2.
See \code{\Link{X11}}.
}

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{show.error.messages} & \code{TRUE} \\
\code{warn} & \code{0}&
\code{warning.length} & \code{1000}\\
\code{echo} & \code{TRUE} &
\code{verbose} & \code{FALSE} \\
\code{scipen} & \code{0} & \code{locatorBell} & \code{TRUE}
}
Others are set from environment variables or are platform-dependent.
\end{Section}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\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) if(is.atomic(op[[i]]))
                         {all(.Options[[i]] == op[[i]])} else TRUE))

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(check.bounds = TRUE)
x <- NULL; x[4] <- "yes" # gives a warning

options(digits=5)
print(1e5)
options(scipen=3); print(1e5)

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

## Not run: 
## set contrast handling to be like S
options(contrasts=c("contr.helmert", "contr.poly"))
## End(Not run)
## Not run: 
## on error, terminate the R session with error status 66
options(error=quote(q("no", status=66, runLast=FALSE)))
stop("test it")
## End(Not run)
## Not run: 
## set an error action for debugging: see ?debugger.
options(error=dump.frames)
## A possible setting for non-interactive sessions
options(error=quote({dump.frames(to.file=TRUE); q()}))
## End(Not run)\end{ExampleCode}
\end{Examples}

