environment_name {envnames}

Retrieve the name of an environment

Description

Retrieve the name of an environment as the environmentName function of the base package does, but extending its functionality to retrieving the names of user-defined environments and function execution environments.

Usage

environment_name(
  env = parent.frame(),
  envir = NULL,
  envmap = NULL,
  matchname = FALSE,
  ignore = NULL,
  include_functions = FALSE
)

Arguments

env

environment whose name is of interest. It can be given as an object of class environment, as a string with the name of the environment, or as a string with the memory address of the environment. The latter is useful to find out if a given memory address is the reference of an environment object. Note that the variable passed may or may not exist in the calling environment, as the purpose of this function is also to search for it (and return its name if it is an environment). It defaults to parent.frame(), meaning that the name of the environment that calls this function is retrieved.

envir

environment where env should be searched for. When NULL, env is searched in the whole workspace, including packages and user-defined environments, recursively.

envmap

data frame containing a lookup table with name-address pairs of environment names and addresses to be used when searching for environment env. It defaults to NULL which means that the lookup table is constructed on the fly with the environments defined in the envir environment –if not NULL–, or in the whole workspace if envir=NULL. See the details section for more information on its structure.

matchname

flag indicating whether the match for env is based on its name or on its memory address. In the latter case all environments sharing the same memory address of the given environment are returned. Such scenario happens when, for instance, different environment objects have been defined equal to another environment (as in env1 <- env). It defaults to FALSE.

ignore

one or more environment names to ignore if found during the search. These environments are removed from the output. It should be given as a character array if more than one environments should be ignored. See the details section for more information.

include_functions

flag indicating whether to look for user-defined environments inside function execution environments. This should be used with care because in a complicated function chain, some function execution environments may contain environments that point to other environments (e.g. the 'envclos' environment in the eval() function when running tests using the test_that package).

Details

If env is an environment it is searched for in the envir environment using its memory address. If env is a string containing a valid 16-digit memory address (enclosed in < >), the memory address itself is searched for among the defined environments in the envir environment. In both cases, if envir=NULL the search is carried out in the whole workspace.

It may happen that more than one environment exist with the same memory address (for instance if an environment is a copy of another environment). In such case, if matchname=FALSE, the names of ALL the environments matching env's memory address are returned. Otherwise, only the environments matching the given name are returned.

If envmap is passed it should be a data frame providing an address-name pair lookup table of environments and should contain at least the following columns:

• location for user-defined environments, the name of the environment where the environment is located; otherwise NA.

• pathname the full environment path to reach the environment separated by $ (e.g. "env1$env$envx")

• address an 8-digit (32-bit architectures) thru 16-digit (64-bit architectures) memory address of the environment given in pathname enclosed in < > (e.g. "<0000000007DCFB38>" (64-bit architectures)) Be ware that Linux Debian distributions may have a 12-digit memory address representation. So the best way to know is to check a memory address by calling e.g. 'address("x")'.

Passing an envmap lookup table is useful for speedup purposes, in case several calls to this function will be performed in the context of an unchanged set of defined environments. Such envmap data frame can be created by calling get_env_names. Use this parameter with care, as the matrix passed may not correspond to the actual mapping of existing environments to their addresses and in that case results may be different from those expected.

The following example illustrates the use of the ignore parameter:

for (e in c(globalenv(), baseenv())) { print(environment_name(e, ignore="e")) }

That is, we iterate on a set of environments and we don't want the loop variable (an environment itself) to show up as part of the output generated by the call to environment_name().

Value

If matchname=FALSE (the default), an array containing the names of all the environments (defined in the envir environment if envir is not NULL) having the same memory address as the env environment.

If matchname=TRUE, the environment name contained in env is used in addition to the memory address to check the matched environments (potentially many if they have the same memory address) so that only the environments having the same name and address as the env environment are returned. Note that several environments may be found if environments with the same name are defined in different environments. WARNING: in this case, the name is matched exactly as the expression given in env. So for instance, if env=globalenv()$env1 the name "globalenv()$env1" is checked and this will not return any environments since no environment can be called like that. For such scenario call the function with parameter env=env1 instead, or optionally with env=env1 and envir=globalenv() if the env1 environment should be searched for just in the global environment.

If env is not found or it is not an environment, NULL is returned.

Examples

# Retrieve name of a user-defined environment
env1 <- new.env()
environment_name(env1)                   		# "env1"

# Retrieve the name of an environment given as a memory address
env1_address = get_obj_address(globalenv()$env1)
environment_name(env1_address)           		# "env1"

# Create a copy of the above environment
env1_copy <- env1
environment_name(env1)                   		# "env1" "env1_copy"
# Retrieve just the env1 environment name
environment_name(env1, matchname=TRUE)   		# "env1"

# Retrieve the name of an environment defined within another environment
with(env1, envx <- new.env())
environment_name(env1$envx)              		# "env1$envx" "env1_copy$envx"
environment_name(env1$envx, matchname=TRUE)
  ## NULL, because the environment name is "envx", NOT "env1$envx"

# Get a function's execution environment name
with(env1, f <- function() { cat("We are inside function", environment_name()) })  
    ## "We are inside function env1$f"