The R Project SVN R

% File src/library/base/man/srcfile.Rd
% Part of the R package, http://www.R-project.org
% Copyright 1995-2008 R Core Development Team
% Distributed under GPL 2 or later

\name{srcfile}
\alias{srcfile}
\alias{srcfilecopy}
\alias{getSrcLines}
\alias{srcref}
\alias{srcfile-class}
\alias{srcfilecopy-class}
\alias{srcref-class}
\alias{print.srcfile}
\alias{summary.srcfile}
\alias{open.srcfile}
\alias{open.srcfilecopy}
\alias{close.srcfile}
\alias{print.srcref}
\alias{summary.srcref}
\alias{as.character.srcref}
\alias{.isOpen}

\title{References to source files}
\description{
These functions are for working with source files.
}
\usage{
srcfile(filename, encoding = getOption("encoding"), Enc = "unknown")
srcfilecopy(filename, lines)
getSrcLines(srcfile, first, last)
srcref(srcfile, lloc)
\method{print}{srcfile}(x, \dots)
\method{summary}{srcfile}(object, \dots)
\method{open}{srcfile}(con, line, \dots)
\method{close}{srcfile}(con, \dots)
\method{print}{srcref}(x, useSource = TRUE, \dots)
\method{summary}{srcref}(object, useSource = FALSE, \dots)
\method{as.character}{srcref}(x, useSource = TRUE, \dots)
.isOpen(srcfile)
}
\arguments{
  \item{filename}{ The name of a file }
  \item{encoding}{ The character encoding to assume for the file }
  \item{Enc}{ The encoding with which to make strings: see the
    \code{encoding} argument of \code{\link{parse}}.}
  \item{lines}{ A character vector of source lines.  Other \R objects
    will be coerced to character. }
  \item{srcfile}{ A \code{srcfile} object. }
  \item{first, last, line}{ Line numbers. }
  \item{lloc}{ A vector of four or six values giving a source location; see
    \sQuote{Details}.}
  \item{x, object, con}{ An object of the appropriate class. }
  \item{useSource}{ Whether to read the \code{srcfile} to obtain the
    text of a \code{srcref}. }
  \item{\dots}{ Additional arguments to the methods; these will be ignored. }
}
\details{
  These functions and classes handle source code references.

  The \code{srcfile} function produces an object of class
  \code{srcfile}, which contains the name and directory of a source code
  file, along with its timestamp, for use in source level debugging (not
  yet implemented) and source echoing.  The encoding of the file is
  saved; see \code{\link{file}} for a discussion of encodings, and
  \code{\link{iconvlist}} for a list of allowable encodings on your platform.

  The \code{srcfilecopy} function produces an object of the descendant
  class \code{srcfilecopy}, which saves the source lines in a character
  vector.

  The \code{getSrcLines} function reads the specified lines from
  \code{srcfile}.

  The \code{srcref} function produces an object of class
  \code{srcref}, which describes a range of characters in a
  \code{srcfile}.  The \code{lloc} value gives the following values:
  \code{c(first_line, first_byte, last_line, last_byte, first_column,
  last_column)}.  (Bytes and columns may be different due to multibyte
  characters.  If only four values are given, the columns and
  bytes are assumed to match.)

  Methods are defined for \code{print}, \code{summary}, \code{open},
  and \code{close} for classes \code{srcfile} and \code{srcfilecopy}.
  The \code{open} method opens its internal \code{file} connection at
  a particular line; if it was already open, it will be repositioned
  to that line.

  Methods are defined for \code{print}, \code{summary} and
  \code{as.character} for class \code{srcref}.  The
  \code{as.character} method will read the associated source file to
  obtain the text corresponding to the reference.  If an error occurs
  (e.g. the file no longer exists), text like \code{<srcref: "file"
  chars 1:1 to 2:10>} will be returned instead, indicating the
  \code{line:column} ranges of the first and last character.  The
  \code{summary} method defaults to this type of display.

  Lists of \code{srcref} objects may be attached to expressions as the
  \code{"srcref"} attribute.  (The list of \code{srcref} objects should be the same
  length as the expression.)  By default, expressions are printed by
  \code{\link{print.default}} using the associated \code{srcref}.  To
  see deparsed code instead, call \code{\link{print}} with argument
  \code{useSource = FALSE}.  If a \code{srcref} object
  is printed with \code{useSource = FALSE}, the \code{<srcref: \dots>}
  record will be printed.

  \code{.isOpen} is intended for internal use:  it checks whether the
  connection associated with a \code{srcfile} object is open.
}
\value{
\code{srcfile} returns a \code{srcfile} object.

\code{srcfilecopy} returns a \code{srcfilecopy} object.

\code{getSrcLines} returns a character vector of source code lines.

\code{srcref} returns a \code{srcref} object.
}
\author{Duncan Murdoch}

\examples{
src <- srcfile(system.file("DESCRIPTION", package = "base"))
summary(src)
getSrcLines(src, 1, 4)
ref <- srcref(src, c(1, 1, 2, 1000))
ref
print(ref, useSource = FALSE)
}

\keyword{ debugging }
\keyword{ utilities }