R: References to source files

srcfile {base} | R Documentation

## References to source files

### Description

These functions are for working with source files.

### Usage

    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)

### Arguments

`filename` | The name of a file
`encoding` | The character encoding to assume for the file
`lines` | A character vector of source lines. Other R objects will be coerced to character.
`srcfile` | A `srcfile` object.
`first, last, line` | Line numbers.
`lloc` | A vector of four values giving a source location; see ‘Details’.
`x, con` | An object of the appropriate type.
`useSource` | Whether to read the `srcfile` to obtain the text of a `srcref`.
`...` | Additional arguments to the methods; these will be ignored.

### Details

These functions and classes handle source code references.

The `srcfile` function produces an object of class `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 `file` for a discussion of encodings, and `iconvlist` for a list of allowable encodings on your platform.

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

The `getSrcLines` function reads the specified lines from `srcfile`.

The `srcref` function produces an object of class `srcref`, which describes a range of characters in a `srcfile`. The `lloc` value gives the following values: `c(first_line, first_column, last_line, last_column)`.

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

Methods are defined for `print` and `as.character` for class `srcref`. The `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 `<srcref: "file" chars 1:1 to 2:10>` will be returned instead, indicating the `line:column` ranges of the first and last character.

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

`.isOpen` is intended for internal use: it checks whether the connection associated with a `srcfile` object is open.

### Value

`srcfile` returns a `srcfile` object.
`srcfilecopy` returns a `srcfilecopy` object.
`getSrcLines` returns a character vector of source code lines.
`srcref` returns a `srcref` object.

### Author(s)

Duncan Murdoch

### Examples

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

[Package base version 2.8.1 Index]