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 = sys.frame(sys.parent()), 
          enclos = if(is.list(envir) || is.pairlist(envir)) 
                       sys.frame(sys.parent()))
     evalq(expr, envir, enclos)
     eval.parent(expr, n = 1)
     local(expr, envir = new.env())

_A_r_g_u_m_e_n_t_s:

    expr: object of mode `expression' or`call' or an ``unevaluated
          expression''.

   envir: the `environment' in which `expr' is to be evaluated.  May
          also be a list or an integer as in `sys.call'.

  enclos: Only relevant if `envir' is a list. Specifies the enclosure,
          i.e., where R looks for objects not found in `envir'.

       n: parent generations to go back

_D_e_t_a_i_l_s:

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

     The `evalq' form is equivalent to `eval(quote(expr), ...)'.

     As `eval' evaluates its first argument before passing it to the
     evaluator, it allows you to assign complicated expressions to
     symbols and then evaluate them.  `evalq' avoids this.

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

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

_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 dataframes 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,
     sys.frame(sys.parent()))'.

_S_e_e _A_l_s_o:

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

_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 <- sys.frame(sys.parent())
        ## 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

     ##
     ## Uses of local()
     ##

     # Mutual recursives. 
     # 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))))

