topic
with possible exceptions dontrun
,
dontshow
, and donttest
, see 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())
help
topic the examples of which should be run.NULL
(the default), when all packages on
the search path are used.NULL
. The default value of NULL
corresponds to all
libraries currently known. If the default is used, the loaded
packages are searched before the libraries.topic
can be
assumed to be a character string.TRUE
evaluate locally, if FALSE
evaluate in the workspace.TRUE
, show the Rinput when sourcing.TRUE
, show even more when running
example 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.
setRNG = TRUE
sets the same state as
setRNG = {RNGkind("default", "default"); set.seed(1)}
."default"
) indicating if
devAskNewPage(ask = TRUE)
should be called
before graphical output happens from the example code. The value
"default"
(the factory-fresh default) means to ask if
echo == 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.echo = TRUE
.give.lines
is true, where a character
vector is returned.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 RExtensions, the author of
the help page can markup parts of the examples for exception rules
[object Object],[object Object],[object Object]
[object Object],[object Object]
demo
## 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)