get_env_names {envnames} | R Documentation |
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 |
include_functions |
flag indicating whether to include in the returned data frame user-defined environments defined inside function execution environments. |
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).
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 thenew.env()
function or using theparent.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 thelocation
environment.address
memory address of the environment. This is the key piece of information used by the package to retrieve the environment name with theenvironment_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 columnspath
andname
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.
Examples
# 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)