\HeaderA{srcfile}{References to source files}{srcfile}
\aliasA{.isOpen}{srcfile}{.isOpen}
\aliasA{as.character.srcref}{srcfile}{as.character.srcref}
\aliasA{close.srcfile}{srcfile}{close.srcfile}
\aliasA{getSrcLines}{srcfile}{getSrcLines}
\aliasA{open.srcfile}{srcfile}{open.srcfile}
\aliasA{open.srcfilecopy}{srcfile}{open.srcfilecopy}
\aliasA{print.srcfile}{srcfile}{print.srcfile}
\aliasA{print.srcref}{srcfile}{print.srcref}
\aliasA{srcfile-class}{srcfile}{srcfile.Rdash.class}
\aliasA{srcfilecopy}{srcfile}{srcfilecopy}
\aliasA{srcfilecopy-class}{srcfile}{srcfilecopy.Rdash.class}
\aliasA{srcref}{srcfile}{srcref}
\aliasA{srcref-class}{srcfile}{srcref.Rdash.class}
\keyword{debugging}{srcfile}
\keyword{utilities}{srcfile}
\begin{Description}\relax
These functions are for working with source files.
\end{Description}
\begin{Usage}
\begin{verbatim}
srcfile(filename, encoding = getOption("encoding"))
srcfilecopy(filename, lines)
getSrcLines(srcfile, first, last)
srcref(srcfile, lloc)
## S3 method for class 'srcfile':
print(x, ...)
## S3 method for class 'srcfile':
open(con, line, ...)
## S3 method for class 'srcfile':
close(con, ...)
## S3 method for class 'srcref':
print(x, useSource = TRUE, ...)
## S3 method for class 'srcref':
as.character(x, useSource = TRUE, ...)
.isOpen(srcfile)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{filename}] The name of a file 
\item[\code{encoding}] The character encoding to assume for the file 
\item[\code{lines}] A character vector of source lines.  Other \R{} objects will be coerced
to character. 
\item[\code{srcfile}] A \code{srcfile} object 
\item[\code{first, last, line}] Line numbers 
\item[\code{lloc}] A vector of four values giving a source location; see Details 
\item[\code{x, con}] An object of the appropriate type 
\item[\code{useSource}] Whether to read the \code{srcfile} to obtain the text of a \code{srcref} 
\item[\code{...}] Additional arguments to the methods; these will be ignored 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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{\LinkA{file}{file}} for a discussion of encodings, and
\code{\LinkA{iconvlist}{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\_column, last\_line, last\_column)}.

Methods are defined for \code{print}, \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} 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.

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

\code{.isOpen} is intended for internal use:  it checks whether the 
connection associated with a \code{srcfile} object is open.
\end{Details}
\begin{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.
\end{Value}
\begin{Author}\relax
Duncan Murdoch
\end{Author}
\begin{Examples}
\begin{ExampleCode}
src <- srcfile(system.file("DESCRIPTION", package = "base"))
getSrcLines(src, 1, 4)
ref <- srcref(src, c(1, 1, 2, 1000))
ref
print(ref, useSource = FALSE)
\end{ExampleCode}
\end{Examples}

