substitute               package:base               R Documentation

Substituting and Quoting Expressions

Description:

     'substitute' returns the parse tree for the (unevaluated)
     expression 'expr', substituting any variables bound in 'env'.

     'quote' simply returns its argument. The argument is not evaluated
     and can be any R expression.

Usage:

     substitute(expr, env)
     quote(expr)

Arguments:

    expr: Any syntactically valid R expression

     env: An environment or a list object.  Defaults to the current
          evaluation environment.

Details:

     The typical use of 'substitute' is to create informative labels
     for data sets and plots. The 'myplot' example below shows a simple
     use of this facility. It uses the functions 'deparse' and
     'substitute' to create labels for a plot which are character
     string versions of the actual arguments to the function 'myplot'.

     Substitution takes place by examining each component of the parse
     tree as follows: If it is not a bound symbol in 'env', it is
     unchanged. If it is a promise object, i.e., a formal argument to a
     function or explicitly created using 'delayedAssign()', the
     expression slot of the promise replaces the symbol. If it is an
     ordinary variable, its value is substituted, unless 'env' is
     '.GlobalEnv' in which case the symbol is left unchanged.

     'substitute' is a primitive function so positional matching is
     used and names of supplied arguments are ignored.

Value:

     The 'mode' of the result is generally '"call"' but may in
     principle be any type. In particular, single-variable expressions
     have mode '"name"' and constants have the appropriate base mode.

Note:

     Substitute works on a purely lexical basis. There is no guarantee
     that the resulting expression makes any sense.

     Substituting and quoting often causes confusion when the argument
     is 'expression(...)'. The result is a call to the 'expression'
     constructor function and needs to be evaluated with 'eval' to give
     the actual expression object.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'missing' for argument 'missingness', 'bquote' for partial
     substitution, 'sQuote' and 'dQuote' for adding quotation marks to
     strings.

Examples:

     require(graphics)
     (s.e <- substitute(expression(a + b), list(a = 1)))  #> expression(1 + b)
     (s.s <- substitute( a + b,            list(a = 1)))  #> 1 + b
     c(mode(s.e), typeof(s.e)) #  "call", "language"
     c(mode(s.s), typeof(s.s)) #   (the same)
     # but:
     (e.s.e <- eval(s.e))          #>  expression(1 + b)
     c(mode(e.s.e), typeof(e.s.e)) #  "expression", "expression"

     substitute(x <- x + 1, list(x=1)) # nonsense

     myplot <- function(x, y)
         plot(x, y, xlab=deparse(substitute(x)),
              ylab=deparse(substitute(y)))

     ## Simple examples about lazy evaluation, etc:

     f1 <- function(x, y = x)             { x <- x + 1; y }
     s1 <- function(x, y = substitute(x)) { x <- x + 1; y }
     s2 <- function(x, y) { if(missing(y)) y <- substitute(x); x <- x + 1; y }
     a <- 10
     f1(a)# 11
     s1(a)# 11
     s2(a)# a
     typeof(s2(a))# "symbol"

