\Header{substitute}{Substituting and quoting expressions}
\alias{quote}{substitute}
\keyword{programming}{substitute}
\keyword{data}{substitute}
\begin{Usage}
\begin{verbatim}
substitute(expr, env=<see below>)
quote(expr)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{expr}] Any syntactically valid R expression
\item[\texttt{env}] An environment or a list object. Defaults to the
current evaluation environment.
\end{ldescription}
\end{Arguments}
\begin{Description}
\texttt{substitute} returns the parse tree for the (unevaluated)
expression \texttt{expr}, substituting any variables bound in
\texttt{env}. \\{} 
\texttt{quote} simply returns the parse tree for the expression.\end{Description}
\begin{Details}
The typical use of \texttt{substitute} is to create informative labels
for data sets and plots.
The \texttt{myplot} example below shows a simple use of this facility.
It uses the functions \texttt{\Link{deparse}} and \texttt{substitute}
to create labels for a plot which are character string versions
of the actual arguments to the function \texttt{myplot}.

Substition takes place by examining each component of the parse tree
as follows: If it is not a bound symbol in \texttt{env}, it is
unchanged. If it is a promise object, i.e. a formal argument to a 
function or explicitly created using \texttt{delay()}, the expression
slot of the promise replaces the symbol. If it is an ordinary
variable, its value is substituted, unless \texttt{env} is
\texttt{.GlobalEnv} in which case the symbol is left unchanged.\end{Details}
\begin{Value}
The \texttt{\Link{mode}} of the result is generally \texttt{"call"} but
may in principle be any type. In particular, single-variable
expressions have mode \texttt{"name"} and constants have the
appropriate base mode.\end{Value}
\begin{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
\texttt{expression(...)}. The result is a call to the
\texttt{\Link{expression}} constructor function and needs to be evaluated
with \texttt{\Link{eval}} to give the actual expression object.\end{Note}
\begin{SeeAlso}
\texttt{\Link{missing}} for argument ``missingness''.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
(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"
\end{ExampleCode}
\end{Examples}

