---
title: "The envnames package helps navigate user-defined and function execution environments, and find objects in nested environments"
author: "Daniel Mastropietro (mastropi@uwalumni.com)"
date: "`r Sys.Date()`"
output:
  rmarkdown::pdf_document:
    toc: true
    number_sections: true
vignette: >
  %\VignetteIndexEntry{Overview of the envnames package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r echo=FALSE}
#library(knitr)
#opts_chunk$set(include=TRUE, warning=FALSE)
```


```{r echo=FALSE}
library(envnames)
rm(list=ls())
```

\newpage
# Introduction

The main goal of this package is to overcome the limitation of the `environmentName()` function in the base package which does not return the name of an environment unless it is a package, a namespace, or a system environment (e.g. the global environment, the base environment). In fact, the `environmentName()` function returns an *empty string* when the argument is a user-defined environment.

On the other hand, the environment itself is identified solely by its memory address, which makes it difficult to track an environment once we have defined a number of them. These limitations --and the workaround provided by this package-- can be seen by running the following code snippet:  

```{r Motivation}
myenv <- new.env()
cat("The name of the environment just defined is: ", environmentName(myenv), "(empty)\n")
cat("Simply referencing the environment just defined yields its memory address,
    which is not so helpful: "); print(myenv)
cat("Using the environment_name() function of the envnames package gives
    the environment name:", environment_name(myenv))
```

Clearly the last one is the result we most likely want, and the envnames package makes this possible by creating a lookup table that maps environment names to their memory addresses. The different functions of this package use this lookup table to provide the user with valuable information, such as the name of the environment where an object resides, be it a package environment, a user-defined environment, or *even* a function execution environment.

Why do we care about knowing the name of user-defined environments and function execution environments? That piece of information may be handy for example under the following scenarios:

- working in a package where user-defined environments have been defined in a nested structure:  
this package facilitates the navigation through those environments and their connection between them, eliminating e.g. the use of `ls()` as a rudimentary tool to identify the human-understandable environment (e.g. `myenv`) referred by an environment given by its memory address (e.g. `<environment: 0x063dbc90>` in 32-bit systems or `<environment: 0x00000000063dbc90>` in 64-bit systems), as already seen above.  
For more information and examples, see below the section on function `get_env_names()`, that returns a map of currently defined environments and the way they are connected or nested.  
- debugging an application:  
this package makes it easier to retrieve variables in different environments; for instance, retrieve the value of a variable in the parent environment to the environment where the debugger is currently positioned, which could well be a function execution environment.  
For more information and examples, see below the sections on functions `get_obj_name()` and `get_obj_value()`, which can be used to retrieve the name and value of the variable leading to a particular variable in connected environments, and the section on `environment_name()`, which can be used to retrieve the name of an execution environment.

Apart from this core functionality, additional tools were added during the package development process which include:

- an enhancement of the built-in `exists()` function with the capability of searching objects inside *user-defined environments* and *recursively* --i.e. in *nested* environments, defined inside other environments--, as well as searching objects that are the *result of expressions*. This functionality is provided by the `obj_find()` function.  
- a simplification of the output obtained when retrieving the calling function name and the stack of calling functions, currently provided by the built-in function `sys.calls()`. This functionality is provided by functions `get_fun_name()`, `get_fun_calling()`, and `get_fun_calling_chain()`, which return simple strings or array of strings with the function names of interest.  
- the retrieval of the memory address of an object. This functionality is provided by the `get_obj_address()` function.  

Currently the package has 11 functions directly accessible to the user (plus one function that is an alias).

**Definition of workspace**: despite being a widely used concept, we want to emphasize here that in this document we use the word "workspace" to refer to the memory space where all *visible* objects exist. In practice, this includes all the environments that are reachable via the `search()` path, namely the system environments (global environment, base environment), all loaded packages, and all user environments defined within and, if inside packages, *exported*.
*Note that package namespaces are not part of the workspace.*  

**Naming convention**: Function names are all small caps and the underscore is used to separate keywords (e.g. `environment_name()`, `get_obj_address()`, etc.)




# Description of the 11 functions in the package

This section describes the functionality of the 11 available functions, which are now briefly described as 7 groups made up of functions with similar functionality and sorted by relevance in terms of historical and practical use:

1) `get_env_names()`, used to retrieve the name of all the environments defined in the workspace together with their memory address. This is an address-name lookup table, the core element of the package that allows the "magic" to happen.  

2) `environment_name()` / `get_env_name()` (its alias), used to get the name of user-defined and execution environments (as well as all other named environments).  

3) `obj_find()`, used to find an object in the workspace and recursively within environments.  

4) `get_fun_name()`, `get_fun_calling()`, `get_fun_calling_chain()`, used to get the function calling name and stack displayed in a format that is easier to manipulate than the one provided by `sys.calls()`.  

5) `get_fun_env()`, used to retrieve a function's execution environment.  

6) `get_obj_name()`, `get_obj_value()`, used to retrieve the *name* and *value* of the object leading to a given function's parameter.  

7) `get_obj_address()`, `address()`, used to get the memory address of an object; `get_obj_address()` first looks for the object (using `obj_find()`), while `address()` assumes it exists in the environment where the function is run.  

Each of the above set of functions will be described in the following sub-sections, where each title is a sentence stating the main purpose of the presented function(s).




\newpage
## `get_env_names()`: retrieve the address-name lookup table of defined environments
The `get_env_names()` function returns a map of all the environments defined in a given environment. If no environment location is given, the map includes all the environments existing in the whole workspace.

In practice, the map is an address-name lookup table that relates the memory address of each environment (be it a system environmet, a package environment, a user-defined environment, or optionally a function execution environment) to its name.

This address-name lookup table is the basis for the operation of most of the other functions in the package, which rely on it to retrieve the names of environments based on their memory addresses.

The signature of the function is the following:  
`get_env_names(envir = NULL, include_functions = FALSE)`.

### Examples

#### Let's start with the definition of a few environments
We define a couple of environments and nested environments.

```{r DefineEnvironments}
env1 <- new.env()
env_of_envs <- new.env()
with(env_of_envs, env21 <- new.env())
```

Note that environment `env21` is *nested* in environment `env_of_envs`.

#### Basic operation
The following call returns a data frame containing the address-name lookup table, where the two main columns are:  
- `address` that contains the memory address of the environment, and  
- `name` that contains  the name of the environment.

The other columns are used to give context to the environments, such as:  
- `path` which tells us how to reach user-defined environments that are nested within other user-defined environments. The path is relative to the `envir` environment given as parameter, or from the global environment if no `envir` is given. As an example, see the case for environment `env21` nested within `env_of_envs`.  
- `location` which indicates, for instance, the package where an environment is defined, or the name of the enclosing environment of a function --i.e. where the function is defined--, if the concerned environment is a function's execution environment.

```{r GetLookupTable}
get_env_names()
```

For instance, in the above map we can see that the `envnames` package defines an environment called `testenv` which contains two other nested enviroments: `env1` and `env22`.

We can also restrict the lookup table to the environments defined within another environment. Now the `path` to the environment is relative to the environment on which the search is restricted (indicated as the `envir` parameter of the function).

```{r GetLookupTableRestricted}
get_env_names(envir=env_of_envs)
```




\newpage
## `environment_name()`: retrieve name of user-defined and function execution environments
The `environment_name()` function (or its alias `get_env_name()`) extends the functionality of the built-in `environmentName()` function by also retrieving the name of user-defined environments and function execution environments.

Although the name of an environment can be easily retrieved with `deparse(substitute(env1))` where `env1` is a user-defined environment, the most useful scenario is when we have just the *memory address* of the environment where e.g. an object resides (as in e.g. `<environment: 0x0437fb40>` in 32-bit systems or `<environment: 0x000000000437fb40>` in 64-bit systems). In this scenario, `environment_name()` can tell us the *name* of the environment having that memory address.  

Note that the address-to-name resolution also works for *function execution environments*, as we shall see in the examples below.

The signature of the function is the following:  
`environment_name(env, envir = NULL, envmap = NULL, matchname = FALSE, ignore = NULL, include_functions = FALSE)`.

### Examples

#### Basic operation
Let's retrieve the names of the environments defined above. This may sound trivial because we are already typing the environment name! However, we receive additional information as follows:

- the output from the first call includes *all* the environments where the environment with the given name (e.g. `env1`) is found.

- the output from the second call contains the *path* to use (starting from the calling environment) in order to reach the environment being searched for (e.g. stating that `env21` is found inside environment `env_of_envs`).

```{r GetEnvironmentNames, warning=FALSE}
cat("Name of environment 'env1':\n")
environment_name(env1)
cat("Name of environment 'env21':\n")
environment_name(env21)
```

For future reference, let us point out that the first case above is a case of *environments with the same name* existing in *different environments*.

If we already know the environment where the environment of interest is defined, we can specify it in the `envir` parameter so that the search for the environment is restricted to the specified  environment:

```{r GetEnvironmentNamesSpecifyingLocation, warning=FALSE}
cat("Name of environment 'env1' when we specify its location:\n")
environment_name(env1, envir=globalenv())
cat("Name of environment 'env21' when we specify its location:\n")
environment_name(env21, envir=env_of_envs)
```

Note that *no path information is attached now* to the returned names in either case, because only one environment is found inside the respective specified environments.

We can also retrieve the name of the `testenv` environment:

```{r GetNameOfTestEnv}
cat("Name of environment 'testenv':\n")
environment_name(testenv)
```
where we obtain the information that `testenv` is defined in package `envnames`.

#### More advanced examples
As above we saw a case of environments with the same name existing in different environments, let's now see a case of *different environments* having the *same memory address*.

So, let's define a new environment that points to one of the already defined environments, and let's retrieve its name as above:

```{r GetNameOfNewEnvironmentThatPointsToAnExistingEnvironment}
e_proxy <- env_of_envs$env21
environment_name(e_proxy)
```

What we get is a named array containing the names of *all* the environments (in alphabetical order) that point to the same memory address (in this case `env21` and `e_proxy`). The names attribute of the array contains the environments where these environments are found (in this case `env_of_envs` defined in the global environment, and `R_GlobalEnv`, the global environment).

We can disable the behaviour of matching environments *just* by memory address by setting the `matchname` parameter to `TRUE` so that the returned environments must match both the memory address *and* the given name:

```{r CallEnvironmentNameWithMatchNameTRUE1}
environment_name(e_proxy, matchname=TRUE)
```

Now the result is an *unnamed* array because there is only one environment matched by the search for the `e_proxy` environemnt. Furthermore, the result indicates that the environment is defined in the global environment, as otherwise the location where it were defined would be part of the name (as in e.g. `env1$e_proxy`).

Note however that the last call could actually return *more than one environment* in the case where environments sharing the same name (`e_proxy` in the above example) were defined in different environments. We could have this situation if we defined an environment called `"e_proxy"` in environment `env_of_envs`, as shown in the following example:

```{r CallEnvironmentNameWithMatchNameTRUE2}
env_of_envs$e_proxy <- new.env()
environment_name(e_proxy, matchname=TRUE)
```
Again a named array is returned with all the matches (by name) to the searched environment.

Finally, if we try to retrieve the environment name of a non-existing environment, we get `NULL`.

```{r CallEnvironmentNameOnNonExistingEnvironment, warning=FALSE}
environment_name(non_existing_env)
```

#### Retrieving the environment name associated with a memory address
Now suppose we have a memory address and we would like to know if that memory address represents an environment.
We can simply call `environment_name()` with the memory address passed as character argument, as shown in the following example:

```{r ConvertMemoryAddressToEnvironmentName}
env1_address = get_obj_address(testenv$env1)
environment_name(env1_address)
```

Of course, in practice we would not call the `get_obj_address()` function to get the environment's memory address; we would simply type in the memory address we are after. Note that this memory address depends on the architecture (32-bit or 64-bit) and it can be given in one of the following four ways:  

- an 8-digit (32-bit) / 16-digit (64-bit) address, e.g. `"0000000011D7A150"` (64-bit architecture)  
- a 10-digit (32-bit) / 18-digit (64-bit) address, e.g. `"0x0000000011D7A150"` (64-bit architecture)  
- either of the above addresses enclosed in `< >`, e.g. `"<0000000011D7A150>"` or `"<0x0000000011D7A150>"` (64-bit archiecture)  
- a 10-digit (32-bit) / 18-digit (64-bit) address preceeded by the `environment: ` keyword and enclosed in `< >`, e.g.: `"<environment: 0x0000000011D7A150>"` (64-bit architecture)  

(note: Linux Debian distributions may have a 12-digit memory address representation. The best way to know
what the memory address representation is in a particular system is to call e.g. `address("x")`.)

The last format is particularly useful when copying & pasting the result of querying an environment object, for example when typing `testenv$env1` at the `R` command prompt, in which case we get:

```{r}
testenv$env1
```

If the memory address does not match any of the above formats or does not represent an environment, `environment_name()` returns `NULL`. Ex:

```{r EnvironmentNameOfNonEnvironmentMemoryAddressIsNULL}
x = 2
environment_name(get_obj_address(x))
```

as the address of `x` is not the address of an environment.

#### Retrieving a function execution environment
If called from within a function with no arguments, `environment_name()` returns the execution environment of the function, which is identified by the name of the function. This is given with its *full path*, as in e.g. `env1$f`, when `environment_name()` is called from function `f()` defined in environment `env1`.

Since the first argument of `environment_name()` is the environment whose name we want to retrieve, we could also retrieve the execution environment of any calling function by specifying the corresponding `parent.frame`. Once again the name of such parent execution environment would be the name of the function given with its *full path*. 

The following example illustrates the above two use cases.

```{r GetExecutionEnvironmentName1}
with(env_of_envs$env21, {
  f <- function() {
    cat("1) We are inside function:", environment_name(), "\n")
    cat("2) The calling environment is:", environment_name(parent.frame()), "\n")
  }
  g <- function() {
    f()
  }
})
cat("Having defined both f() and g() in environment env_of_envs$env21,
    and having function g() call f()...\n")
cat("...when we call env_of_envs$env21$f() from the global environment,
    we get the output that follows:\n")
env_of_envs$env21$f()
cat("\n...and when we call f() from inside function g(),
    we get the output that follows:\n")
env_of_envs$env21$g()
```
Note that, in the second case when `f()` is called from `g()` --and not directly from the global environment--, the enviroment showing as path to `f()` is *not* `env_of_envs$env21` (as we would have expected) but `e_proxy`. The reason is that environment `e_proxy` (in the global environment) points to the same memory address as `env_of_envs$env21`. And since environment names are retrieved by their memory address  (which in this case is the memory address of `f`'s execution environment), there may be more than one environment matching the same memory address. In such cases, the rule implemented in `environment_name()` is to retrieve the matching environment whose name comes first in alphabetical order (which in this case is `e_proxy` --coming before both `env_of_envs$e_proxy` and `env_of_envs$env21` in alphabetical order, all environments that match the memory address of the environment where `f()` is defined).

But if we call `env_of_envs$env21$f()` (instead of calling `f()` as above) from a function `h()` defined in the `env_of_envs$env21` environment, we get:

```{r GetExecutionEnvironmentName2}
with(env_of_envs$env21, {
  f <- function() {
    cat("1) We are inside function", environment_name(), "\n")
    cat("2) The calling environment is:", environment_name(parent.frame()), "\n")
  }
  h <- function() {
    env_of_envs$env21$f()
  }
  }
)
env_of_envs$env21$h()
```

i.e., when making explicit the location of function `f()`, such location is shown as part of the name of the execution environment (as opposed to seeing a "supposedly strange" location `e_proxy` as above).




\newpage
## `obj_find()`: find the environments where (visible) objects exist
With the `obj_find()` function we can check if an object exists in the whole workspace and retrieve all the environments where it has been found. In the case of packages, only *exported* objects are searched for.

All environments --including system environments, packages, user-defined environments, and optionally function execution environments-- are crawled and searched for the object. This includes any environments that are defined *within* other environments (*nested*).

It therefore represents an enhancement to the built-in `exists()` function, which does *not* search for an object inside user-defined and nested environments, nor tells use *where* the object is defined.

The function returns a character array with all the environments where the object has been found.

Objects to search for can be specified either as a symbol or as a string. Ex: `obj_find(x)` and `obj_find("x")` both look for an object called "x". They can also be the result of an expression as in `v[1]`.

The function returns `NULL` if the object is not found or if the expression is invalid. For instance `obj_find(unquote(quote(x)))` returns `NULL` because the `unquote()` function does not exist in R.

The signature of the function is the following:  
`obj_find(obj, envir = NULL, envmap = NULL, globalsearch = TRUE, n = 0, return_address = FALSE, include_functions = FALSE, silent = TRUE)`

### Examples

#### Let's start with a few object definitions
We define a couple of objects in the environments already defined above:

```{r DefineObjectsInEnvironments}
x <- 5
env1$x <- 3
with(env_of_envs, env21$y <- 5)
with(env1, {
  vars_as_string <- c("x", "y", "z")
})
```

#### Basic operation
Now let's look for these objects:
```{r LookForObjects1}
environments_where_obj_x_is_found = obj_find(x)
cat("Object 'x' found
in the following environments:"); print(environments_where_obj_x_is_found)
environments_where_obj_y_is_found = obj_find(y)
cat("Object 'y' found
in the following environments:"); print(environments_where_obj_y_is_found)
```

(if we are seeing more environments than expected in the above output, let us recall that two `e_proxy` environments point to the same environment as `env_of_envs$env21`)

```{r LookForObjects2}
environments_where_obj_is_found = obj_find(vars_as_string)
cat("Object 'vars_as_string' found
in the following environments:"); print(environments_where_obj_is_found)
```

Let's also look for the objects defined in `vars_as_string` and `vars_quoted`.
```{r LookForObjectsWhoseNamesAreGivenInArray}
environments_where_obj_1_is_found = obj_find(env1$vars_as_string[1])
  ## Here we are looking for the object 'x'
cat(paste("Object '", env1$vars_as_string[1], "' found
in the following environments:")); print(environments_where_obj_1_is_found)
environments_where_obj_2_is_found = obj_find(env1$vars_as_string[2])
  ## Here we are looking for the object 'y'
cat(paste("Object '", env1$vars_as_string[2], "' found
in the following environments:")); print(environments_where_obj_2_is_found)
environments_where_obj_3_is_found = obj_find(env1$vars_as_string[3])
  ## Here we are looking for the object 'z' which does not exist
cat(paste("Object '", env1$vars_as_string[3], "' found
in the following environments:")); print(environments_where_obj_3_is_found)
```

or using `sapply()` to look for all the objects whose names are stored in `env1$vars_as_strings` at once:

```{r LookForObjectsUsingSAPPLY}
environments_where_objs_are_found = with(env1, sapply(vars_as_string, obj_find) )
cat("The objects defined in the 'env1$vars_as_string' array are found
    in the following environments:\n");
print(environments_where_objs_are_found)
```

Note how calling `obj_find()` from within the `env1` environment (which we do in order to resolve the `vars_as_string` variable --the argument of `obj_find()`) still searches for the objects everywhere. This is because parameter `globalsearch` is set to `TRUE` (by default). If we set it to `FALSE` and we add `envir=env1` as searched environment, we would get a non `NULL` value only for the objects defined in the `env1` environment, as shown below:  

```{r LookForObjectsUsingSAPPLYNoGlobalSearch}
environments_where_objs_are_found = with(env1,
                      sapply(vars_as_string, obj_find, globalsearch=FALSE, envir=env1) )
cat("The objects defined in the 'env1$vars_as_string' array are found
    in the following environments (no globalsearch):\n");
print(environments_where_objs_are_found)
```
NOTE: Even if we run `sapply()` inside environment `env1`, it is important to add parameter `envir=env1` to the call to `obj_find()`; if we don't add it, *no object is found* because the calling environment for `obj_find()` (i.e. its parent environment) is *not* `env1` but the `sapply()` execution environment, where the objects do not exist.

We can also search for objects given as a symbol:

```{r LookForObjectAsASymbol}
environments_where_obj_x_is_found = obj_find(as.name("x"))
cat("Object 'x' found in the following environments:\n")
print(environments_where_obj_x_is_found)
```

Finally, we can also search for visible (exported) objects defined in packages:

```{r LookForObjectsDefinedInPackages}
environments_where_obj_is_found = obj_find(aov)
cat("Object 'aov' found in the following environments:\n")
print(environments_where_obj_is_found)
```




\newpage
## `get_fun_name()`, `get_fun_calling()`, `get_fun_calling_chain()`: retrieve functions in the function calling chain (stack)
Functions `get_fun_name()`, `get_fun_calling()`, and `get_fun_calling_chain()` can be used to retrieve information about
calling functions. The first two retrieve information about *one* function while the latter retrieves information about the functions in the calling chain or stack, in the same spirit as `sys.calls()`.

However, the `get_fun_calling_chain()` function was designed to give an output that is easier to handle than the output from `sys.calls()` in the practical scenario of making a decision based on the *name* of the calling function. The following section shows such an example.

The signatures of the three aforementioned functions are:  
`get_fun_name(n = 0)`  
`get_fun_calling(n = 1, showParameters = FALSE)`  
`get_fun_calling_chain(n = NULL, showParameters = FALSE, silent = TRUE)`

### Examples
The example of this section shows the practical impact of using the `get_fun_calling_chain()` function instead of the built-in `sys.calls()` function to retrieve the calling stack and make decisions based on the calling function names.

In particular note:  
- How easy it is to check what the calling function is (just do a string comparison as in e.g. `get_fun_calling() == "env1$f"`). On the contrary, when using `sys.call()` we first need to parse the output before making such a comparison. See **[this link](http://stackoverflow.com/questions/15595478/how-to-get-the-name-of-the-calling-function-inside-the-called-routine)** for more details.  
- We get a data frame containing the chain of calling functions, from the most recent call to least recent, including function parameters if desired.

#### Let's start with a few object definitions
1) First we define a couple of new environments:

```{r DefineTwoEnvironments}
env11 <- new.env()
env12 <- new.env()
```

2) Now we define an example function `h` to be called by two different functions `f` defined in two different user-environments. This function `h` sums `+1` or `+2` to the input parameter `x` depending on which function `f` was responsible for calling it.

```{r DefineFunctionH}
with(globalenv(), 
h <- function(x, silent=TRUE) {
  fun_calling_chain = get_fun_calling_chain(silent=silent)

  # Do a different operation on input parameter x depending on the calling function
  fun_calling = get_fun_calling(showParameters=FALSE)
  if (fun_calling == "env11$f") { x = x + 1 }
  else if (fun_calling == "env12$f") { x = x + 2 }

  return(x)
}
)
```

3) Finally we define the two functions `f` that call `h`, respectively in environments `env11` and `env12`:

```{r DefineTwoFunctionsFInSeparateEnvironments}
with(env11,
  f <- function(x, silent=TRUE) {
    fun_calling_chain = get_fun_calling_chain()
    return(h(x, silent=silent))
  }
)

with(env12,
  f <- function(x, silent=TRUE) {
    fun_calling_chain = get_fun_calling_chain()
    return(h(x, silent=silent))
  }
)
```

### Basic operation
We now run these functions `f` and take note of their output.

- Output from `env11$f()`:

```{r RunFunctionF1, echo=FALSE}
silent = FALSE
x = 0
cat("\nWhen h(x) is called by env11$f(x=", x, ") the output is: ", env11$f(x, silent=silent), "\n", sep="")
```

- Output from `env12$f()`:

```{r RunFunctionF2, echo=FALSE}
silent = FALSE
x = 0
cat("\nWhen h(x) is called by env12$f(x=", x, ") the output is: ", env12$f(x, silent=silent), "\n", sep="")
```

Note how easy it was (by using just a string comparison) to decide what action to take based on the `f()` function calling `h()` and perform a different operation.

Note also that, in order to decide between the two possible calling functions `env11$f()` or `env12$f()` we used `get_fun_calling()`, as opposed to `get_fun_name()`, because the latter returns *just* the function name, devoided of any environment name.




\newpage
## `get_fun_env()`: retrieve a function's execution environment
The `get_fun_env()` function can be used to retrieve the execution environment of a function by simply giving the function's name.

This removes the need of knowing the *position* of the function in the calling chain, which is a piece of information that is required by the usual way of retrieving a function's execution environment, namely with `parent.frame()`.

The following example illustrates.

### Basic operation
Let's start defining a couple of functions that make up a function calling chain. The called function `h()` retrieves and displays the value of variable `x` both inside `h()` and inside the calling function `env1$g()`, whose execution environment is retrieved by `get_fun_env("env1$g")`.

```{r GetFunEnv}
h <- function(x) {
  # Get the value of parameter 'x' in the execution environment of function 'env1$g'
  # The returned value is a list because there may exist different instances of the
  # same function.
  xval_h = x
  xval_g = evalq(x, get_fun_env("env1$g")[[1]])
  cat("The value of variable 'x' in function", get_fun_name(), "is", xval_h, "\n")
  cat("The value of variable 'x' inside function env1$g is", xval_g, "\n") 
}
env1 <- new.env()
with(env1, 
  g <- function() {
    x = 2
    return( h(3) )
  }
)
env1$g() 
```
When `get_fun_env()` is called from outside a function, it returns NULL, even when the function exists.

```{r GetFunEnvOutside}
cat("The execution environment of a function that is not in the calling chain is:\n")
print(get_fun_env("env1$g"))

```

### Advanced example that puts together `get_fun_calling()` and `get_fun_env()`
In this example the parent frame of function `h()` (i.e. the execution environment of the calling function) is retrieved with `get_fun_env(get_fun_calling())`.

```{r GetFunEnvCombinedExample}
h <- function(x) {
  parent_function_name = get_fun_calling(n=1)
  cat("Using get_fun_calling() and environment_name() functions:
      The parent frame of function", get_fun_name(), "is", get_fun_calling(n=2), "\n")
  # Get the value of parameter 'x' in the execution environment of function 'env1$g'
  # The returned value is a list because there may exist different instances of the
  # same function.
  xval_h = x
  xval_g = evalq(x, get_fun_env(parent_function_name)[[1]])
  cat("Using get_fun_name():
      The value of variable 'x' in function", get_fun_name(), "is", xval_h, "\n")
  cat("Using get_fun_env() and evalq() functions:
      The value of variable 'x' inside function", parent_function_name, "is", xval_g,"\n") 
}
env1 <- new.env()
with(env1, 
  g <- function() {
    x = 2
    return( h(3) )
  }
)
env1$g() 
```

Clearly in the above examples we *already know* the position of function `env1$g()` in the calling chain, so using `parent.frame()` would have sufficed. However, using `get_fun_env()` could help in case the function calling chain from withing `h()` changes in the future, in which case we would not need to update the number of the parent frame in order to refer to the execution environment of function `env1$g()`.




\newpage
## `get_obj_name()`, `get_obj_value()`: retrieve the name/value of an object at a specified parent generation
The `get_obj_name()` and `get_obj_value()` functions are intended to help track objects and their values as they are passed through different environments. The most useful of the two is `get_obj_name()`, because the *values* of linked objects are the same as they traverse the different environments, making `get_obj_value()` be almost the same as calling `eval()` or `evalq()` at any environment (except for some special cases described in the function's documentation). However, `get_obj_value()` provides some kind of shortcut to the required `eval()` or `evalq()` expressions that do the same thing.

When called from within a function `get_obj_name()` can be used to know the name of the object that *leads* to a particular parameter a few generations back following the function calling chain. In other words, it helps us know the object in a given parent generation that is "responsible" for a function's parameter value.

After learning a little more about `get_obj_name()`, one may have the impression that it gives the same result as the one provided by `deparse(substitute())`. However, this is **not** the case as is shown in the examples that follow.

The signatures of these two functions are:  
`get_obj_name(obj, n = 0, eval = FALSE, silent = TRUE)`
`get_obj_value(obj, n = 0, silent = TRUE)`

### Examples

#### Let's start with a few function definitions
```{r GetObjNameExampleDefinitions}
getObjNameAndCompareWithSubstitute <- function(y, eval=FALSE) {
  parent_generation = 2
  get_obj_name_result = get_obj_name(y, n=parent_generation, eval=eval)
  deparse_result = deparse(y)
  substitute_result = substitute(y, parent.frame(n=parent_generation))
  deparse_substitute_result = deparse(substitute(y, parent.frame(n=parent_generation)))
  eval_result = evalq(y, envir=parent.frame(n=parent_generation))
  if (!eval) {
    cat("Result of get_obj_name(y, n=", parent_generation, "): ", get_obj_name_result,
        "\n\tConceptually this is the name of the object at parent generation ",
        parent_generation,
        "\n\tLEADING to *parameter* 'y'.\n", sep="")
    cat("Result of deparse(substitute(y, parent.frame(n=", parent_generation, "))): ",
        deparse_substitute_result,
        "\n\tConceptually this is the substitution of *variable* 'y'
        at parent generation ", parent_generation,
        "\n\tconverted to a string.\n", sep="")
  } else {
    cat("Result of get_obj_name(y, n=", parent_generation, ", eval=", eval, "): ",
        get_obj_name_result,
        "\n\tConceptually this is the object LEADING to *parameter* 'y' evaluated
        at parent generation ", parent_generation, ".\n", sep="")
    cat("Result of deparse(y): ", deparse_result,
        "\n\tConceptually this is the value of *parameter* 'y' converted to a character
        string.\n", sep="")
    cat("Result of substitute(y, parent.frame(n=", parent_generation, ")): ",
        substitute_result,
        "\n\tConceptually this is the substitution of *variable* 'y' at parent generation ",
        parent_generation,
        ".\n", sep="")
    cat("Result of evalq(y, envir=parent.frame(n=", parent_generation, ")): ",
        eval_result,
        "\n\tConceptually this is the evaluation of *variable* 'y' at parent generation ",
        parent_generation,
        ".\n", sep="")
  }
}

callGetObjNameAndCompareWithSubstitute <- function(x, eval=FALSE) {
  getObjNameAndCompareWithSubstitute(x, eval=eval)
}
```

#### Basic operation
Let's compare the result of calling `get_obj_name()` with the result of `deparse(substitute())`:

```{r GetObjNameExampleCall1}
y <- -9   # Global variable with the same name as the parameter of testing function
z <- 3
callGetObjNameAndCompareWithSubstitute(z)
```

Note the conceptual difference: `deparse(substitute(y, parent.frame(n=2)))` retrieves the object assigned to `y` at parent generation 2 (`substitut`ion) and returns it as a string (`depars`ing), while `get_obj_name(y, n=2)` **first** *traces back* the object names in parent generations leading to parameter `y`, and **then** returns the name of the object at the specified parent generation.

When `eval=TRUE`, `get_obj_name()` behaves the same way as `deparse()`, because the values of the objects leading to parameter `y` in parent generations is always the same and equal to the parameter's value. This result is the same as the one obtained by calling `get_obj_value()`. The following example illustrates:

```{r GetObjNameExampleCall2}
y <- -9   # Global variable with the same name as the parameter of testing function
z <- 3
callGetObjNameAndCompareWithSubstitute(z, eval=TRUE)
```

That is, calling `get_obj_name(y, n=n, eval=TRUE)` (or its equivalent `get_obj_value()`) retrieves the value of parameter `y` in parent generation `n`, which is the same in all parent generations and equal to the value of parameter `y` inside the calling function. Therefore, this is the same as the result of `deparse(y)`.
On the other hand substituting or evaluating variable `y` in parent generation 2 concerns directly variable `y` in *that* parent generation.

#### Finding the parameter path leading to a given function's parameter
The `get_obj_name()` function can also be used to find the set of variables in the different parent environments leading to a specified variable in the current environment. A particular case of this is the parameter path in a function calling chain leading to a function's parameter, which is illustrated below.

Let's define a set of simple functions that create a calling chain, `f1() -> f2() -> f3()` each of them having a parameter with a different name (`x`, `y`, and `z`):

```{r RetrieveParameterPath}
f1 <- function(x) {
  cat("f1(x) is calling f2(y=x)...\n")
  f2(x)
}
f2 <- function(y) {
  cat("f2(y) is calling f3(z=y)...\n")
  f3(y)
}
f3 <- function(z) {
  cat("f3(z) is retrieving the parameter path from three parent environments
      leading to function parameter z...\n\n")
  cat("Output from get_obj_name(z, n=3, silent=FALSE):\n")
  variable_leading_to_z_3levels_back = get_obj_name(z, n=3, silent=FALSE)
}
w = 1.3
f1(w)
```

So, we clearly see the environments and variables leading to parameter `z` from `R_GlobalEnv$w`:  
`R_GlobalEnv$w -> f1$x -> f2$y -> f3$z`

### Use of `get_obj_value()`
The result of calling `get_obj_value()` is the same as calling `get_obj_name()` with `eval=TRUE`.
It may come as a handy function (by reducing writing) to use in debugger contexts to find out the value of variables in different environments.

The following example illustrates the use of the function from within a function and shows the difference with the result of using `evalq()`.
Let's start defining two functions:

```{r GetObjValueExampleDefinitions}
getObjValueAndCompareWithEval <- function(y) {
  parent_generation = 2
  get_obj_value_result = get_obj_value(y, n=parent_generation)
  eval_result = evalq(y, envir=parent.frame(n=parent_generation))
  cat("Result of get_obj_value(y, n=", parent_generation, "): ", get_obj_value_result,
      "\n\tConceptually this is the object LEADING to *parameter* 'y' 
      \tevaluated at parent generation ",
      parent_generation, ".\n", sep="")
  cat("Result of evalq(y, envir=parent.frame(n=", parent_generation, ")): ", eval_result,
        "\n\tConceptually this is the evaluation of *variable* 'y' at parent generation ",
        parent_generation, ".\n", sep="")
}

callGetObjValueAndCompareWithEval <- function(x) { getObjValueAndCompareWithEval(x) }
```

Now let's see the results of calling this function which explains the differences between `get_obj_value()` and `evalq()`.

```{r GetObjValueExampleCall}
y <- -9   # Global variable with the same name as the parameter of testing function
z <- 3
callGetObjValueAndCompareWithEval(z)
```




\newpage
## `get_obj_address()` and `address()`: retrieve the memory address of an object
Following are examples of using the `get_obj_address()` function to retrieve the memory address of an object, which is then checked by the `address()` function that calls the direct method (via a C function call) to retrieve an object's memory address. The differences between these two functions are also explained.

In the `get_obj_address()` function, the object can be given either as a symbol or as an expression. If given as an expression, the memory address of the *result* of the expression is returned. If the result is yet *another* expression, the process stops, i.e. the memory address of that final expression is returned.

Internally this funcion first calls `obj_find()` to look for the object (using `globalsearch=TRUE`) and then retrieves the object's memory address, showing the name of all the environments where the object was found, or `NULL` if the object is not found.  

The signature of the function is the following:  
`get_obj_address(obj, envir = NULL, envmap = NULL, n = 0, include_functions = FALSE)`

### Examples
The following two calls return the same result:

```{r GetObjectAddress1}
obj_address1 = get_obj_address(x)
cat("Output of 'get_obj_address(x)':\n"); print(obj_address1)
obj_address2 = with(env1, get_obj_address(x))
cat("Output of 'with(env1, get_obj_address(x))':\n"); print(obj_address2)
```

Note especially the last case, where calling `get_obj_address()` from within the `env1` environment still searches for the object everywhere.

We can restrict the memory addresses returned by making the environment where the object is located explicit --by either using the `$` notation or the `envir` parameter of `get_obj_address()`. In this case only the address of the specified object is returned, even if other objects with the same name exist within the specified environment. A few examples follow:

```{r GetObjectAddress2}
get_obj_address(env1$x)
get_obj_address(x, envir=env1)
with(env1, get_obj_address(x, envir=env1))
```

Note there is a slight difference between calling `get_obj_address()` using the `$` notation and calling it with the `envir=` parameter: in the latter case, the result is an *unnamed* array.    

&nbsp;
&nbsp;

Suppose now the object is an expression referencing three potential existing objects as strings, more specifically an array:

```{r GetNonExistentObjectAddress}
vars = c("x", "y", "nonexistent")
get_obj_address(vars[1], envir=env1)
sapply(vars, get_obj_address)
```

(if we are seeing more environments than expected in the above output, let us recall that environment `e_proxy` points to the same environment as `env_of_envs$env21`)

We can check that the memory address is correct by running the internal function `address()` which calls a C function that retrieves the memory address of an object:

```{r CheckMemoryAddressIsCorrect}
address(env1$x)
address(e_proxy$y)
```

Finally: why would we use `get_obj_address()` instead of `address()` to retrieve the memory address of an object? For two main reasons:  
- `get_obj_address()` first searches for the object in all user-defined environments, while `address()` needs to be called from within the environment where the object is defined.  
- `get_obj_address()` returns `NULL` if the object does not exist, while `address()` returns the *memory address* of the `NULL` object, which may be misleading.  

To prove the second statement, we simply run the following two commands which yield the same result:

```{r MemoryAddressOfNULL}
address(env1$nonexistent)
address(NULL)
```
while running `get_obj_address()` on the non-existent object yields `NULL`:

```{r MemoryAddressOfNonExistentIsNULL}
get_obj_address(env1$nonexistent)
```




\newpage
# Summing up
We have described all the 11 visible functions defined in the `envnames` package and shown examples of using them, as follows:  

1) We have used `get_env_names()` to retrieve all the environments defined in the workspace in the form of a lookup table where the environment name can be looked up from its memory address.  

2) We have used `environment_name()` / `get_env_name()` (its alias) to retrieve the name of an environment. This function extends the functionality of the built-in `environmentName()` function by retrieving:  
    - the name of a user-defined environment  
    - the name and path to environments defined inside other environments  
    - the name and path to the function associated to an execution environment  
    - the name of the environment associated to a memory address  

3) We have used `obj_find()` to find an object in the workspace. This function extends the functionality of the built-in `exists()` function by:  
    - searching for the object in user-defined environments and in function execution environments  
    - searching for the object recursively (i.e. in environments defined inside other environments)  
    - showing the environment where the object is defined  

4) We have used `get_fun_name()`, `get_fun_calling()`, `get_fun_calling_chain()` to get the stack of calling functions. These functions return the stack information in a manner that is much simpler than the built-in `sys.calls()` function, making it easier to check the *names* of the calling functions and make decisions that depend on them.  

5) We have used `get_fun_env()` to get the execution environment of a function in the calling chain by *simply passing the function's name*, so that we can retrieve the value of objects that exist within.  

6) We have used `get_obj_name()`, `get_obj_value()` to retrieve the name and value of the object leading to a given function's parameter.  

7) We have used `get_obj_address()`, `address()` to retrieve the memory address of an object. These functions provide a functionality that is not available in base R. Note that the `data.table` package also provides a function called `address()` to retrieve the memory address of an object; however the object is *not searched for in the whole workspace* as is the case with the `get_obj_address()` function in this package.  

&nbsp;
&nbsp;




\newpage
This vignette was generated under the following platform:
```{r SystemInfo, echo=FALSE}
data.frame(SystemInfo=Sys.info()[c("sysname", "release", "version", "machine")])
version
```