substitute {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.

`enquote` is a simple one-line utility which transforms a call of the form `Foo(....)` into the call `quote(Foo(....))`. This is typically used to protect a `call` from early evaluation.

### Usage

    substitute(expr, env)
    quote(expr)
    enquote(cl)

### Arguments

`expr` | any syntactically valid R expression
`cl` | a `call`, i.e., an R object of `class` (and `mode`) `"call"`.
`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.

Both `quote` and `substitute` are ‘special’ primitive functions which do not evaluate their arguments.

### 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 cause 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,

`all.names` to retrieve the symbol names from an expression or call.

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

[Package base version 3.4.2 Index]