1% File src/library/utils/man/sourceutils.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 2011-2013 R Core Team
4% Distributed under GPL 2 or later
5
6\name{sourceutils}
7\alias{getSrcFilename}
8\alias{getSrcDirectory}
9\alias{getSrcref}
10\alias{getSrcLocation}
11\title{
12  Source Reference Utilities
13}
14\description{
15  These functions extract information from source references.
16}
17\usage{
18getSrcFilename(x, full.names = FALSE, unique = TRUE)
19getSrcDirectory(x, unique = TRUE)
20getSrcref(x)
21getSrcLocation(x, which = c("line", "column", "byte", "parse"),
22               first = TRUE)
23}
24\arguments{
25  \item{x}{
26    An object (typically a function) containing source references.
27  }
28  \item{full.names}{
29    Whether to include the full path in the filename result.
30  }
31  \item{unique}{
32    Whether to list only unique filenames/directories.
33  }
34  \item{which}{
35    Which part of a source reference to extract.  Can be abbreviated.
36  }
37  \item{first}{
38    Whether to show the first (or last) location of the object.
39  }
40}
41\details{
42  Each statement of a function will have its own source reference if the
43  \code{"keep.source"} option is \code{TRUE}.  These functions retrieve
44  all of them.
45
46  The components are as follows:
47  \describe{
48    \item{line}{The line number where the object starts or ends.}
49    \item{column}{The column number where the object starts or ends.}
50    \item{byte}{As for \code{"column"}, but counting bytes, which may
51      differ in case of multibyte characters.}
52    \item{parse}{As for \code{"line"}, but this ignores \code{#line} directives.}
53  }
54}
55\value{
56  \code{getSrcFilename} and \code{getSrcDirectory} return character vectors
57  holding the filename/directory.
58
59  \code{getSrcref} returns a list of \code{"srcref"} objects or
60  \code{NULL} if there are none.
61
62  \code{getSrcLocation} returns an integer vector of the requested type
63  of locations.
64}
65\seealso{
66\code{\link{srcref}}, \code{\link{getParseData}}
67}
68\examples{
69fn <- function(x) {
70  x + 1 # A comment, kept as part of the source
71}
72
73# Show the temporary file directory
74# where the example was saved
75
76getSrcDirectory(fn)
77getSrcLocation(fn, "line")
78}
79\keyword{ utilities }
80