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 two possible exceptions, dontrun and dontshow, see Details below.

Usage

example(topic, package = NULL, lib.loc = NULL,
        local = FALSE, echo = TRUE, verbose = getOption("verbose"),
        setRNG = FALSE, ask = getOption("example.ask"),
        prompt.echo = paste(abbreviate(topic, 6),"> ", sep=""))

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 example code, or NULL. By default, all packages in 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.
local logical: if TRUE evaluate locally, if FALSE 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 as R CMD check does for running a package's examples. This is currently equivalent to setRNG = {RNGkind("default", "default"); set.seed(1)}.
ask logical (or "default") indicating if par(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.
prompt.echo character; gives the prompt to be used if echo = TRUE.

Details

If lib.loc is not specified, the packages are searched for amongst those already loaded, then in the specified libraries. If 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 local=TRUE objects are not created in the workspace and so not available for examination after example completes: on the other hand they cannot clobber 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 two 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.

If the examples file contains non-ASCII characters the encoding used will matter. If in a UTF-8 locale example first tries UTF-8 and then Latin-1. (This can be overridden by setting the encoding in the .Rd file.)

Value

The value of the last evaluated expression.

Note

The examples can be many small files. On some file systems it is desirable to save space, and the files in the ‘R-ex’ directory of an installed package can be zipped up as a zip archive ‘Rex.zip’.

Author(s)

Martin Maechler and others

See Also

demo

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
[Package utils version 2.4.1 Index]