R: Run an Examples Section from the Online Help

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 `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 of `NULL` 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, if `FALSE` evaluate in the workspace.
`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 `knitr` package is installed. Several other arguments are silently ignored in that case, including `setRNG` and `lib.loc`.
`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 as `R CMD check` does for running a package's examples. This is currently equivalent to `setRNG = {RNGkind("default", "default", "default"); set.seed(1)}`.
`ask`	logical (or `"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` is 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` is true (as it is by default).
`catch.aborts`	logical, passed on to `source()`, indicating that “abort”ing errors should be caught.
`run.dontrun`	logical indicating that `⁠\dontrun⁠` should be ignored, i.e., do run the enclosed code.
`run.donttest`	logical indicating that `⁠\donttest⁠` should be ignored, i.e., do run the enclosed code.

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() leads example() 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

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)

[Package utils version 4.4.1 Index]