Scoping, Environments and Closures

The R Language Definition describes an environment as two things: a frame, which is a set of symbol-value pairs, and an enclosure, which is a pointer to another environment. When R looks up the value of a symbol it examines the frame, and if the symbol is not there it follows the enclosure and repeats. Environments therefore form a tree in which the enclosures play the role of parents, rooted in the empty environment emptyenv(), which has no parent and is the direct enclosure of the base environment baseenv() (R-lang: Environments).

The manual’s section on the scope of variables starts from the workspace: the global environment is the root of the user workspace, an assignment from the command line makes the object belong to it, and its enclosing environment is the next environment on the search path, "and so on back to the empty environment that is the enclosure of the base environment" (R-lang: Scope of variables, R-lang: Global environment).

The same manual is careful about the words in the section on the lexical environment: a frame is a set of variables, an environment is a nesting of frames, or equivalently the innermost frame plus the enclosing environment (R-lang: Lexical environment). In everyday code the two words are used loosely; ls(env) lists the frame, and parent.env(env) follows the enclosure.

Environments are created in two ways. Every call to a function creates one, containing the arguments and the local variables, with the environment of the called closure as its enclosure. And new.env() creates one directly. They are objects like any other (typeof() and class() say "environment"), but unlike most R objects they are not copied when they are assigned or passed to a function: if you assign the same environment to several names and change one, the others change too (R-lang: Environments). Environments are the main exception to the copy-on-modify behaviour of R values, and section Environments as mutable hash maps uses that on purpose.

Source: R documentation: environment

The first script prints the named environments, creates one and asks where a function from a package lives. The printed form of an environment is <environment: R_GlobalEnv> for the named ones and <environment: 0x...>, with an address, for the rest.

Source: R documentation: environment

topenv() reports the workspace here because the script runs at the top level. desk is an anonymous environment with no name, and its enclosure is the workspace because new.env() takes its default parent from parent.frame(), the frame of whoever called it. A function from a package such as sd() has the namespace of its package as its environment (<environment: namespace:stats>), not the workspace, and a primitive function such as sum() has no environment at all (environment(sum) is NULL). The next sections explain why that matters.

The tree of environments is a set of chains, and a short loop with parent.env() walks one. The helper below stops at the empty environment, because parent.env(emptyenv()) is an error, not NULL.

Source: The R Language Definition: Environments

The first chain is the search path: the workspace, the default packages, Autoloads, and the base environment. The second is the chain of a function from a package: its own namespace, then the imports of the package, then the base namespace, then the workspace and the rest of the search path. That order is the reason a package keeps working when your workspace masks a base function, and it is explained in the section on namespaces below. The third chain is the one of a function frame: the frame has no name, and its enclosure is the workspace because the function was created there.

as.environment() accepts a position on the search path (1 is the workspace, 2 is the first attached package, and so on), the name of an entry of search(), or a list, which becomes the frame of a new environment whose enclosure is the empty environment. list2env() fills an existing environment from a named list, and as.list() goes the other way. At the top level there are no function calls, so the call-stack functions have nothing to report.

Source: R documentation: as.environment

A closure (a function written in R) carries its defining environment as part of its definition; environment(f) returns it and environment(f) <- value replaces it. The manual says that when the function is subsequently called, its evaluation environment is created with the closure’s environment as the enclosure, and that this is "not necessarily the environment of the caller" (R-lang: Lexical environment). Primitive functions and operators written in C have no environment.

Source: R documentation: environment

After environment(fine) <- rates the same function body finds a different fine_per_day, which shows that a function and its environment are two objects that happen to be stored together. Replacing the environment of a primitive function is no longer done: since R 4.5.0 it signals a warning and changes nothing (R NEWS, "Changes in R 4.5.0"; the help page calls the attempt deprecated), and the script catches the warning. Inside a call, sys.function() is the function being run, environment() is its frame, and the enclosure of the frame is the environment of that function.

An Introduction to R divides the symbols in the body of a function into three classes: formal parameters, which are the names in the argument list; local variables, whose values come from evaluating expressions in the body; and free variables, which are neither. Free variables become local variables if they are assigned to. R resolves a free variable by first looking in the environment in which the function was created, which is called lexical scope (R-intro: Scope). The R FAQ states the same rule as the first difference between R and the original S, whose free variables came from a set of global variables, as in C, with only a local and a global scope (R FAQ 3.3.1: Lexical scoping). Lexical scoping is analogous to the evaluation model of Scheme, and it is what makes closures useful.

Every name in a function body is looked up, including the names of functions. In the script below loan_days is a free variable, but so are -, {, <-, as.integer and max: codetools::findGlobals() lists them, and all of them except loan_days are found in the base environment at the end of the chain. The linter cannot see the variable that source("scenario.R") created, which is why that line carries a # nolint, and it is the same lookup that R CMD check and lintr use to warn about "no visible binding for global variable".

Source: The R Language Definition: Lexical environment

due_in() is the same argument as the cube() and sq() example in R-intro and in R FAQ 3.3.1. The inner function remaining() has a free variable loan_days. Under the scoping rules of the original S, a free variable was looked up among the global variables, so remaining() would read the global 21 and return 16. In R the variable is found in the frame of the call to due_in(), because that is where remaining() was created, and the result is 9. The third example shows the sentence "free variables become local variables if they are assigned to": the right-hand side loan_days + 7L is evaluated first and reads the global value, then the assignment creates a local variable of the same name; the global one is untouched.

The R manual puts the whole rule in one paragraph. When a variable is requested inside a function it is first sought in the evaluation environment, then in the enclosure, the enclosure of the enclosure, and so on; once the workspace or the environment of a package is reached the search continues up the search path to the environment of the base package, and if the variable is not found there the search proceeds to the empty environment and fails (R-lang: Lexical environment). The failure is the error object 'x' not found, shown with the other messages in Common errors and warnings.

When a name is used in the position of a function, R skips bindings that are not functions. That is why c <- 3 followed by c(1, 2) still works, and why a variable called nchar, sum or data does not break the calls of the function of the same name. The C interface documents the same rule: Rf_findFun does the lookup and "restricts the search to functions" (R-exts: Evaluating R expressions from C). In R code, the mode argument of get() and exists() expresses the same decision.

Source: R documentation: get

The reverse is not true: a name used as a value finds the first binding of any kind. The sum + 1 line fails with the message of arithmetic on a function, not with "object not found", because sum was found (it was the function defined in the script, which hides the one in base). Naming data after functions (c, t, df, data, sum) is legal and works most of the time, but it makes both reading and debugging harder, and conflicts() finds such cases (see Masking).

Scoping happens when code mentions a name. The functions below do the same lookup with a name held in a string, and let you choose the environment to start from. get(x, envir, mode, inherits = TRUE) returns the object or signals an error, exists() returns whether it was found, get0(x, envir, mode, inherits, ifnotfound) does both in one call, and mget() looks up a character vector of names and returns a named list, with inherits = FALSE by default (R documentation: get). The inherits argument says whether the enclosures of envir are searched too; with inherits = FALSE only the frame of envir is examined.

The pos argument selects the environment by position on the search path, by name or by environment, and envir is an alternative way to do the same. By default both mean the environment of the call to get(), which is the frame of the function that called it.

Source: R documentation: get

The exists("shelf_today", envir = desk) call is TRUE because desk has the workspace as its enclosure and inherits = TRUE follows it, while with inherits = FALSE the answer is FALSE: the same difference as between lexical lookup and a lookup of the frame alone. dynGet() is the other direction: it looks for an object in the frames of the callers, which is dynamic scope. The help page says it is "somewhat experimental" and to be used with caution, and the next section explains why dynamic scope is not R’s default.

assign(x, value, pos, envir, inherits = FALSE) is the inverse of get(). With the default inherits = FALSE it assigns in the frame of envir; with inherits = TRUE it searches the enclosures for an existing binding and assigns there, or in the workspace if there is none, which is what <<- does (R documentation: assign).

In addition to the environments of function calls, R has a search path of environments that are searched for names not found elsewhere. It is used for two things: packages of functions, and attached user data. The first element is the workspace and the last is the base package; an Autoloads environment holds proxy objects that may be loaded on demand; other environments are inserted with attach() or library() (R-lang: Search path). On the search path each item’s enclosure is the next item, so search() is simply the chain of enclosures that starts at the workspace. searchpaths() returns the same entries with the file-system path from which each package was loaded; the script prints only the final part of each path because the full paths depend on the machine.

Source: R documentation: search

library(tools) inserted package:tools at position 2, directly after the workspace, and that changed the enclosure of the workspace: parent.env(globalenv()) was package:stats before and package:tools after. detach() removes the entry from the path and leaves the namespace loaded (isNamespaceLoaded("tools") stays TRUE), which is also why detaching and re-attaching a package is not a reliable way to refresh it: the help page for detach says that the most reliable way to completely detach a package is to restart R. The pos argument of library() chooses another position, and library(mypkg, pos = "package:base") is the documented way to mask as little as possible (R documentation: library). The page Sessions, Workspaces and Startup shows the search path of a fresh session and how R_DEFAULT_PACKAGES changes it, and Packages, Libraries and Namespaces covers libraries, library() against require() and requireNamespace().

When two entries of the search path contain the same name, the one that comes first on the path wins and the other is masked. A package attached later is inserted in front of the earlier ones, so it masks them, and anything in the workspace masks every package, because the workspace is first. library() reports a clash when it attaches a package; the report is printed as a message, not as a warning, even though the argument that controls it is called warn.conflicts (R documentation: library). conflicts() lists the masked objects and conflicts(detail = TRUE) the places that mask them, and find() shows every entry of the search path that holds a given name (R documentation: conflicts).

In this installation none of the recommended packages of R masks stats or base, but two of them clash with each other: both boot and lattice have an object called melanoma, so attaching them in that order produces the real message.

Source: R documentation: library

The message names the package that is masked and the object (The following object is masked from 'package:boot':, printed with typographic quotes in a UTF-8 session) and find("melanoma") confirms that lattice is first. A definition made in the workspace masks silently, because nothing is being attached. The message appears the other way round, when a package or a database is attached while the workspace already holds an object of the same name, and then it says that the object is masked by .GlobalEnv (the attach() example in attach() and the older habits it came from prints that form). stats::sd() reaches the original whatever is masking it.

The best-known form of the message involves stats, because dplyr defines filter() and lag(), and base, because it defines intersect(), setdiff(), setequal() and union(). This script needs dplyr, 1.2.1 here, which is not part of base R.

Source: dplyr package documentation: reference index

The same-name function in stats is still reachable, as stats::filter(), and in the other direction the attached package is reachable with dplyr::filter() whether or not it is attached. Code in a script is clearer, and safer against a later library() call that masks something, when it qualifies the names of functions that clash. For the packages that do have to be attached, library() can resolve the clash at the moment of attaching.

Source: R documentation: library

exclude drops names from the attach, include.only attaches only the names given, and mask.ok declares that masking particular names is expected. Setting the option conflicts.policy to "strict" turns every unresolved conflict into an error, with the message printed above, and "depends.ok" exempts conflicts with declared dependencies. These arguments and the option are described under "Conflicts" in the help page of library; the warn.conflicts = FALSE argument only silences the message and resolves nothing.

Two details avoid surprises. First, since R 4.0.0 S3 method lookup by default skips the elements of the search path between the workspace and the base environment (R NEWS, "Changes in R 4.0.0"), so an S3 method that a package merely exports, without registering it, is no longer found through the search path. Methods and registration are covered on S3 Classes and Generics. Second, the search path is the tail of the chain only for code created in the workspace. Code inside a package namespace reaches the workspace and the search path last, as the next section shows.

Every time a function is invoked a new evaluation frame is created, and a "context" is placed on a list of contexts, the call stack; when the function finishes, its context is removed. The environments of the currently active calls are accessible through the call stack, and making variables defined higher up the stack available is called dynamic scope: the binding for a variable is the most recent one in time. The manual says that this contradicts the default scoping rules of R, which use the bindings in the environment where the function was defined, and that some functions, particularly those that use and manipulate model formulas, need to simulate dynamic scope by accessing the call stack directly (R-lang: The call stack).

Access to the stack is provided by the family of functions whose names start with sys., plus parent.frame():

Source: R documentation: sys.parent

Source: R documentation: sys.parent

The frame number of report() is 3 because checkout() is frame 1, validate() frame 2, and the workspace is frame 0. sys.parents() lists the parent of each frame (0 for checkout(), because it was called from the workspace). parent.frame() at the top level is the workspace, and in is_called_from() it is whatever frame the call was made in, wherever the function was defined. Three cautions are in the help page. sys.parent() and parent.frame() refer to the context of the parent interpreted function, so internal functions (which may or may not set contexts) may not be counted, and S3 methods can do surprising things. As a consequence of lazy evaluation these functions look at the stack at the time they are evaluated, not at the time they are called, so passing a call to them as an argument is "unlikely to be a good idea". And the sys. functions are themselves not counted in the stack, so they never report their own context.

The difference between the enclosure and the calling environment is where lexical scope and dynamic scope part ways, and a function called from inside another function shows it. is_overdue() is defined at the top level, so its enclosure is the workspace. Whatever variable named loan_days exists in the function that calls it, it still reads the one in the workspace.

Source: R FAQ 7.12: What are the enclosing and parent environments?

In at_the_desk() the call is_overdue(10L) returns FALSE, because 10 days out is not more than the global 21. Under dynamic scope the function would have found the loan_days <- 7L of its caller and answered TRUE. When a function really wants the caller’s variable, as model-fitting functions want the variables of a formula, it has to ask for it explicitly with parent.frame(), as is_overdue_here() does. The third example changes the enclosure itself with environment(fn) <- ..., which is the lexical way to give one function a different view of its free variables.

R FAQ 7.12 explains why both exist. Enclosing environments matter because a function can use the variables in its enclosure to share information with other functions or with other invocations of itself; this relies on the enclosing environment being the same each time the function is called (in C that would be done with static variables). Parent environments matter because things like model formulae need to be evaluated in the environment the function was called from, since that is where the variables will be available, and that relies on the parent environment being potentially different with each call. It also gives a way to say the difference between R and S: in S the enclosing environment is always the workspace, and in R it is wherever the function was created.

Most functions never touch parent.frame(). It appears in three places, which are the ones to recognise when reading code.

Whenever a function takes an envir or where argument whose default is parent.frame(), it is following the convention that the caller’s frame is the place to work in, and tests that pass an explicit environment avoid touching the real workspace.

A closure is a function together with the environment in which it was created. Because the environment is part of the function, variables of that environment stay alive as long as the function does, and every call to the function can read and change them. R-intro puts it as "lexical scope can also be used to give functions mutable state" and builds a bank account out of three functions created inside open.account(): deposit, withdraw and balance, all of which see the variable total of the call that created them (R-intro: Scope). The same design in the library-shelf scenario is a loan desk: make_loan_desk() returns three functions that share the lists of ISBNs and due dates created inside the call, and each desk made by the factory has its own.

Source: An Introduction to R: Scope

The two desks do not share anything: the book lent at kids_desk is due on 2026-07-07 because that desk was created with days = 7L, and giving a book back at main_desk does not change kids_desk. The state lives in one environment per call of make_loan_desk(), which is the enclosure of lend(), give_back() and outstanding(); ls() on it shows the three functions, the two state variables and the argument days. Because it is an ordinary environment, it can be inspected from outside, as the last lines do. That is useful when debugging and it also shows the weakness of the technique: there is nothing private about a closure’s environment.

The factory make_loan_desk() is a function factory, a function whose value is a function. The page Function Factories and Higher-Order Functions treats the patterns built on that: generators, decorators, memoisation and partial application. When state and several operations have to be bundled with methods and inheritance, the closure approach scales into the Reference Classes and R6 classes of Reference Classes and R6, which are environments with a class attribute.

A closure keeps its whole creation environment, not only the variables it mentions. Anything created in the factory before it returns stays reachable, which can keep a large table in memory for as long as the function exists, and the arguments of the factory are promises (see Lazy Evaluation and Promises), so a factory whose argument is a variable that changes later may capture the later value unless the argument is forced.

Source: The R Language Definition: Lexical environment

The first closure keeps scratch as well as max_days. Removing it with rm() before returning, or doing the heavy work in a helper function whose frame disappears, releases the memory. lazy_checker sees 7 because the promise limit was not evaluated until the first call, after limit had been changed; force(max_days) in the factory evaluates the argument immediately, so forced_checker kept 21.

Source: R documentation: exists, get0

The $ and [[ forms never look at the enclosures; get() and exists() do, unless told not to. In the library-shelf scenario a hash map is a natural way to count loans by ISBN: the keys are strings and each loan updates one entry, without rebuilding a vector.

Source: R documentation: get, mget

%||% returns its right-hand side when the left-hand side is NULL; it was added to base R in 4.4.0 (R NEWS, "Changes in R 4.4.0"). The ISBN keys are not syntactic names, so loan_count$9780306406157 would be a parse error, and the [[ and get() forms are the ones to use; backticks make $ possible but unreadable. Names have to be character strings: env[[1L]] is an error, and env[1L] is a "not subsettable" error. The order of names(env) and of eapply() depends on the hash table and is not guaranteed, which is why the script sorts with ls() and sort() before printing anything; as.list(env, sorted = TRUE) is the sorted form.

A hash map built with new.env() is not a clean dictionary, because its enclosure is the caller’s frame and get() and exists() search the enclosures. Looking up a key that was never stored can therefore return an unrelated object that has that name somewhere in the chain, including a function from base R. For a collection of arbitrary keys, create the environment with new.env(parent = emptyenv()) and pass inherits = FALSE where it matters.

Source: R documentation: environment

exists("c", envir = cache) is TRUE because of the function c() in the base environment at the end of the chain, while cache[["c"]] is NULL (so is.function() says FALSE) because [[ looks only at the frame. The same defect is visible the other way around: an environment whose enclosure is the empty environment cannot evaluate any code that calls a function, because even + is looked up as a function; eval() reports could not find function "+". Use the empty parent for data and a normal parent for code.

Another consequence of how an environment stores values is that assigning NULL to a key keeps the binding, with NULL as its value, while assigning NULL to a list element removes the element. To remove a key from an environment use rm(), and test for a key with exists() and not with is.null() if NULL can be a stored value.

Source: R documentation: rm

Since environments are not copied, they behave like references: a function that receives one can modify the caller’s collection, with no need to return the result. The R Language Definition notes that environments are not standard objects, in particular that they are not copied on assignment (R-lang: Lexical environment), and that assigning attributes to an environment can lead to surprises, because the attributes belong to the single shared object (R-lang: Environments).

Source: The R Language Definition: Environments

receive(stock, 2L) changed the caller’s stock without returning anything. The list version returned a modified copy and left stock_list alone, which is the copy-on-modify behaviour described on Memory and Copy Semantics. as.list() takes a snapshot, which is itself a value. Reference semantics is the source of the efficiency of environments, because nothing is copied when a million keys change, and of their hazards, because any function that can see the environment can change it. A function that modifies an argument in place should say so in its name and its documentation, and a shared environment that should not change can be locked.

lockBinding() makes a single binding read-only, lockEnvironment() forbids adding or removing bindings (and, with bindings = TRUE, locks every existing binding too), and makeActiveBinding() installs a function that runs whenever a variable is read or assigned. The help page notes that namespace environments of packages with namespaces are locked when loaded, that locked bindings can still be removed unless the environment is locked, and that active bindings are used to implement Reference Classes (R documentation: lockBinding).

Source: R documentation: lockBinding

After lockEnvironment(settings) the existing value loan_days can still be changed (settings$loan_days <- 7L ran without an error), but a new key cannot be added. With bindings = TRUE the values are frozen as well. Locking is the cheap way to make an environment of constants safe from accidental changes; the base environment and package namespaces use it. Since R 4.3.0 attach() of an environment with active bindings preserves them (R NEWS, "Changes in R 4.3.0").

attach() was the standard way to use the columns of a data frame without writing df$ in older tutorials. It does not attach the data frame: it creates a new environment on the search path, at position 2 by default, and copies the columns into it, and the help page says that for this reason it can lead to confusion and that the good practice in interactive use is with(). The script shows the confusion: assigning to a column name creates a variable in the workspace, leaving both the attached copy and the data frame as they were, and attaching twice shows the two kinds of masking message.

Source: R documentation: attach

The help page also gives the rule for programs: functions should not change the search path unless that is their purpose, and when they have to, they should use a distinctive name and follow attach() immediately with an on.exit() call to detach(). A useful side of the same function is attach(NULL, name = "mine"), which creates an empty environment on the search path into which objects can be assigned, and detach("mine") removes it again; this is a legitimate use that does not copy anything.

The other habits of that era are building variable names out of strings, and evaluating the result as code. The script compares them with a named list.

Source: R documentation: assign

assign() and get() with computed names are not wrong, and they are the right tools for environments, which is why this page uses them; the older habit is to use the workspace as the container, where the variables cannot be iterated, passed, saved with one call, or cleaned up without searching the whole workspace with ls(pattern = ). The wider list of differences between old and current R is on What’s New and Migrating Older Code, and the idioms that follow from this page are on Idioms and Common Pitfalls.