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=<<see below>>)
     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 `delay()', 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.

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.

See Also:

     `missing' for argument ``missingness''.

Examples:

     (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"

