The R Project SVN R

Rev

Rev 85981 | Rev 88907 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 85981 Rev 86132
Line 1... Line 1...
1 
% File src/library/utils/man/example.Rd
 1 
% File src/library/utils/man/example.Rd
2 
% Part of the R package, https://www.R-project.org
 2 
% Part of the R package, https://www.R-project.org
3 
% Copyright 1995-2023 R Core Team
 3 
% Copyright 1995-2024 R Core Team
4 
% Distributed under GPL 2 or later
 4 
% Distributed under GPL 2 or later
5 
 
 5 
 
6 
\name{example}
 6 
\name{example}
7 
\alias{example}
 7 
\alias{example}
8 
\title{Run an Examples Section from the Online Help}
 8 
\title{Run an Examples Section from the Online Help}
9 
\description{
 9 
\description{
10 
  Run all the \R code from the \bold{Examples} part of \R's online help
 10 
  Run all the \R code from the \bold{Examples} part of \R's online help
11 
  topic \code{topic} with possible exceptions \code{dontrun},
 11 
  topic \code{topic}, with possible exceptions due to \verb{\dontrun},
12 
  \code{dontshow}, and \code{donttest}, see \sQuote{Details} below.
 12 
  \verb{\dontshow}, and \verb{\donttest} tags, see \sQuote{Details} below.
13 
}
 13 
}
14 
\usage{
 14 
\usage{
15 
example(topic, package = NULL, lib.loc = NULL,
 15 
example(topic, package = NULL, lib.loc = NULL,
16 
        character.only = FALSE, give.lines = FALSE, local = FALSE,
 16 
        character.only = FALSE, give.lines = FALSE, local = FALSE,
17 
        type = c("console", "html"), echo = TRUE,
 17 
        type = c("console", "html"), echo = TRUE,
Line 62... Line 62...
62 
  \item{prompt.prefix}{character; prefixes the prompt to be used if
 62 
  \item{prompt.prefix}{character; prefixes the prompt to be used if
63 
    \code{echo} is true (as it is by default).}
 63 
    \code{echo} is true (as it is by default).}
64 
  \item{catch.aborts}{logical, passed on to \code{\link{source}()},
 64 
  \item{catch.aborts}{logical, passed on to \code{\link{source}()},
65 
    indicating that \I{\dQuote{abort}ing} errors should be caught.}
 65 
    indicating that \I{\dQuote{abort}ing} errors should be caught.}
66 
  \item{run.dontrun}{logical indicating that \verb{\dontrun}
 66 
  \item{run.dontrun}{logical indicating that \verb{\dontrun}
67 
    should be ignored.}
 67 
    should be ignored, i.e., do run the enclosed code.}
68 
  \item{run.donttest}{logical indicating that \verb{\donttest}
 68 
  \item{run.donttest}{logical indicating that \verb{\donttest}
69 
    should be ignored.}
 69 
    should be ignored, i.e., do run the enclosed code.}
70 
}
 70 
}
71 
\value{
 71 
\value{
72 
  The value of the last evaluated expression, unless \code{give.lines}
 72 
  The value of the last evaluated expression, unless \code{give.lines}
73 
  is true, where a \code{\link{character}} vector is returned.
 73 
  is true, where a \code{\link{character}} vector is returned.
74 
}
 74 
}
Line 86... Line 86...
86 
  If \code{local = TRUE} objects are not created in the workspace and so
 86 
  If \code{local = TRUE} objects are not created in the workspace and so
87 
  not available for examination after \code{example} completes: on the
 87 
  not available for examination after \code{example} completes: on the
88 
  other hand they cannot overwrite objects of the same name in the
 88 
  other hand they cannot overwrite objects of the same name in the
89 
  workspace.
 89 
  workspace.
90 
 
 90 
 
91 
  As detailed in the manual \emph{Writing \R Extensions}, the author of
 91 
  As detailed in the \sQuote{Writing R Extensions} manual, the author of
92 
  the help page can markup parts of the examples for exception rules
 92 
  the help page can tag parts of the examples with the following
- 
 
 93 
  exception rules:
93 
  \describe{
 94 
  \describe{
94 
    \item{\code{dontrun}}{encloses code that should not be run.}
 95 
    \item{\verb{\dontrun}}{encloses code that should not be run.}
95 
    \item{\code{dontshow}}{encloses code that is invisible on help
 96 
    \item{\verb{\dontshow}}{encloses code that is invisible on help
96 
      pages, but will be run both by the package checking tools,
 97 
      pages, but will be run both by the package checking tools,
97 
      and the \code{example()} function.  This was previously
 98 
      and the \code{example()} function.  This was previously
98 
      \code{testonly}, and that form is still accepted.}
 99 
      \verb{\testonly}, and that form is still accepted.}
99 
    \item{\code{donttest}}{encloses code that typically should be run,
 100 
    \item{\verb{\donttest}}{encloses code that typically should be run,
100 
      but not during package checking.  The default
 101 
      but not during package checking.  The default
101 
      \code{run.donttest = \link{interactive}()}
 102 
      \code{run.donttest = \link{interactive}()}
102 
      leads \code{example()} use in other help
 103 
      leads \code{example()} use in other help
103 
      page examples to skip \verb{\donttest} sections appropriately.}
 104 
      page examples to skip \verb{\donttest} sections appropriately.}
104 
  }
 105 
  }
- 
 
 106 
  The additional \verb{\dontdiff} tag (in \R \eqn{\ge} 4.4.0) produces
- 
 
 107 
  special comments in the code run by \code{example} (for
- 
 
 108 
  \code{\link{Rdiff}}-based testing of example output), but does not
- 
 
 109 
  affect which code is run or displayed on the help page.
105 
}
 110 
}
106 
\author{Martin Maechler and others}
 111 
\author{Martin Maechler and others}
107 
\seealso{\code{\link{demo}}}
 112 
\seealso{\code{\link{demo}}}
108 
\examples{
 113 
\examples{
109 
example(InsectSprays)
 114 
example(InsectSprays)