example
Run an Examples Section from the Online Help
Run all the R code from the Examples part of R's online help
topic topic
with possible exceptions dontrun
,
dontshow
, and donttest
, see ‘Details’ below.
- Keywords
- utilities, documentation
Usage
example(topic, package = NULL, lib.loc = NULL,
character.only = FALSE, give.lines = FALSE, local = FALSE,
echo = TRUE, verbose = getOption("verbose"),
setRNG = FALSE, ask = getOption("example.ask"),
prompt.prefix = abbreviate(topic, 6),
run.dontrun = FALSE, run.donttest = interactive())
Arguments
- topic
name or literal character string: the online
help
topic the examples of which should be run.- package
a character vector giving the package names to look into for the topic, or
NULL
(the default), when all packages on the search path are used.- lib.loc
a character vector of directory names of R libraries, or
NULL
. The default value ofNULL
corresponds to all libraries currently known. If the default is used, the loaded packages are searched before the libraries.- character.only
a logical indicating whether
topic
can be assumed to be a character string.- give.lines
logical: if true, the lines of the example source code are returned as a character vector.
- local
logical: if
TRUE
evaluate locally, ifFALSE
evaluate in the workspace.- echo
logical; if
TRUE
, show the R input when sourcing.- verbose
logical; if
TRUE
, show even more when running example code.- setRNG
logical or expression; if not
FALSE
, the random number generator state is saved, then initialized to a specified state, the example is run and the (saved) state is restored.setRNG = TRUE
sets the same state asR CMD check
does for running a package's examples. This is currently equivalent tosetRNG = {RNGkind("default", "default", "default"); set.seed(1)}
.- ask
logical (or
"default"
) indicating ifdevAskNewPage(ask = TRUE)
should be called before graphical output happens from the example code. The value"default"
(the factory-fresh default) means to ask ifecho == TRUE
and the graphics device appears to be interactive. This parameter applies both to any currently opened device and to any devices opened by the example code.- prompt.prefix
character; prefixes the prompt to be used if
echo = TRUE
.- run.dontrun
logical indicating that
\dontrun
should be ignored.- run.donttest
logical indicating that
\donttest
should be ignored.
Details
If lib.loc
is not specified, the packages are searched for
amongst those already loaded, then in the libraries given by
.libPaths()
. If lib.loc
is specified, packages
are searched for only in the specified libraries, even if they are
already loaded from another library. The search stops at the first
package found that has help on the topic.
An attempt is made to load the package before running the examples, but this will not replace a package loaded from another location.
If local = TRUE
objects are not created in the workspace and so
not available for examination after example
completes: on the
other hand they cannot overwrite objects of the same name in the
workspace.
As detailed in the manual Writing R Extensions, the author of the help page can markup parts of the examples for exception rules
dontrun
encloses code that should not be run.
dontshow
encloses code that is invisible on help pages, but will be run both by the package checking tools, and the
example()
function. This was previouslytestonly
, and that form is still accepted.donttest
encloses code that typically should be run, but not during package checking. The default
run.donttest = interactive()
leadsexample()
use in other help page examples to skip\donttest
sections appropriately.
Value
The value of the last evaluated expression, unless give.lines
is true, where a character
vector is returned.
See Also
Examples
library(utils)
# NOT RUN {
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
## Exploring examples code:
## How large are the examples of "lm...()" functions?
lmex <- sapply(apropos("^lm", mode = "function"),
example, character.only = TRUE, give.lines = TRUE)
sapply(lmex, length)
# }