environment               package:base               R Documentation

Environment Access

Description:

     Get, set, test for and create environments.

Usage:

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

     is.environment(obj)

     .GlobalEnv
     globalenv()
     .BaseNamespaceEnv

     emptyenv()
     baseenv()

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

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

Arguments:

     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

Details:

     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
     available as 'baseenv()'.  The ultimate enclosure of any
     environment is the empty environment 'emptyenv()', to which
     nothing may be assigned. If one follows the 'parent.env()' chain
     of enclosures back far enough from any environment, eventually one
     reaches the empty environment.

     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.

Value:

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

See Also:

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

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

Examples:

     f <- function() "top level function"

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

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

     is.environment(.GlobalEnv) # TRUE

     e1 <- new.env(parent = baseenv())  # 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

