R: Find the Location of a Line of Source Code, or Set a...

findLineNum {utils} | R Documentation

## Find the Location of a Line of Source Code, or Set a Breakpoint There.

### Description

These functions locate objects containing particular lines of source code, using the information saved when the code was parsed with `options(keep.source = TRUE)`.

### Usage

    findLineNum(srcfile, line, nameonly = TRUE,
                envir = parent.frame(), lastenv)

    setBreakpoint(srcfile, line, nameonly = TRUE,
                  envir = parent.frame(), lastenv, verbose = TRUE,
                  tracer, print = FALSE, clear = FALSE, ...)

### Arguments

`srcfile` | The name of the file containing the source code.
`line` | The line number within the file. See Details for an alternate way to specify this.
`nameonly` | If `TRUE` (the default), we require only a match to `basename(srcfile)`, not to the full path.
`envir` | Where do we start looking for function objects?
`lastenv` | Where do we stop? See the Details.
`verbose` | Should we print information on where breakpoints were set?
`tracer` | An optional `tracer` function to pass to `trace`. By default, a call to `browser` is inserted.
`print` | The `print` argument to pass to `trace`.
`clear` | If `TRUE`, call `untrace` rather than `trace`.
`...` | Additional arguments to pass to `trace`.

### Details

The `findLineNum` function searches through all objects in environment `envir`, it's parent, grandparent, etc., all the way back to `lastenv`.

`lastenv` defaults to the global environment if `envir` is not specified, and to the root environment `emptyenv()` if `envir` is specified. (The first default tends to be quite fast, and will usually find all user code other than S4 methods; the second one is quite slow, as it will typically search all attached system libraries.)

For convenience, `envir` may be specified indirectly: if it is not an environment, it will be replaced with `environment(envir)`.

`setBreakpoint` is a simple wrapper function for `trace` and `untrace`. It will set or clear breakpoints at the locations found by `findLineNum`.

The `srcfile` is normally a filename entered as a character string, but it may be a `"srcfile"` object, or it may include a suffix like `"filename.R#nn"`, in which case the number `nn` will be used as a default value for `line`.

As described in the description of the `where` argument on the man page for `trace`, the R package system uses a complicated scheme that may include more than one copy of a function in a package. The user will typically see the public one on the search path, while code in the package will see a private one in the package NAMESPACE. If you set `envir` to the environment of a function in the package, by default `findLineNum` will find both versions, and `setBreakpoint` will set the breakpoint in both. (This can be controlled using `lastenv`; e.g. `envir=environment(foo)`, `lastenv=globalenv()` will find only the private copy, as the search is stopped before seeing the public copy.)

S version 4 methods are also somewhat tricky to find. They are stored with the generic function, which may be in the base or other package, so it is usually necessary to have `lastenv=emptyenv()` in order to find them. In some cases transformations are done by R when storing them and `findLineNum` may not be able to find the original code. Many special cases, e.g. methods on primitive generics, are not yet supported.

### Value

`fineLineNum` returns a list of objects containing location information. A `print` method is defined for them.

`setBreakpoint` has no useful return value; it is called for the side effect of calling `trace` or `untrace`.

### Author(s)

Duncan Murdoch

### See Also

`trace`

### Examples

    ## Not run:
    # Find what function was defined in the file mysource.R at line 100:
    findLineNum("mysource.R#100")

    # Set a breakpoint in both copies of that function, assuming one is in the
    # same namespace as myfunction and the other is on the search path
    setBreakpoint("mysource.R#100", envir=myfunction)

    ## End(Not run)

[Package utils version 2.15.1 Index]