\name{runExample}
\alias{runExample}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Run or access example files}
\description{
  This function finds and runs a file,  usually of R code.  The
  function is specialized to look for examples included in the package
  and based on material in \emph{Software for Data Analysis}, but can
  be used for other directories containing source files as well.
}
\usage{
runExample(what, where = , run = TRUE, ..., echo = TRUE, prompt.echo, wd)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{what}{ Identifies the example to be run.  Can be either a  character string name of the file to be run,
      possibly without the suffix or the page in  \emph{Software for
        Data Analysis} where the example appears.  See
      \code{\link{exampleFiles}} for details. }
  \item{where}{ The character string name of the package or directory
      in which the files are to be found.  By
      default, and usually, it is
      the \code{SoDA} package.  If a package name is given, that
      package must have an \code{"Examples"} directory.}
  \item{run}{ Should the example code be run, or only parsed, assuming
    it is R source code?}
  \item{\dots, echo, prompt.echo}{ Any optional arguments to the \code{\link{source}}
      function, assuming \code{run} is \code{TRUE}. The default for
      \code{prompt.echo} is constructed from an abbreviation of the
      file name. }
  \item{wd}{ The working directory in which to run the example. If the
      argument is missing and \code{where} is a package, the working
      directory is the package directory, which is also the parent
      directory of the \code{Examples} directory.

      If \code{where} is a directory and not a package, and \code{wd}
      is missing, then the working directory is not changed.
      Otherwise, the working directory is set before running the
      example and reset after.  As you would hope, this argument is
      ignored if \code{run} is \code{FALSE}.
      }
}
\value{
  If the file is an R source file, the function returns either the
  value from \code{source} or the parsed version of the file,
  according to whether \code{run} is \code{TRUE}.

  For non-R files, the value is currently just the character vector
  containing the lines of the file.  Future versions may be a little
  more clever.
}
\seealso{\code{\link{demoSource}} for a more interactive way to run a
  file of R code, and \code{\link{exampleFiles}} for direct access to
  the path of the file. }
\references{
Chambers, John M.(2008) \emph{Software for Data Analysis}, Springer.
}
\examples{
\dontrun{
runExample("madCall")  # run file "madCall.R"
runExample(53) # the example appearing on page 53 of the book.
}
}
\keyword{programming }