| 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 |
|
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.
Quotes about forward, back, and double quotes ‘'’,
‘`’, and ‘"’.
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 = deparse1(substitute(x)),
ylab = deparse1(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"