r-statistics.co by Selva Prabhakaran

About

Lexical Scoping in R: How R Looks Up Variable Names (R Search Path)

When R encounters a variable name, it doesn't just look in your current workspace. It walks a chain of environments — from local to global to packages to base R — until it finds a match. This process is called lexical scoping, and understanding it explains most "mysterious" R behavior.

Have you ever wondered why you can use mean() without loading any package? Or why a variable inside a function doesn't clash with one outside? The answer is lexical scoping — R's systematic way of resolving names to values.

Introduction

Scoping answers one question: given a name like x, which value does it refer to?

R uses lexical scoping (also called static scoping). "Lexical" means the answer depends on where the code is written, not where it's called. Specifically:

  1. Look in the current environment (e.g., inside the function body)
  2. If not found, look in the parent environment (where the function was defined)
  3. Keep going up the chain until you reach the empty environment
  4. If still not found, throw object 'x' not found

This tutorial covers:

  • The four rules of lexical scoping
  • How the search path works
  • Name masking and conflicts
  • The :: operator for explicit lookups
  • Lexical vs dynamic scoping

The Four Rules of Lexical Scoping

Rule 1: Name Masking

R looks for names from the inside out. Inner definitions mask outer ones:

x <- 10 # global outer <- function() { x <- 20 # outer's execution env inner <- function() { x <- 30 # inner's execution env cat("inner x:", x, "\n") } inner() cat("outer x:", x, "\n") } outer() cat("global x:", x, "\n")


  






Each function sees its own x. The inner function's x <- 30 doesn't affect the outer function or the global environment. This is name masking: the closest definition wins.



Rule 2: Functions vs Variables



R distinguishes between function and non-function lookups. If R needs a function (e.g., after name(), it skips non-function bindings:





  


    
# A variable named 'c' and the function c() can coexist
c <- 10
cat("c the variable:", c, "\n")

# R knows c() here must be the function
result <- c(1, 2, 3)
cat("c() the function:", result, "\n")

# Clean up
rm(c)


    


      

      

    


    


  






R finds that c is 10 in the global env, but when it sees c(1, 2, 3) it knows it needs a function, so it keeps searching until it finds the base R c() function.



Rule 3: A Fresh Start



Every function call creates a new execution environment. Variables from a previous call don't persist:





  


    
counter_broken <- function() {
  # This creates a NEW 'n' each time — it doesn't accumulate
  if (!exists("n")) {
    n <- 0
  }
  n <- n + 1
  cat("n =", n, "\n")
}

counter_broken()  # n = 1
counter_broken()  # n = 1 again — fresh environment each time!
counter_broken()  # n = 1 again


    


      

      

    


    


  






Each call starts fresh. To persist state across calls, you need closures (covered in the next tutorial).



Rule 4: Dynamic Lookup



R looks up values when the function runs, not when it's defined:





  


    
# Define a function that uses external variable 'multiplier'
scale <- function(x) {
  x * multiplier
}

multiplier <- 2
cat("scale(5) =", scale(5), "\n")  # 10

multiplier <- 10
cat("scale(5) =", scale(5), "\n")  # 50 — different result!


    


      

      

    


    


  






The value of multiplier is looked up at call time. This is powerful but can be a source of bugs — if multiplier changes unexpectedly, scale() changes too.



The Search Path



The search path is the ordered list of environments R checks when looking up a name:





  


    
# Show the search path
cat("Search path:\n")
path <- search()
for (i in seq_along(path)) {
  cat(sprintf("  %d. %s\n", i, path[i]))
}


    


      

      

    


    


  






When you call library(pkg), R inserts that package's environment into position 2 of the search path (just after the global environment). Later-loaded packages are searched first:





  


    
# Demonstrate search path order
cat("Before loading any package:\n")
cat("  Path length:", length(search()), "\n")

library(stats)  # Already loaded, but let's show the concept

cat("\nCurrent path:\n")
for (s in search()) {
  cat(" ", s, "\n")
}


    


      

      

    


    


  






Name Masking and Conflicts



When two packages export a function with the same name, the later-loaded package's version wins:





  


    
# Both base R and stats have 'filter'
# Demonstrate masking
filter_result <- stats::filter(1:10, rep(1/3, 3))
cat("stats::filter result:", round(filter_result[2:4], 2), "\n")

# If dplyr were loaded after stats, dplyr::filter would mask stats::filter
# That's why you see: "The following objects are masked from 'package:stats': filter, lag"


    


      

      

    


    


  






The :: Operator



Use package::function() to call a specific version explicitly:





  


    
# Always unambiguous — ignores the search path
cat("Base mean:", base::mean(1:10), "\n")
cat("Base sum:", base::sum(1:100), "\n")
cat("Stats median:", stats::median(1:10), "\n")

# This is best practice when:
# 1. Two packages have same-named functions
# 2. You want clarity about which package you're using
# 3. In package code (NAMESPACE imports are even better)


    


      

      

    


    


  






Finding Masked Functions





  


    
# conflicts() shows functions that are masked
masked <- conflicts()
if (length(masked) > 0) {
  cat("Masked functions:\n")
  for (fn in masked[1:min(5, length(masked))]) {
    cat(" ", fn, "\n")
  }
} else {
  cat("No masked functions\n")
}

# find() shows where a function lives
cat("\nWhere does 'mean' live?\n")
print(find("mean"))

cat("\nWhere does 'c' live?\n")
print(find("c"))


    


      

      

    


    


  






Lexical vs Dynamic Scoping



Most languages use lexical scoping. R mostly does too, but has a few dynamic scoping features:





  


    
# LEXICAL scoping: looks where function was DEFINED
x <- "global"

make_printer <- function() {
  x <- "local"
  function() cat("x =", x, "\n")
}

printer <- make_printer()
printer()  # prints "local" — lexical, looks at defining environment

# If R used DYNAMIC scoping, printer() would look at the
# CALLING environment and find x = "global"


    


      

      

    


    


  








  


    
# R's parent.frame() gives dynamic scoping behavior
# (rarely needed, but good to know)
dynamic_example <- function() {
  # parent.frame() = the caller's environment
  caller_env <- parent.frame()
  cat("Caller's secret:", get("secret", envir = caller_env), "\n")
}

wrapper <- function() {
  secret <- "found me!"
  dynamic_example()
}

wrapper()


    


      

      

    


    


  






parent.frame() looks at the calling environment (dynamic), while parent.env() looks at the defining/enclosing environment (lexical). This distinction is crucial for advanced R programming.



Practice Exercises



Exercise 1: Predict the Output





  


    
# Exercise: Without running this code, predict what each cat() prints.
# Then run it to check.

a <- 1

f <- function() {
  a <- 2
  g <- function() {
    a <- 3
    cat("g:", a, "\n")
  }
  g()
  cat("f:", a, "\n")
}

f()
cat("global:", a, "\n")

# Write your predictions as comments, then run:



    


      

      

    


    


  







Click to reveal solution

```r


  

    
a <- 1

f <- function() {
  a <- 2
  g <- function() {
    a <- 3
    cat("g:", a, "\n")       # 3 — inner a masks all others
  }
  g()
  cat("f:", a, "\n")         # 2 — g's a=3 was local to g
}

f()
cat("global:", a, "\n")       # 1 — f's a=2 was local to f

# Output:
# g: 3
# f: 2
# global: 1

    

      
      
    

    

  




**Explanation:** Each `a <-` assignment creates a local binding in that function's execution environment. Name masking means each function sees only its own `a`. No function modifies another's binding.





Exercise 2: Dynamic Lookup Trap





  


    
# Exercise: This code has a bug caused by dynamic lookup.
# Find it and fix it.

make_adder <- function(n) {
  function(x) x + n
}

n <- 100
add_5 <- make_adder(5)
cat("add_5(10) =", add_5(10), "\n")

# Expected: 15
# What do you actually get? Why? Fix it.

# Write your fix below:



    


      

      

    


    


  







Click to reveal solution

```r


  

    
# The code actually works correctly! Output is 15.
# Here's why: make_adder(5) captures n=5 in its closure.
# The global n=100 is irrelevant because lexical scoping
# looks at the DEFINING environment (make_adder's execution env
# where n=5), not the CALLING environment.

make_adder <- function(n) {
  force(n)  # Best practice: force evaluation of the argument
  function(x) x + n
}

n <- 100
add_5 <- make_adder(5)
cat("add_5(10) =", add_5(10), "\n")  # 15

# The force() call is a safeguard against lazy evaluation bugs.
# Without force(), if n were modified before the inner function
# is first called, you could get unexpected results in edge cases.

    

      
      
    

    

  




**Explanation:** Lexical scoping protects you here — the closure's `n` is the function argument, not the global `n`. Adding `force(n)` is defensive programming that ensures the argument is evaluated at definition time.





Summary







Concept
Meaning
Example






Lexical scoping
Lookup based on where code is written
Inner functions see outer variables




Name masking
Closest definition wins
Local x masks global x




Fresh start
Each call gets a new environment
Local vars don't persist




Dynamic lookup
Values resolved at call time
Changing y changes f()




Search path
search() shows env order
Global -> packages -> base




:: operator
Explicit package access
stats::filter()




Masking
Later package hides earlier
dplyr::filter masks stats::filter







Key insight: Lexical scoping means R's behavior is predictable from reading the code — you don't need to trace through the call stack to know which x a function uses.



FAQ



Why does R use lexical scoping instead of dynamic scoping?



Lexical scoping makes code easier to reason about. You can determine which variable a name refers to just by reading the source code. With dynamic scoping, the meaning of a variable depends on the runtime call stack, which is harder to predict and debug.



How do I avoid name masking bugs?



Three strategies: (1) Use unique, descriptive variable names. (2) Use package::function() when there might be conflicts. (3) Keep functions short so masking is obvious.



What's the difference between parent.env() and parent.frame()?



parent.env(env) returns the enclosing (lexical) parent — where the function was defined. parent.frame() returns the calling (dynamic) parent — the environment of the code that called the current function. Lexical scoping uses parent.env; dynamic scoping uses parent.frame.



What's Next?



Now that you understand how R looks up names, explore how functions capture their environment:



    


  1. R Closures — functions that remember their defining environment
    2. 


  2. R Conditions System — how R handles errors, warnings, and messages
    3. 


  3. R Namespaces — how packages use scoping to prevent conflicts
    4. 




        


        
      


      

        

        
© 2016- Selva Prabhakaran.
          This work is licensed under the Creative Commons License.