[ RDocumentation ](/)

Moon  [ ](https://github.com/datacamp/rdocumentation-2.0) [ Learn R
](https://www.datacamp.com/learn/r)

Search all packages and functions

[ base  (version  3.6.2  ) ](/packages/base/versions/3.6.2)

#  substitute: 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 ](/link/call?package=base&version=3.6.2) ` from early
evaluation.

##  Usage

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

##  Arguments

expr

any syntactically valid  R  expression

cl

a ` [ call ](/link/call?package=base&version=3.6.2) ` , i.e., an  R  object of
` [ class ](/link/class?package=base&version=3.6.2) ` (and ` [ mode
](/link/mode?package=base&version=3.6.2) ` ) ` "call" ` .

env

an environment or a list object. Defaults to the current evaluation
environment.

##  Value

The ` [ mode ](/link/mode?package=base&version=3.6.2) ` 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.

##  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
](/link/deparse?package=base&version=3.6.2) ` 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 ](/link/delayedAssign?package=base&version=3.6.2) () `
, the expression slot of the promise replaces the symbol. If it is an ordinary
variable, its value is substituted, unless ` env ` is ` [ .GlobalEnv
](/link/.GlobalEnv?package=base&version=3.6.2) ` in which case the symbol is
left unchanged.

Both ` quote ` and ` substitute ` are ‘special’ [ primitive
](/link/primitive?package=base&version=3.6.2) functions which do not evaluate
their arguments.

##  References

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

##  See Also

` [ missing ](/link/missing?package=base&version=3.6.2) ` for argument
‘missingness’, ` [ bquote ](/link/bquote?package=base&version=3.6.2) ` for
partial substitution, ` [ sQuote ](/link/sQuote?package=base&version=3.6.2) `
and ` [ dQuote ](/link/dQuote?package=base&version=3.6.2) ` for adding
quotation marks to strings,

` [ all.names ](/link/all.names?package=base&version=3.6.2) ` to retrieve the
symbol names from an expression or call.

##  Examples

[ Run this code
](https://app.datacamp.com/workspace/preview?_tag=rdocs&rdocsPath=packages%2Fbase%2Fversions%2F3.6.2%2Ftopics%2Fsubstitute&utm_source=r-docs&utm_medium=docs&utm_term=substitute&utm_content=run_example_in_workspace)

    
    
    # NOT RUN {
    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 a