1% File src/library/utils/man/findLineNum.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 2009-2014 Duncan Murdoch and the R Core Team
4% Distributed under GPL 2 or later
5
6\name{findLineNum}
7\alias{findLineNum}
8\alias{setBreakpoint}
9\title{
10  Find the Location of a Line of Source Code, or Set a Breakpoint There
11}
12\description{
13  These functions locate objects containing particular lines of source
14  code, using the information saved when the code was parsed with
15  \code{keep.source = TRUE}.
16}
17\usage{
18findLineNum(srcfile, line, nameonly = TRUE,
19            envir = parent.frame(), lastenv)
20
21setBreakpoint(srcfile, line, nameonly = TRUE,
22              envir = parent.frame(), lastenv, verbose = TRUE,
23              tracer, print = FALSE, clear = FALSE, ...)
24}
25\arguments{
26  \item{srcfile}{The name of the file containing the source code.}
27  \item{line}{The line number within the file.  See Details for an
28    alternate way to specify this.}
29  \item{nameonly}{If \code{TRUE} (the default), we require only a match
30    to \code{basename(srcfile)}, not to the full path.}
31  \item{envir}{Where do we start looking for function objects?}
32  \item{lastenv}{Where do we stop?  See the Details.}
33  \item{verbose}{Should we print information on where breakpoints were set?}
34  \item{tracer}{An optional \code{tracer} function to pass to
35    \code{\link{trace}}.  By default, a call to \code{\link{browser}}
36    is inserted.}
37  \item{print}{The \code{print} argument to pass to \code{\link{trace}}.}
38  \item{clear}{If \code{TRUE}, call \code{\link{untrace}} rather than
39    \code{\link{trace}}.}
40  \item{\dots}{Additional arguments to pass to \code{\link{trace}}.}
41}
42
43\details{
44  The \code{findLineNum} function searches through all objects in
45  environment \code{envir}, its parent, grandparent, etc., all the way
46  back to \code{lastenv}.
47
48  \code{lastenv} defaults to the global environment if
49  \code{envir} is not specified, and to the
50  root environment \code{\link{emptyenv}()} if \code{envir} is
51  specified.  (The first default tends to be quite fast, and will
52  usually find all user code other than S4 methods; the second one is
53  quite slow, as it will typically search all attached system
54  libraries.)
55
56  For convenience, \code{envir} may be specified indirectly:  if it is
57  not an environment, it will be replaced with
58  \code{environment(envir)}.
59
60  \code{setBreakpoint} is a simple wrapper function for
61  \code{\link{trace}} and \code{\link{untrace}}.  It will set or clear
62  breakpoints at the locations found by \code{findLineNum}.
63
64  The \code{srcfile} is normally a filename entered as a character
65  string, but it may be a \code{"\link{srcfile}"} object, or it may
66  include a suffix like \code{"filename.R#nn"}, in which case the number
67  \code{nn} will be used as a default value for \code{line}.
68
69  As described in the description of the \code{where} argument on the
70  man page for \code{\link{trace}}, the \R package system uses a
71  complicated scheme that may include more than one copy of a function
72  in a package.  The user will typically see the public one on the
73  search path, while code in the package will see a private one in the
74  package namespace.  If you set \code{envir} to the environment of a
75  function in the package, by default \code{findLineNum} will find both
76  versions, and \code{setBreakpoint} will set the breakpoint in both.
77  (This can be controlled using \code{lastenv}; e.g.,
78  \code{envir = environment(foo)}, \code{lastenv = globalenv()}
79  will find only the private copy, as the search is stopped before
80  seeing the public copy.)
81
82  S version 4 methods are also somewhat tricky to find.  They are stored
83  with the generic function, which may be in the \pkg{base} or other
84  package, so it is usually necessary to have \code{lastenv = emptyenv()}
85  in order to find them.  In some cases transformations are done by \R
86  when storing them and \code{findLineNum} may not be able to find the
87  original code.  Many special cases, e.g.\sspace{}methods on primitive
88  generics, are not yet supported.
89}
90\value{
91  \code{findLineNum} returns a list of objects containing location
92  information.  A \code{print} method is defined for them.
93
94  \code{setBreakpoint} has no useful return value; it is called for the
95  side effect of calling \code{\link{trace}} or \code{\link{untrace}}.
96}
97\author{
98  Duncan Murdoch
99}
100\seealso{
101  \code{\link{trace}}
102}
103\examples{
104\dontrun{
105# Find what function was defined in the file mysource.R at line 100:
106findLineNum("mysource.R#100")
107
108# Set a breakpoint in both copies of that function, assuming one is in the
109# same namespace as myfunction and the other is on the search path
110setBreakpoint("mysource.R#100", envir = myfunction)
111}
112}
113\keyword{ debugging }
114