\HeaderA{delay}{Delay Evaluation}{delay}
\keyword{programming}{delay}
\keyword{data}{delay}
\begin{Description}\relax
\code{delay} creates a \emph{promise} to evaluate the given
expression in the specified environment if its value is requested.
This provides direct access to \emph{lazy evaluation} mechanism
used by \R{} for the evaluation of (interpreted) functions.
\end{Description}
\begin{Usage}
\begin{verbatim}
delay(x, env = .GlobalEnv)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] an expression.
\item[\code{env}] an evaluation environment
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If promises are kept inside an \code{\LinkA{environment}{environment}} or
\code{\LinkA{list}{list}}, they can be accessed in several ways without
evaluation, see the examples below.

When a promise is eventually forced, it is evaluated within the
environment specified by \code{env} (who contents may have changed in
the meantime).
\end{Details}
\begin{Value}
A \emph{promise} to evaluate the expression.  The value which is
returned by \code{delay} can be assigned without forcing its
evaluation, but any further accesses will cause evaluation.
\end{Value}
\begin{Examples}
\begin{ExampleCode}
x <- delay({
    for(i in 1:7)
        cat("yippee!\n")
    10
})

x^2 #- yippee
x^2 #- simple number

e <- (function(x, y = 1, z) environment())(1+2, "y", {cat(" HO! "); pi+2})
(le <- as.list(e)) # a list with three promise components
utils::str(le)     # even shows what's promised

le$z # prints; does not eval
ez <- le$z
ez-2 # "HO!", pi
ez # 5.14
le$z # still promise
\end{ExampleCode}
\end{Examples}

