example {utils} | R Documentation |
Run an Examples Section from the Online Help
Description
Run all the R code from the Examples part of R's online help
topic topic
, with possible exceptions due to \dontrun
,
\dontshow
, and \donttest
tags, see ‘Details’ below.
Usage
example(topic, package = NULL, lib.loc = NULL,
character.only = FALSE, give.lines = FALSE, local = FALSE,
type = c("console", "html"), echo = TRUE,
verbose = getOption("verbose"),
setRNG = FALSE, ask = getOption("example.ask"),
prompt.prefix = abbreviate(topic, 6),
catch.aborts = FALSE,
run.dontrun = FALSE, run.donttest = interactive())
Arguments
topic |
name or literal character string: the online
|
package |
a character vector giving the package names to look
into for the topic, or |
lib.loc |
a character vector of directory names of R libraries,
or |
character.only |
a logical indicating whether |
give.lines |
logical: if true, the lines of the example source code are returned as a character vector. |
local |
logical: if |
type |
character: whether to show output in the console or a
browser (using the dynamic help system). The latter is honored only
in interactive sessions and if the |
echo |
logical; if |
verbose |
logical; if |
setRNG |
logical or expression; if not |
ask |
logical (or |
prompt.prefix |
character; prefixes the prompt to be used if
|
catch.aborts |
logical, passed on to |
run.dontrun |
logical indicating that |
run.donttest |
logical indicating that |
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 ‘Writing R Extensions’ manual, the author of the help page can tag parts of the examples with the following 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 previously\testonly
, 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.
The additional \dontdiff
tag (in R \ge
4.4.0) produces
special comments in the code run by example
(for
Rdiff
-based testing of example output), but does not
affect which code is run or displayed on the help page.
Value
The value of the last evaluated expression, unless give.lines
is true, where a character
vector is returned.
Author(s)
Martin Maechler and others
See Also
Examples
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)
lengths(lmex)