EVOLUTION-MANAGER
Edit File: parse.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Parse R Expressions</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for parse {base}"><tr><td>parse {base}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Parse R Expressions</h2> <h3>Description</h3> <p><code>parse()</code> returns the parsed but unevaluated expressions in an <code><a href="expression.html">expression</a></code>, a “list” of <code><a href="call.html">call</a></code>s. </p> <p><code>str2expression(s)</code> and <code>str2lang(s)</code> return special versions of <code>parse(text=s, keep.source=FALSE)</code> and can therefore be regarded as transforming character strings <code>s</code> to expressions, calls, etc. </p> <h3>Usage</h3> <pre> parse(file = "", n = NULL, text = NULL, prompt = "?", keep.source = getOption("keep.source"), srcfile, encoding = "unknown") str2lang(s) str2expression(text) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>file</code></td> <td> <p>a <a href="connections.html">connection</a>, or a character string giving the name of a file or a URL to read the expressions from. If <code>file</code> is <code>""</code> and <code>text</code> is missing or <code>NULL</code> then input is taken from the console.</p> </td></tr> <tr valign="top"><td><code>n</code></td> <td> <p>integer (or coerced to integer). The maximum number of expressions to parse. If <code>n</code> is <code>NULL</code> or negative or <code>NA</code> the input is parsed in its entirety.</p> </td></tr> <tr valign="top"><td><code>text</code></td> <td> <p>character vector. The text to parse. Elements are treated as if they were lines of a file. Other <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> objects will be coerced to character if possible.</p> </td></tr> <tr valign="top"><td><code>prompt</code></td> <td> <p>the prompt to print when parsing from the keyboard. <code>NULL</code> means to use <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span>'s prompt, <code>getOption("prompt")</code>.</p> </td></tr> <tr valign="top"><td><code>keep.source</code></td> <td> <p>a logical value; if <code>TRUE</code>, keep source reference information.</p> </td></tr> <tr valign="top"><td><code>srcfile</code></td> <td> <p><code>NULL</code>, a character vector, or a <code><a href="srcfile.html">srcfile</a></code> object. See the ‘Details’ section.</p> </td></tr> <tr valign="top"><td><code>encoding</code></td> <td> <p>encoding to be assumed for input strings. If the value is <code>"latin1"</code> or <code>"UTF-8"</code> 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 <code>con</code> or <em>via</em> <code><a href="options.html">options</a>(encoding=)</code>: see the example under <code><a href="connections.html">file</a></code>.</p> </td></tr> <tr valign="top"><td><code>s</code></td> <td> <p>a <code><a href="character.html">character</a></code> vector of length <code>1</code>, i.e., a “string”.</p> </td></tr> </table> <h3>Details</h3> <dl> <dt><code>parse(....)</code>: </dt><dd> <p>If <code>text</code> has length greater than zero (after coercion) it is used in preference to <code>file</code>. </p> <p>All versions of <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> 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. </p> <p>When input is taken from the console, <code>n = NULL</code> is equivalent to <code>n = 1</code>, and <code>n < 0</code> 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’). </p> <p>The default for <code>srcfile</code> is set as follows. If <code>keep.source</code> is not <code>TRUE</code>, <code>srcfile</code> defaults to a character string, either <code>"<text>"</code> or one derived from <code>file</code>. When <code>keep.source</code> is <code>TRUE</code>, if <code>text</code> is used, <code>srcfile</code> will be set to a <code><a href="srcfile.html">srcfilecopy</a></code> containing the text. If a character string is used for <code>file</code>, a <code><a href="srcfile.html">srcfile</a></code> object referring to that file will be used. </p> <p>When <code>srcfile</code> is a character string, error messages will include the name, but source reference information will not be added to the result. When <code>srcfile</code> is a <code><a href="srcfile.html">srcfile</a></code> object, source reference information will be retained. </p> </dd> <dt><code>str2expression(s)</code>: </dt><dd><p>for a <code><a href="character.html">character</a></code> vector <code>s</code>, <code>str2expression(s)</code> corresponds to <code><a href="parse.html">parse</a>(text = s, keep.source=FALSE)</code>, which is always of type (<code><a href="typeof.html">typeof</a></code>) and <code><a href="class.html">class</a></code> <code>expression</code>. </p> </dd> <dt><code>str2lang(s)</code>: </dt><dd><p>for a <code><a href="character.html">character</a></code> string <code>s</code>, <code>str2lang(s)</code> corresponds to <code><a href="parse.html">parse</a>(text = s, keep.source=FALSE)[[1]]</code> (plus a check that both <code>s</code> and the <code>parse(*)</code> result are of length one) which is typically a <code>call</code> but may also be a <code>symbol</code> aka <code><a href="name.html">name</a></code>, <code><a href="NULL.html">NULL</a></code> or an atomic constant such as <code>2</code>, <code>1L</code>, or <code>TRUE</code>. Put differently, the value of <code>str2lang(.)</code> is a call or one of its parts, in short “a call or simpler”. </p> </dd> </dl> <p>Currently, encoding is not handled in <code>str2lang()</code> and <code>str2expression()</code>. </p> <h3>Value</h3> <p><code>parse()</code> and <code>str2expression()</code> return an object of type <code>"<a href="expression.html">expression</a>"</code>, for <code>parse()</code> with up to <code>n</code> elements if specified as a non-negative integer. </p> <p><code>str2lang(s)</code>, <code>s</code> a string, returns “a <code><a href="call.html">call</a></code> or simpler”, see the ‘Details:’ section. </p> <p>When <code>srcfile</code> is non-<code>NULL</code>, a <code>"srcref"</code> attribute will be attached to the result containing a list of <code><a href="srcfile.html">srcref</a></code> records corresponding to each element, a <code>"srcfile"</code> attribute will be attached containing a copy of <code>srcfile</code>, and a <code>"wholeSrcref"</code> attribute will be attached containing a <code><a href="srcfile.html">srcref</a></code> record corresponding to all of the parsed text. Detailed parse information will be stored in the <code>"srcfile"</code> attribute, to be retrieved by <code><a href="../../utils/html/getParseData.html">getParseData</a></code>. </p> <p>A syntax error (including an incomplete expression) will throw an error. </p> <p>Character strings in the result will have a declared encoding if <code>encoding</code> is <code>"latin1"</code> or <code>"UTF-8"</code>, or if <code>text</code> is supplied with every element of known encoding in a Latin-1 or UTF-8 locale. </p> <h3>Partial parsing</h3> <p>When a syntax error occurs during parsing, <code>parse</code> signals an error. The partial parse data will be stored in the <code>srcfile</code> argument if it is a <code><a href="srcfile.html">srcfile</a></code> object and the <code>text</code> argument was used to supply the text. In other cases it will be lost when the error is triggered. </p> <p>The partial parse data can be retrieved using <code><a href="../../utils/html/getParseData.html">getParseData</a></code> applied to the <code>srcfile</code> object. Because parsing was incomplete, it will typically include references to <code>"parent"</code> entries that are not present. </p> <h3>Note</h3> <p>Using <code>parse(text = *, ..)</code> or its simplified and hence more efficient versions <code>str2lang()</code> or <code>str2expression()</code> is at least an order of magnitude less efficient than <code><a href="call.html">call</a>(..)</code> or <code><a href="call.html">as.call</a>()</code>. </p> <h3>References</h3> <p>Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) <em>The New S Language</em>. Wadsworth & Brooks/Cole. </p> <p>Murdoch, D. (2010). <a href="https://journal.r-project.org/archive/2010-2/RJournal_2010-2_Murdoch.pdf">Source References</a>. <em>The R Journal</em> 2/2, 16-19. </p> <h3>See Also</h3> <p><code><a href="scan.html">scan</a></code>, <code><a href="source.html">source</a></code>, <code><a href="eval.html">eval</a></code>, <code><a href="deparse.html">deparse</a></code>. </p> <p>The source reference information can be used for debugging (see e.g. <code><a href="../../utils/html/findLineNum.html">setBreakpoint</a></code>) and profiling (see <code><a href="../../utils/html/Rprof.html">Rprof</a></code>). It can be examined by <code><a href="../../utils/html/sourceutils.html">getSrcref</a></code> and related functions. More detailed information is available through <code><a href="../../utils/html/getParseData.html">getParseData</a></code>. </p> <h3>Examples</h3> <pre> 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 }) # A partial parse with a syntax error txt <- " x <- 1 an error " sf <- srcfile("txt") try(parse(text = txt, srcfile = sf)) getParseData(sf) </pre> <hr /><div style="text-align: center;">[Package <em>base</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>