substitute               package:base               R Documentation

_S_u_b_s_t_i_t_u_t_i_n_g _a_n_d _Q_u_o_t_i_n_g _E_x_p_r_e_s_s_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     '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.

_U_s_a_g_e:

     substitute(expr, env)
     quote(expr)

_A_r_g_u_m_e_n_t_s:

    expr: Any syntactically valid R expression

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

_D_e_t_a_i_l_s:

     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.

     'substitute' and 'quote' are both primitive functions so
     positional matching is used and names of supplied arguments are
     ignored.

_V_a_l_u_e:

     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.

_N_o_t_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.

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'missing' for argument 'missingness', 'bquote' for partial
     substitution, 'sQuote' and 'dQuote' for adding quotation marks to
     strings.

_E_x_a_m_p_l_e_s:

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