Parse Expressions

DESCRIPTION:

Returns an object of mode "expression" that is the parsed version of the input.

USAGE:

parse(file="", n=NULL, prompt=NULL, text=NULL, mode="Splus")
set.parse.mode(mode)

OPTIONAL ARGUMENTS:

file
the file or S-PLUS connection object from which input to the parser should be read. If neither text nor file is provided, or if file is the empty string, the parser reads from standard input.
n
number of expressions to parse. If negative, parsing will continue to the end of the file. By default, parse reads to the end of the file or text, except when the file is the standard input, in which case n=1.
text
character vector to use as input to the parser.
prompt
character string to use as the prompt in interactive use of parse. The default is the value of the option named prompt.
mode
Should be either "Splus" or 0 to to parse in Splus mode or "R" or 1 to parse in R mode. The default mode is 0 (Splus mode) unless the environment variable "S_PARSE_MODE" had been set. You may change that default by calling set.parse.mode. To see the current parse mode without changing it, enter set.parse.mode(mode=-1).

NOTE:

The parse function also includes arguments white and keep.text that were used in previous versions of the function but are now ignored.

VALUE:

parse returns an object of mode expression , containing the parsed version of the expression(s) read.

set.parse.mode returns an integer value. If called with mode=-1, then that value is the current mode, either '0' for Splus mode or '1'for R mode. If set.parse.mode is called to change the parse mode ( mode=0|"Splus"|1|"R") then the return value is the previous mode.

DETAILS:

Usually, parse() prompts for input when the input is coming from the standard input stream and the standard input and standard error streams appear to be terminals. ( Options("prompt") and options("continue") give the prompt strings.) If you desire the prompting even when those streams are pipes or files, set the environmental variable ALWAYS_PROMPT (to anything at all) before starting S-PLUS. parse() never prints prompts if its file argument is not null or if the text argument is given.

The standard .Program calls parse() with no arguments to get input from the user.

At startup the default parse mode is Splus mode, but S-PLUS can start up in R parse mode by setting the environment variable S_PARSE_MODE. For example, start up S-PLUS with parse mode set to R:

     Splus START S_PARSE_MODE=R

Also, the parse mode can be changed to R mode while running S-PLUS by calling set.parse.mode("R") . Calling set.parse.mode(-1) returns the current parse mode without changing the mode.

Parsing differences between "Splus" and "R" mode:
- In R mode a sequence of digits without a decimal point is parsed as "numeric" (double precsion) but parsed as "integer" in Splus mode.
- In R mode object names may include underscores, whereas in Splus mode an underscore means assignment.
- In R mode, R-style calls to .Internal will generate an warning instead of an error.

Parsing R's .Internal function:

R's version of .Internal does not include the name of the C function to call as its second argument, but instead the function name is stored in a table. So when parsing R code containing calls to .Internal an error will be generated due to the missing argument. But when parsing in "R" mode, a warning is generated so that parsing will continue instead of stopping when a call to .Internal is found. The parser puts a message into the second argument as a reminder that the function name is missing.

     > pmode <- set.parse.mode("R")
     > func <- function(x) .Internal(func(x))
     Warning messages:
       Second argument (the name of the C routine) missing in .Internal for
             func(x).  Splus, unlike R, requires it
     > func
     function(x)
     .Internal(func(x), "Unspecified .Internal entry point")

SEE ALSO:

, , , .

EXAMPLES:

parse(n=-1, file="my.file") # parse everything on my.file
# Example function that uses parse to input a value interactively:
convertFahrenheit <- function(){
  x <- parse(n = 1,
             prompt = "Input a temperature (in Fahrenheit):  ")[[1]]
  paste("The temperature in Celsius is", (x-32)*100/180)
}

# Show differences between R and Splus mode
set.parse.mode(mode="R")
parse(n=2, text="x_1<-10; class(x_1)")
# Returns: expression("x_1" <- 10., class(`x_1`))
eval(parse(n=2, text="x_1<-10; class(x_1)"))
# Returns: "numeric"
set.parse.mode(mode="Splus")
parse(n=2, text="x_1<-10; class(x_1)")
# Returns: expression(x <- 1 <- 10, class(x <- 1))