parse
Parse Expressions
parse
returns the parsed but unevaluated expressions in a
list.
- Keywords
- file, programming, connection
Usage
parse(file = "", n = NULL, text = NULL, prompt = "?",
keep.source = getOption("keep.source"), srcfile,
encoding = "unknown")
Arguments
- file
- a connection, or a character string giving the name of a
file or a URL to read the expressions from.
If
file
is""
andtext
is missing orNULL
then input is taken from the console. - n
- integer (or coerced to integer). The maximum number of
expressions to parse. If
n
isNULL
or negative orNA
the input is parsed in its entirety. - 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.
NULL
means to use R's prompt,getOption("prompt")
. - keep.source
- a logical value; if
TRUE
, keep source reference information. - srcfile
NULL
, a character vector, or asrcfile
object. See the ‘Details’ section.- encoding
- encoding to be assumed for input strings. If the
value is
"latin1"
or"UTF-8"
it is used to mark character strings as known to be in Latin-1 or UTF-8: it is not used to re-encode the input. To do the latter, specify the encoding as part of the connectioncon
or viaoptions(encoding=)
: see the example underfile
.
Details
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.
Value
An object of type "expression"
, with up to n
elements if specified as a non-negative integer. 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.
Partial parsing
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.
References
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Murdoch, D. (2010). https://journal.r-project.org/archive/2010-2/RJournal_2010-2_Murdoch.pdf. The R Journal 2/2, 16-19.
See Also
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
.
Examples
library(base)
cat("x <- c(1, 4)\n x ^ 3 -10 ; outer(1:7, 5:9)\n", file = "xyz.Rdmped")
# parse 3 statements from the file "xyz.Rdmped"
parse(file = "xyz.Rdmped", n = 3)
unlink("xyz.Rdmped")
# A partial parse with a syntax error
txt <- "
x <- 1
an error
"
sf <- srcfile("txt")
try(parse(text = txt, srcfile = sf))
getParseData(sf)