

   substitute {base}                            R Documentation

   SSuubbssttiittuuttiinngg aanndd QQuuoottiinngg EExxpprreessssiioonnss

   DDeessccrriippttiioonn::

        `substitute' returns the parse tree for the (unevalu-
        ated) expression `expr', substituting any variables
        bound in `env'.
        `quote' simply returns the parse tree for the expres-
        sion.

   UUssaaggee::

        substitute(expr, env=<<see below>>)
        quote(expr)

   AArrgguummeennttss::

       expr: Any syntactically valid R expression

        env: An environment or a list object. Defaults to the
             current evaluation environment.

   DDeettaaiillss::

        The typical use of `substitute' is to create informa-
        tive 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 cre-
        ated using `delay()', the expression slot of the
        promise replaces the symbol. If it is an ordinary vari-
        able, its value is substituted, unless `env' is `.Glob-
        alEnv' in which case the symbol is left unchanged.

   VVaalluuee::

        The `mode' of the result is generally `"call"' but may
        in principle be any type. In particular, single-vari-
        able expressions have mode `"name"' and constants have
        the appropriate base mode.

   NNoottee::

        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 `expression(...)'. The result is a call
        to the `expression' constructor function and needs to
        be evaluated with `eval' to give the actual expression
        object.

   SSeeee AAllssoo::

        `missing' for argument ``missingness''.

   EExxaammpplleess::

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

