example                package:utils                R Documentation

_R_u_n _a_n _E_x_a_m_p_l_e_s _S_e_c_t_i_o_n _f_r_o_m _t_h_e _O_n_l_i_n_e _H_e_l_p

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

   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
          '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.

prompt.prefix: character; prefixes the prompt to be used if 'echo =
          TRUE'.

_D_e_t_a_i_l_s:

     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

     '_d_o_n_t_r_u_n' encloses code that should not be run.

     '_d_o_n_t_s_h_o_w' 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.)

_V_a_l_u_e:

     The value of the last evaluated expression.

_N_o_t_e:

     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'.

_A_u_t_h_o_r(_s):

     Martin Maechler and others

_S_e_e _A_l_s_o:

     'demo'

_E_x_a_m_p_l_e_s:

     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