| parse | R Documentation |
parse() returns the parsed but unevaluated expressions in an
expression, a “list” of calls.
str2expression(s) and str2lang(s) return special versions
of parse(text=s, keep.source=FALSE) and can therefore be regarded as
transforming character strings s to expressions, calls, etc.
parse(file = "", n = NULL, text = NULL, prompt = "?",
keep.source = getOption("keep.source"), srcfile,
encoding = "unknown")
str2lang(s)
str2expression(text)
file |
a connection, or a character string giving the name of a
file or a URL to read the expressions from.
If |
n |
integer (or coerced to integer). The maximum number of
expressions to parse. If |
text |
character vector. The text to parse. Elements are treated as if they were lines of a file. Other R objects will be coerced to character if possible. |
prompt |
the prompt to print when parsing from the keyboard.
|
keep.source |
a logical value; if |
srcfile |
|
encoding |
encoding to be assumed for input strings. If the
value is |
s |
a |
parse(....): If text has length greater than zero (after coercion) it is used in
preference to file.
All versions of R accept input from a connection with end of line marked by LF (as used on Unix), CRLF (as used on DOS/Windows) or CR (as used on classic Mac OS). The final line can be incomplete, that is missing the final EOL marker.
When input is taken from the console, n = NULL is equivalent to
n = 1, and n < 0 will read until an EOF character is
read. (The EOF character is Ctrl-Z for the Windows front-ends.) The
line-length limit is 4095 bytes when reading from the console (which
may impose a lower limit: see ‘An Introduction to R’).
The default for srcfile is set as follows. If
keep.source is not TRUE, srcfile
defaults to a character string, either "<text>" or one
derived from file. When keep.source is
TRUE, if text is used, srcfile will be set to a
srcfilecopy containing the text. If a character
string is used for file, a srcfile object
referring to that file will be used.
When srcfile is a character string, error messages will
include the name, but source reference information will not be added
to the result. When srcfile is a srcfile
object, source reference information will be retained.
str2expression(s): for a character vector
s, str2expression(s) corresponds to
parse(text = s, keep.source=FALSE), which is always of
type (typeof) and class expression.
str2lang(s): for a character string
s, str2lang(s) corresponds to
parse(text = s, keep.source=FALSE)[[1]] (plus a check
that both s and the parse(*) result are of length one)
which is typically a call but may also be a symbol aka
name, NULL or an atomic constant such as
2, 1L, or TRUE. Put differently, the value of
str2lang(.) is a call or one of its parts, in short
“a call or simpler”.
Currently, encoding is not handled in str2lang() and
str2expression().
parse() and str2expression() return an object of type
"expression", for parse() with up to n
elements if specified as a non-negative integer.
str2lang(s), s a string, returns “a
call or simpler”, see the ‘Details:’ section.
When srcfile is non-NULL, a "srcref" attribute
will be attached to the result containing a list of
srcref records corresponding to each element, a
"srcfile" attribute will be attached containing a copy of
srcfile, and a "wholeSrcref" attribute will be
attached containing a srcref record corresponding to
all of the parsed text. Detailed parse information will be stored in
the "srcfile" attribute, to be retrieved by
getParseData.
A syntax error (including an incomplete expression) will throw an error.
Character strings in the result will have a declared encoding if
encoding is "latin1" or "UTF-8", or if
text is supplied with every element of known encoding in a
Latin-1 or UTF-8 locale.
When a syntax error occurs during parsing, parse
signals an error. The partial parse data will be stored in the
srcfile argument if it is a srcfile object
and the text argument was used to supply the text. In other
cases it will be lost when the error is triggered.
The partial parse data can be retrieved using
getParseData applied to the srcfile object.
Because parsing was incomplete, it will typically include references
to "parent" entries that are not present.
Using parse(text = *, ..) or its simplified and hence more
efficient versions str2lang() or str2expression() is at
least an order of magnitude less efficient than call(..) or
as.call().
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
Murdoch, D. (2010). “Source References”. The R Journal, 2(2), 16–19. \Sexpr[results=rd,stage=build]{tools:::Rd_expr_doi("10.32614/RJ-2010-010")}.
scan, source, eval,
deparse.
The source reference information can be used for debugging (see
e.g. setBreakpoint) and profiling (see
Rprof). It can be examined by getSrcref
and related functions. More detailed information is available through
getParseData.
fil <- tempfile(fileext = ".Rdmped")
cat("x <- c(1, 4)\n x ^ 3 -10 ; outer(1:7, 5:9)\n", file = fil)
# parse 3 statements from our temp file
parse(file = fil, n = 3)
unlink(fil)
## str2lang(<string>) || str2expression(<character>) :
stopifnot(exprs = {
identical( str2lang("x[3] <- 1 4"), quote(x[3] <- 1 4))
identical( str2lang("log(y)"), quote(log(y)) )
identical( str2lang("abc" ), quote(abc) -> qa)
is.symbol(qa) & !is.call(qa) # a symbol/name, not a call
identical( str2lang("1.375" ), 1.375) # just a number, not a call
identical( str2expression(c("# a comment", "", "42")), expression(42) )
})
# A partial parse with a syntax error
txt <- "
x <- 1
an error
"
sf <- srcfile("txt")
try(parse(text = txt, srcfile = sf))
getParseData(sf)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.
