environment               package:base               R Documentation

_E_n_v_i_r_o_n_m_e_n_t _A_c_c_e_s_s

_D_e_s_c_r_i_p_t_i_o_n:

     Get, set, test for and create environments.

_U_s_a_g_e:

     environment(fun = NULL)
     environment(fun) <- value

     is.environment(obj)

     .GlobalEnv
     globalenv()
     .BaseNamespaceEnv

     new.env(hash = FALSE, parent = parent.frame())

     parent.env(env)
     parent.env(env) <- value

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

     fun: a 'function', a 'formula', or 'NULL', which is the default.

   value: an environment to associate with the function

     obj: an arbitrary R object.

    hash: a logical, if 'TRUE' the environment will be hashed

  parent: an environment to be used as the enclosure of the environment
          created.

     env: an environment

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

     Environments consist of a _frame_, or collection of named objects,
     and a pointer to an _enclosing environment_.  The most common
     example is the frame of variables local to a function call; its
     enclosure is the environment where the function was defined.  The
     enclosing environment is distinguished from the _parent frame_: 
     the latter (returned by 'parent.frame') refers to the environment
     of the caller of a function.

     When 'get' or 'exists' search an environment with the default
     'inherits = TRUE', they look for the variable in the frame, then
     in the enclosing frame, and so on.

     The global environment '.GlobalEnv', more often known as the
     user's workspace, is the first item on the search path.  It can
     also be accessed by 'globalenv()'.  On the search path, each
     item's enclosure is the next item.

     The object '.BaseNamespaceEnv' is the namespace environment for
     the base package.  The environment of the base package itself is
     represented by 'NULL', the ultimate enclosure of any environment:
     If one follows the 'parent.env()' chain of enclosures back far
     enough from any environment, eventually one reaches 'NULL'. This
     means that arithmetic operators and the base package functions
     will be always be found by 'eval()' or 'get(..., inherits =
     TRUE)'.

     The replacement function 'parent.env<-' is extremely dangerous as
     it can be used to destructively change environments in ways that
     violate assumptions made by the internal C code.  It may be
     removed in the near future.

     'is.environment' is generic: you can write methods to handle
     specific classes of objects, see InternalMethods.

_V_a_l_u_e:

     If 'fun' is a function or a formula then 'environment(fun)'
     returns the environment associated with that function or formula.
     If 'fun' is 'NULL' then the current evaluation environment is
     returned.

     The assignment form sets the environment of the function or
     formula 'fun' to the 'value' given.

     'is.environment(obj)' returns 'TRUE' iff 'obj' is an
     'environment'.

     'new.env' returns a new (empty) environment enclosed in the
     parent's environment, by default.

     'parent.env' returns the parent environment of its argument.

     'parent.env<-' sets the enclosing environment of its first
     argument.

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

     The 'envir' argument of 'eval', 'get', and 'exists'.

     'ls' may be used to view the objects in an environment.

_E_x_a_m_p_l_e_s:

     ##-- all three give the same:
     environment()
     environment(environment)
     .GlobalEnv

     ls(envir=environment(approxfun(1:2,1:2, method="const")))

     is.environment(.GlobalEnv) # TRUE

     e1 <- new.env(parent = NULL)  # this one has enclosure package:base.
     e2 <- new.env(parent = e1)
     assign("a", 3, env=e1)
     ls(e1)
     ls(e2)
     exists("a", env=e2)     # this succeeds by inheritance     
     exists("a", env=e2, inherits = FALSE)
     exists("+", env=e2)     # this succeeds by inheritance

