The R Project SVN R

% File src/library/base/man/srcfile.Rd

% Part of the R package, https://www.R-project.org

% Copyright 1995-2024 R Core Team

% Distributed under GPL 2 or later

\name{srcfile}

\title{References to Source Files and Code}

\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}

\alias{srcfilealias-class}

\alias{srcfilealias}

\alias{open.srcfilealias}

\alias{close.srcfilealias}

\description{

  These functions are for working with source files and more generally

  with \dQuote{source references} (\code{"srcref"}), i.e., references to

  source code.  The resulting data is used for printing and source level

  debugging, and is typically available in interactive \R sessions,

  namely when \code{\link{options}(keep.source = TRUE)}.

}

\usage{

srcfile(filename, encoding = getOption("encoding"), Enc = "unknown")

srcfilecopy(filename, lines, timestamp = Sys.time(), isFile = FALSE)

srcfilealias(filename, srcfile)

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, to = x, \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{timestamp}{ The timestamp to use on a copy of a file. }

  \item{isFile}{ Is this \code{srcfilecopy} known to come from a file system file? }

  \item{srcfile}{ A \code{srcfile} object. }

  \item{first, last, line}{ Line numbers. }

  \item{lloc}{ A vector of four, six or eight 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{to}{ An optional second \code{srcref} object to mark the end

    of the character range. }

  \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.  It copies the value of the \code{isFile} argument, to help

  debuggers identify whether this text comes from a real file in the

  file system.

  The \code{srcfilealias} function produces an object of the descendant

  class \code{srcfilealias}, which gives an alternate name to another

  \code{srcfile}.  This is produced by the parser when a \code{#line} directive

  is used.

  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:

\preformatted{c(first_line, first_byte, last_line, last_byte, first_column,

  last_column, first_parsed, last_parsed)

}

  Bytes (elements 2, 4) and

  columns (elements 5, 6) may be different due to multibyte

  characters.  If only four values are given, the columns and bytes

  are assumed to match.  Lines (elements 1, 3) and parsed lines

  (elements 7, 8) may differ if a \code{#line} directive is used in

  code:  the former will respect the directive, the latter will just

  count lines.  If only 4 or 6 elements are given, the parsed lines

  will be assumed to match the lines.

  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{\link{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 the \code{to} argument is given,

  it should be a second \code{srcref} that follows the first, in the

  same file; they will be treated as one reference to the whole

  range.  The exact behaviour depends on the

  class of the source file.  If the source file inherits from

  class \code{srcfilecopy}, the lines are taken from the saved copy

  using the \dQuote{parsed} line counts.  If not, an attempt

  is made to read the file, and the original line numbers of the

  \code{srcref} record (i.e., elements 1 and 3) are used.  If an error

  occurs (e.g., the file no longer exists), text like

  \samp{<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 \samp{<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.

}

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

}

\seealso{

  \code{\link{getSrcFilename}} for extracting information from a source

  reference, or \code{\link{removeSource}} to remove it from a language

  object or a (non-primitive) function (aka \sQuote{closure}).

}

\author{Duncan Murdoch}

\examples{

src <- srcfile(system.file("DESCRIPTION", package = "base"))

\dontdiff{summary(src)}% timestamp

getSrcLines(src, 1, 4)

ref <- srcref(src, c(1, 1, 2, 1000))

ref

print(ref, useSource = FALSE)

}

\keyword{ debugging }

\keyword{ utilities }