The R Project SVN R

\name{options}
\alias{options}
\alias{.Options}
\alias{getOption}
\title{Options Settings}
\usage{
options(\dots)
getOption(x)
.Options
}
\arguments{
  \item{\dots}{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{prompt}{a string, used for \R's prompt; should usually end in a
    blank (\code{" "}).}

  \item{continue}{a string setting the prompt used for lines which continue
    over one line.}

  \item{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{digits}{controls the number of digits to print when printing
    numeric values.  It is a suggestion only.}

  \item{editor}{sets the default text editor, e.g., for
    \code{\link{edit}}. Set from the environment variable \code{VISUAL}
    on UNIX.}

  \item{pager}{the (stand-alone) program used for displaying ASCII files on
    \R's console.
#ifdef unix
   Defaults to \file{\$R\_HOME/bin/pager}.
#endif
#ifdef windows
   Defaults to \code{"internal"}, which uses a pager similar to the GUI
   console. Another possibility is \code{"console"} to use the console itself.
#endif
  }

  \item{browser}{default HTML browser used by \code{\link{help.start}()}
    on UNIX.}

  \item{mailer}{default mailer used by \code{\link{bug.report}()}. can
    be \code{"none"}.}

  \item{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{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{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{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{na.action}{the name of a function for treating missing values
    (\code{\link{NA}}'s) for certain situations.}

  \item{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{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.}
#ifdef unix
  \item{latexcmd, dvipscmd}{character strings giving commands to be used
    in off-line printing of help pages.}
#endif

  \item{show.signif.stars, show.coef.Pvalues}{logical, affecting P value
    printing, see \code{\link{print.coefmat}}.}

  \item{ts.eps}{the relative tolerance for certain time series
    (\code{\link{ts}}) computations.}

  \item{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{show.error.messages}{a logical. Should error messages be
    printed?  Intended for use with \code{\link{try}} or a
    user-installed error handler.}

  \item{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{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{verbose}{logical. Should \R report extra information on
    progress? Set to \code{TRUE} by the command-line option
    \code{--verbose}.}

  \item{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.}
#ifdef unix
  \item{X11colortype}{The default colour type for \code{\link{X11}} devices.}
#endif

  \item{CRAN}{The URL of the preferred CRAN node for use by
    \code{\link{update.packages}}. Defaults to
    \url{http://cran.r-project.org}.}

  \item{unzip}{the command used unzipping help files.
#ifdef windows
    Defaults to "internal" when the internal unzip DLL is used.
#endif
  }
  \item{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{x}{a character string holding one of the above option names.}
}
\description{
  \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.
}
\details{
  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} \tab \code{"> "} \tab
    \code{continue} \tab \code{"+ "}\cr
    \code{width}  \tab \code{80} \tab
    \code{digits} \tab \code{7}\cr
    \code{expressions} \tab \code{500} \tab
    \code{keep.source} \tab \code{TRUE}\cr
    \code{show.signif.stars} \tab \code{TRUE} \tab
    \code{show.coef.Pvalues} \tab \code{TRUE}\cr
    \code{na.action} \tab \code{na.omit} \tab
    \code{ts.eps} \tab \code{1e-5}\cr
    \code{error} \tab \code{NULL} \tab
    \code{warn} \tab \code{0}\cr
    \code{echo} \tab \code{TRUE} \tab
    \code{verbose} \tab \code{FALSE}
  }
  Others are set from environment variables or are platform-dependent.
}
\value{
  A list (in any case) with the previous values of the options changed,
  or all options when no arguments were given.
}
\examples{
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')

\dontrun{## set contrast handling to be like S
options(contrasts=c("contr.helmert", "contr.poly"))
}
\dontrun{## on error, terminate the R session with error status 66
options(error=quote(q("no", status=66, runLast=FALSE)))
stop("test it")
}
\dontrun{## 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()}))
}}
\keyword{environment}
\keyword{error}
\keyword{print}