example                package: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 = .packages(), lib.loc = NULL,
             local = FALSE, echo = TRUE, verbose = getOption("verbose"),
             setRNG = FALSE,
             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 with package names.  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)}'.

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.

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 randum 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

