envnames (version 0.4.1)

get_env_names: Create a lookup table with address-name pairs of environments

Description

Return a data frame containing the address-name pairs of system, package, namespace, user-defined, and function execution environments in the whole workspace or within a given environment.

Usage

get_env_names(envir = NULL, include_functions = FALSE)

Arguments

envir

environment where environments are searched for to construct the lookup table. It defaults to NULL which means that all environments in the whole workspace should be searched for and all packages in the search() path should be returned including their namespace environments.

include_functions

flag indicating whether to include in the returned data frame user-defined environments defined inside function execution environments.

Value

A data frame containing the following seven columns:

• type type of environment ("user" for user-defined environments, "function" for function execution environments, "system/package" for system or package environments, "namespace" for namespace environments, and "empty" for empty environments such as emptyenv()).

• location location of the environment, which is only non-NA for user-defined and function execution environments:

  • for a user-defined environment, the location is the system environment or package where the environment resides (note that this may be different from the parent environment if the parent environment was set during creation with the parent= option of the new.env() function or using the parent.env() function)

  • for a function execution environment, the location is the function's enclosing environment, i.e. the environment where the function is defined.

• locationaddress the memory address of the location environment.

• address memory address of the environment. This is the key piece of information used by the package to retrieve the environment name with the environment_name() function. For functions, this is the address of the function's execution environment.

• pathname path to the environment and its name. This is the combination of columns path and name whose values are put together separated by $.

• path path to the environment (i.e. all environments that need to be traversed in order to reach the environment).

• name name of the environment.

The type column is used to distinguish between user-defined environments, function execution environments, package or system environments, namespace environments, and empty environments.

The data frame is empty if no environments are found in the given envir environment.

NULL is returned when an error occurs.

Details

The table includes the empty environment as well when the address-name pairs map is constructed on the whole workspace.

The search for environments is recursive, meaning that a search is carried out for environments defined within other user-defined environments and, when include_functions=TRUE within function execution environments.

The search within packages is always on exported objects only.

If envir=NULL the lookup table includes all system, package, and namespace environments in the search() path, as well as all user-defined found in any of those environments (with recursive search), and all function execution environments.

If envir is not NULL the lookup table includes just the user-defined and function execution environments found inside the given environment (with recursive search).

Examples

# NOT RUN {
# Create example of chained environments
env1 <- new.env()
with(env1, env11 <- new.env())
with(env1$env11, envx <- new.env())

# Address-name pairs of all environments defined in the workspace,
# including environments in the search path
get_env_names()  # returns a data frame with at least the following user environments:
                 # "env1", "env1$env11", "env1$env11$envx"  

# Address-name pairs of the environments defined in a given user-defined environment
get_env_names(env1)  # returns a data frame with the following user environments:
                     # "env11", "env11$envx"

# Address-name pairs of the environments defined in a given package
get_env_names(as.environment("package:stats")) # should return an empty data frame
                                               # (since the stats package does not
                                               # have any environments defined)
# }