Looking for an object in nested environments

The following picture shows an environment space that highlights the connections between package and system environments (child -> parent relationships) and in particular the use of user-defined environments (outer_env and nested_env), which are part of the global environment and may be regarded as nested environments (within the global environment). The package includes the obj_find() function that is able to look for objects in the whole workspace including user-defined environments, even if they are nested in other user environments. This is an important feature because the R built-in function exists() does not look for objects in user-defined environments, but only in system and package environments. The only way to make exists() look for objects in user-defined environments is to specify them explicitly –but this doesn’t help if we don’t know where the object may reside! The following example illustrates the above limitations of the exists() function, and how such limitations are overcome with the obj_find() function. First we define the necessary environments, including objects x and y, as shown in the picture:

outer_env <- new.env()
outer_env$nested_env <- new.env(parent=emptyenv())
x <- 0
with(outer_env, x <- 3)
with(outer_env,
    {
        nested_env$x <- 5.7;
        nested_env$y <- "phrase"
    })

Now we check whether the objects exist using the exists() function:

cat("\n'x' exists?: ", exists("x"), "\n")
cat("\n'y' exists?: ", exists("y"), "\n")
## 
## 'x' exists?:  TRUE 
## 
## 'y' exists?:  FALSE

We clearly see two important limitations of the exists() function: - it does not check for existence in user-defined environments (y is not found, but it exists in the nested_env environment), - if the object exists, it doesn’t tell us where it is found. Instead, the following calls to the obj_find() function tell us the whole picture and is informative about the location of the objects (if existing):

cat("\nObject 'x' is found in the following environments:\n",
    paste(obj_find(x), collapse="\n"), "\n", sep="")
cat("\nObject 'y' is found in the following environments:\n",
    paste(obj_find(y), collapse="\n"), "\n", sep="")
cat("\nObject 'nonexisting' is found in the following environments:\n",
    paste(obj_find(nonexisting), collapse="\n"), "\n", sep="")
## 
## Object 'x' is found in the following environments:
## outer_env
## outer_env$nested_env
## R_GlobalEnv
## 
## Object 'y' is found in the following environments:
## outer_env$nested_env
## 
## Object 'nonexisting' is found in the following environments:

Not only is object y found, but object x is found in all three environments where it is defined, including the user-defined environments outer_env and nested_env, despite the fact that nested_env is nested in outer_env. The path to reach each object is shown using the $ notation, which is the symbol used to access the object’s value, as achieved by outer_env$nested_env$x.

h <- function() {
    x <- 10.37
    cat("Object 'x' is found in the following environments:\n",
        paste(obj_find(x, include_functions=TRUE), collapse="\n"), "\n", sep="")
}
env1 <- new.env()
with(env1, 
    g <- function() {
        x <- 2
        h()
    }
)
env1$g()
## Object 'x' is found in the following environments:
## env1$g
## eval
## h
## handle
## outer_env
## outer_env$nested_env
## process_group
## process_group.block
## R_GlobalEnv
## timing_fn
## withVisible