1% File src/library/utils/man/getParseData.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 2012-2015 R Core Team
4% Distributed under GPL 2 or later
5
6\name{getParseData}
7\alias{getParseData}
8\alias{getParseText}
9\title{Get Detailed Parse Information from Object}
10\description{
11  If the \code{"keep.source"} option is \code{TRUE}, \R's parser
12  will attach detailed information on the object it has parsed.  These
13  functions retrieve that information.
14}
15\usage{
16getParseData(x, includeText = NA)
17getParseText(parseData, id)
18}
19\arguments{
20  \item{x}{
21    an expression returned from \code{\link{parse}}, or a function or other
22    object with source reference information
23  }
24  \item{includeText}{
25    logical; whether to include the text of parsed items in the result
26  }
27  \item{parseData}{
28    a data frame returned from \code{getParseData}
29  }
30  \item{id}{
31    a vector of item identifiers whose text is to be retrieved
32  }
33}
34\details{
35  In version 3.0.0, the \R{} parser was modified to include code written
36  by Romain Francois in his \pkg{parser} package.  This constructs a
37  detailed table of information about every token and higher level
38  construct in parsed code.  This table is stored in the
39  \code{\link{srcfile}} record associated with source references in the
40  parsed code, and retrieved by the \code{getParseData} function.
41}
42\value{
43  For \code{getParseData}:\cr
44  If parse data is not present, \code{NULL}.  Otherwise
45  a data frame is returned, containing the following columns:
46  \item{line1}{integer. The line number where the item starts.  This is the
47    parsed line number called \code{"parse"} in \code{\link{getSrcLocation}},
48    which ignores \verb{#line} directives.}
49  \item{col1}{integer. The column number where the item starts.  The first character
50    is column 1.  This corresponds to \code{"column"} in \code{\link{getSrcLocation}}.}
51  \item{line2}{integer. The line number where the item ends.}
52  \item{col2}{integer. The column number where the item ends.}
53  \item{id}{integer. An identifier associated with this item.}
54  \item{parent}{integer. The \code{id} of the parent of this item.}
55  \item{token}{character string. The type of the token.}
56  \item{terminal}{logical.  Whether the token is \dQuote{terminal}, i.e.
57    a leaf in the parse tree.}
58  \item{text}{character string. If \code{includeText} is \code{TRUE}, the
59    text of all tokens; if it is \code{NA} (the default), the text of terminal
60    tokens.  If \code{includeText == FALSE}, this column is not included.
61    Very long strings (with source of 1000 characters or more) will not be stored;
62    a message giving their length and delimiter will be included instead.}
63
64  The rownames of the data frame will be equal to the \code{id} values,
65  and the data frame will have a \code{"srcfile"} attribute containing
66  the \code{\link{srcfile}} record which was used.  The rows will be
67  ordered by starting position within the source file, with parent items
68  occurring before their children.
69
70  For \code{getParseText}:\cr
71  A character vector of the same length as \code{id} containing the associated
72  text items.  If they are not included in \code{parseData}, they will be
73  retrieved from the original file.
74}
75\references{
76  Romain Francois (2012). parser: Detailed R source code parser. R
77  package version 0.0-16. \url{https://github.com/halpo/parser}.
78}
79\author{
80Duncan Murdoch
81}
82\note{
83  There are a number of differences in the results returned by
84  \code{getParseData} relative to those in the original \pkg{parser}
85  code:
86  \itemize{
87    \item Fewer columns are kept.
88    \item The internal token number is not returned.
89    \item \code{col1} starts counting at 1, not 0.
90    \item The \code{id} values are not attached to the elements of the parse
91    tree, they are only retained in the table returned by \code{getParseData}.
92    \item \verb{#line} directives are identified, but other comment
93    markup (e.g., \CRANpkg{roxygen} comments) are not.
94  }
95}
96
97\seealso{
98\code{\link{parse}}, \code{\link{srcref}}
99}
100\examples{
101fn <- function(x) {
102  x + 1 # A comment, kept as part of the source
103}
104
105d <- getParseData(fn)
106if (!is.null(d)) {
107  plus <- which(d$token == "'+'")
108  sum <- d$parent[plus]
109  print(d[as.character(sum),])
110  print(getParseText(d, sum))
111}
112}
113\keyword{  utilities  }
114