parse returns the parsed but unevaluated expressions in a
parse(file = "", n = NULL, text = NULL, prompt = "?", keep.source = getOption("keep.source"), srcfile, encoding = "unknown")
- a connection, or a character string giving the name of a
file or a URL to read the expressions from.
textis missing or
NULLthen input is taken from the console.
- integer (or coerced to integer). The maximum number of
expressions to parse. If
NULLor negative or
NAthe input is parsed in its entirety.
- 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.
- the prompt to print when parsing from the keyboard.
NULLmeans to use R's prompt,
- a logical value; if
TRUE, keep source reference information.
NULL, a character vector, or a
srcfileobject. See the Details section.
- encoding to be assumed for input strings. If the
"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 connection
options(encoding=): see the example under
text has length greater than zero (after coercion) it is used in
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
defaults to a character string, either
" or one
text is used,
srcfile will be set to a
srcfilecopy containing the text. If a character
string is used for
referring to that file will be used.
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
object, source reference information will be retained.
An object of type
"expression", with up to
nelements if specified as a non-negative integer.When
"srcref"attribute will be attached to the result containing a list of
srcrefrecords corresponding to each element, a
"srcfile"attribute will be attached containing a copy of
srcfile, and a
"wholeSrcref"attribute will be attached containing a
srcrefrecord 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
"UTF-8", or if
textis supplied with every element of known encoding in a Latin-1 or UTF-8 locale.
When a syntax error occurs during parsing,
signals an error. The partial parse data will be stored in the
srcfile argument if it is a
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
Because parsing was incomplete, it will typically include references
"parent" entries that are not present.
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.
The source reference information can be used for debugging (see e.g.
setBreakpoint) and profiling (see
Rprof). It can be examined by
and related functions. More detailed information is available through
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)