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