eval                  package:base                  R Documentation

_E_v_a_l_u_a_t_e _a_n (_U_n_e_v_a_l_u_a_t_e_d) _E_x_p_r_e_s_s_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     Evaluate an R expression in a specified environment.

_U_s_a_g_e:

     eval(expr, envir = parent.frame(),
                enclos = if(is.list(envir) || is.pairlist(envir))
                            parent.frame() else baseenv())
     evalq(expr, envir, enclos)
     eval.parent(expr, n = 1)
     local(expr, envir = new.env())

_A_r_g_u_m_e_n_t_s:

    expr: an object to be evaluated.  See 'Details'.

   envir: the 'environment' in which 'expr' is to be evaluated.  May
          also be 'NULL', a list, a data frame, a pairlist or an
          integer as specified to 'sys.call'.

  enclos: Relevant when 'envir' is a (pair)list or a data frame.
          Specifies the enclosure, i.e., where R looks for objects not
          found in 'envir'.  This can be 'NULL' (interpreted as the
          base package environment) or an environment.

       n: number of parent generations to go back

_D_e_t_a_i_l_s:

     'eval' evaluates the 'expr' argument in the environment specified
     by 'envir' and returns the computed value. If 'envir' is not
     specified, then the default is 'parent.frame()' (the environment
     where the call to 'eval' was made).

     Objects to be evaluated can be of types 'call' or 'expression' or
     name (when the name is looked up in the current scope and its
     binding is evaluated), a promise or any of the basic types such as
     vectors, functions and environments (which are returned
     unchanged).

     The 'evalq' form is equivalent to 'eval(quote(expr), ...)'. 'eval'
     evaluates its first argument in the current scope before passing
     it to the evaluator: 'evalq' avoids this.

     'eval.parent(expr, n)' is a shorthand for 'eval(expr,
     parent.frame(n))'.

     If 'envir' is a list (such as a data frame) or pairlist, it is
     copied into a temporary environment (with enclosure 'enclos'), and
     the temporary environment is used for evaluation.  So if 'expr'
     changes any of the components named in the (pair)list, the changes
     are lost.

     If 'envir' is 'NULL' it is interpreted as an empty list so no
     values could be found in 'envir' and look-up goes directly to
     'enclos'.

     'local' evaluates an expression in a local environment.  It is
     equivalent to 'evalq' except that its default argument creates a
     new, empty environment.  This is useful to create anonymous
     recursive functions and as a kind of limited name space feature
     since variables defined in the environment are not visible from
     the outside.

_V_a_l_u_e:

     The result of evaluating the object: for an expression vector this
     it the result of evaluating the last elements.

_N_o_t_e:

     Due to the difference in scoping rules, there are some differences
     between R and S in this area.  In particular, the default
     enclosure in S is the global environment.

     When evaluating expressions in data frames that has been passed as
     argument to a function, the relevant enclosure is often the
     caller's environment, i.e., one needs 'eval(x, data,
     parent.frame())'.

_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. ('eval' only.)

_S_e_e _A_l_s_o:

     'expression', 'quote', 'sys.frame', 'parent.frame', 'environment'.

     Further, 'force' to _force_ evaluation, typically of function
     arguments.

_E_x_a_m_p_l_e_s:

     eval(2 ^ 2 ^ 3)
     mEx <- expression(2^2^3); mEx; 1 + eval(mEx)
     eval({ xx <- pi; xx^2}) ; xx

     a <- 3 ; aa <- 4 ; evalq(evalq(a+b+aa, list(a=1)), list(b=5)) # == 10
     a <- 3 ; aa <- 4 ; evalq(evalq(a+b+aa, -1), list(b=5))        # == 12

     ev <- function() {
        e1 <- parent.frame()
        ## Evaluate a in e1
        aa <- eval(expression(a),e1)
        ## evaluate the expression bound to a in e1
        a <- expression(x+y)
        list(aa = aa, eval = eval(a, e1))
     }
     tst.ev <- function(a = 7) { x <- pi; y <- 1; ev() }
     tst.ev()#-> aa : 7,  eval : 4.14

     a <- list(a=3, b=4)
     with(a, a <- 5) # alters the copy of a from the list, discarded.

     ##
     ## Example of evalq()
     ##

     N <- 3
     env <- new.env()
     assign("N", 27, envir=env)
     ## this version changes the visible copy of N only, since the argument
     ## passed to eval is '4'.
     eval(N <- 4, env)
     N
     get("N", envir=env)
     ## this version does the assignment in env, and changes N only there.
     evalq(N <- 5, env)
     N
     get("N", envir=env)

     ##
     ## Uses of local()
     ##

     # Mutually recursive.
     # gg gets value of last assignment, an anonymous version of f.

     gg <- local({
         k <- function(y)f(y)
         f <- function(x) if(x) x*k(x-1) else 1
     })
     gg(10)
     sapply(1:5, gg)

     # Nesting locals. a is private storage accessible to k
     gg <- local({
         k <- local({
             a <- 1
             function(y){print(a <<- a+1);f(y)}
         })
         f <- function(x) if(x) x*k(x-1) else 1
     })
     sapply(1:5, gg)

     ls(envir=environment(gg))
     ls(envir=environment(get("k", envir=environment(gg))))