\HeaderA{example}{Run an Examples Section from the Online Help}{example}
\keyword{documentation}{example}
\keyword{utilities}{example}
\begin{Description}\relax
Run all the \R{} code from the \bold{Examples} part of \R's online help
topic \code{topic} with two possible exceptions, \code{dontrun} and
\code{dontshow}, see Details below.
\end{Description}
\begin{Usage}
\begin{verbatim}
example(topic, package = NULL, lib.loc = NULL,
        local = FALSE, echo = TRUE, verbose = getOption("verbose"),
        setRNG = FALSE,
        prompt.echo = paste(abbreviate(topic, 6),"> ", sep=""))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{topic}] name or literal character string: the online
\code{\LinkA{help}{help}} topic the examples of which should be run.
\item[\code{package}] a character vector giving the package names to look
into for example code, or \code{NULL}.  By default, all packages in
the search path are used.
\item[\code{lib.loc}] a character vector of directory names of \R{} libraries,
or \code{NULL}.  The default value of \code{NULL} corresponds to all
libraries currently known.  If the default is used, the loaded
packages are searched before the libraries.
\item[\code{local}] logical: if \code{TRUE} evaluate locally, if \code{FALSE}
evaluate in the workspace.
\item[\code{echo}] logical;  if \code{TRUE}, show the \R{} input when sourcing.
\item[\code{verbose}] logical;  if \code{TRUE}, show even more when running
example code.
\item[\code{setRNG}] logical or expression;  if not \code{FALSE}, the random
number generator state is saved, then initialized to a specified state,
the example is run and the (saved) state is restored.  \code{setRNG
      = TRUE} sets the same state as \code{R CMD \LinkA{check}{check}} does for
running a package's examples.  This is currently equivalent to
\code{setRNG = \{RNGkind("default", "default"); set.seed(1)\}}.
\item[\code{prompt.echo}] character; gives the prompt to be used if
\code{echo = TRUE}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If \code{lib.loc} is not specified, the packages are searched for
amongst those already loaded, then in the specified libraries.
If \code{lib.loc} is specified, they are searched for only
in the specified libraries, even if they are already loaded from
another library.

An attempt is made to load the package before running the examples,
but this will not replace a package loaded from another location.

If \code{local=TRUE} objects are not created in the workspace and so
not available for examination after \code{example} completes: on the
other hand they cannot clobber objects of the same name in the
workspace.

As detailed in the manual \emph{Writing \R{} Extensions}, the author of
the help page can markup parts of the examples for two exception rules
\describe{
\item[\code{dontrun}] encloses code that should not be run.
\item[\code{dontshow}] encloses code that is invisible on help
pages, but will be run both by the package checking tools,
and the \code{example()} function.  This was previously
\code{testonly}, and that form is still accepted.
}

If the examples file contains non-ASCII characters the encoding used
will matter.  If in a UTF-8 locale \code{example} first tries UTF-8
and then Latin-1.  (This can be overridden by setting the encoding in
the \code{.Rd} file.)
\end{Details}
\begin{Value}
The value of the last evaluated expression.
\end{Value}
\begin{Note}\relax
The examples can be many small files.  On some file systems it is
desirable to save space, and the files in the \file{R-ex} directory
of an installed package can be zipped up as a zip archive
\file{Rex.zip}.
\end{Note}
\begin{Author}\relax
Martin Maechler and others
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{demo}{demo}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
example(InsectSprays)
## force use of the standard package 'stats':
example("smooth", package="stats", lib.loc=.Library)

## set RNG *before* example as when R CMD check is run:

r1 <- example(quantile, setRNG = TRUE)
x1 <- rnorm(1)
u <- runif(1)
## identical random numbers
r2 <- example(quantile, setRNG = TRUE)
x2 <- rnorm(1)
stopifnot(identical(r1, r2))
## but x1 and x2 differ since the RNG state from before example()
## differs and is restored!
x1; x2
\end{ExampleCode}
\end{Examples}