| Title: | Parse Data of 'R' Code as an 'XML' Tree |
|---|---|
| Description: | Convert the output of 'utils::getParseData()' to an 'XML' tree, that one can search via 'XPath', and easier to manipulate in general. |
| Authors: | Gábor Csárdi [aut, cre], Posit Software, PBC [cph, fnd], Mango Solutions [cph, fnd] |
| Maintainer: | Gábor Csárdi <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.5.9000 |
| Built: | 2024-06-12 04:01:27 UTC |
| Source: | https://github.com/r-lib/xmlparsedata |
Get an XML representation of an expression
expr_as_xml(expr)expr_as_xml(expr)
expr |
An expression. |
In recent R versions the parser can attach source code location
information to the parsed expressions. This information is often
useful for static analysis, e.g. code linting. It can be accessed
via the utils::getParseData() function.
xml_parse_data(x, includeText = NA, pretty = FALSE)xml_parse_data(x, includeText = NA, pretty = FALSE)
x |
an expression returned from |
includeText |
logical; whether to include the text of parsed items in the result |
pretty |
Whether to pretty-indent the XML output. It has a small overhead which probably only matters for very large source files. |
xml_parse_data() converts this information to an XML tree.
The R parser's token names are preserved in the XML as much as
possible, but some of them are not valid XML tag names, so they are
renamed, see the xml_parse_token_map vector for the
mapping.
The top XML tag is <exprlist>, which is a list of
expressions, each expression is an <expr> tag. Each tag
has attributes that define the location: line1, col1,
line2, col2. These are from the getParseData()
data frame column names. Next, there are two attributes,
start and end, which can be used as an ordering of
expressions in the document. Note that while the values
are correlated with (and in some cases may match exactly)
positions in the document, this cannot be relied upon.
See an example below. See also the README at
https://github.com/r-lib/xmlparsedata#readme
for examples on how to search the XML tree with the xml2 package
and XPath expressions.
Note that xml_parse_data() silently drops all control characters
(0x01-0x1f) from the input, except horizontal tab (0x09) and newline
(0x0a), because they are invalid in XML 1.0.
An XML string representing the parse data. See details below.
xml_parse_token_map for the token names. https://github.com/r-lib/xmlparsedata#readme for more information and use cases.
code <- "function(a = 1, b = 2) {\n a + b\n}\n" expr <- parse(text = code, keep.source = TRUE) # The base R way: getParseData(expr) cat(xml_parse_data(expr, pretty = TRUE))code <- "function(a = 1, b = 2) {\n a + b\n}\n" expr <- parse(text = code, keep.source = TRUE) # The base R way: getParseData(expr) cat(xml_parse_data(expr, pretty = TRUE))
xml_parse_data()
Some of the R token names are not valid XML tag names,
so xml_parse_data() needs to replace them to create a
valid XML file.
xml_parse_token_mapxml_parse_token_map
An object of class character of length 20.
Convert the output of 'utils::getParseData()' to an 'XML' tree, that is searchable and easier to manipulate in general.