Package 'rlang'

Description

These functions are equivalent to base functions base::stop(), base::warning(), and base::message(). They signal a condition (an error, warning, or message respectively) and make it easy to supply condition metadata:

• Supply class to create a classed condition that can be caught or handled selectively, allowing for finer-grained error handling.

• Supply metadata with named ... arguments. This data is stored in the condition object and can be examined by handlers.

• Supply call to inform users about which function the error occurred in.

• Supply another condition as parent to create a chained condition.

Certain components of condition messages are formatted with unicode symbols and terminal colours by default. These aspects can be customised, see Customising condition messages.

Usage

abort(
  message = NULL,
  class = NULL,
  ...,
  call,
  body = NULL,
  footer = NULL,
  trace = NULL,
  parent = NULL,
  use_cli_format = NULL,
  .inherit = TRUE,
  .internal = FALSE,
  .file = NULL,
  .frame = caller_env(),
  .trace_bottom = NULL,
  .subclass = deprecated()
)

warn(
  message = NULL,
  class = NULL,
  ...,
  body = NULL,
  footer = NULL,
  parent = NULL,
  use_cli_format = NULL,
  .inherit = NULL,
  .frequency = c("always", "regularly", "once"),
  .frequency_id = NULL,
  .subclass = deprecated()
)

inform(
  message = NULL,
  class = NULL,
  ...,
  body = NULL,
  footer = NULL,
  parent = NULL,
  use_cli_format = NULL,
  .inherit = NULL,
  .file = NULL,
  .frequency = c("always", "regularly", "once"),
  .frequency_id = NULL,
  .subclass = deprecated()
)

signal(message = "", class, ..., .subclass = deprecated())

reset_warning_verbosity(id)

reset_message_verbosity(id)

Arguments

Details

• abort() throws subclassed errors, see "rlang_error".

• warn() temporarily set the warning.length global option to the maximum value (8170), unless that option has been changed from the default value. The default limit (1000 characters) is especially easy to hit when the message contains a lot of ANSI escapes, as created by the crayon or cli packages

Error prefix

As with base::stop(), errors thrown with abort() are prefixed with "Error: ". Calls and source references are included in the prefix, e.g. ⁠"Error in ⁠my_function()⁠ at myfile.R:1:2:"⁠. There are a few cosmetic differences:

• The call is stripped from its arguments to keep it simple. It is then formatted using the cli package if available.

• A line break between the prefix and the message when the former is too long. When a source location is included, a line break is always inserted.

If your throwing code is highly structured, you may have to explicitly inform abort() about the relevant user-facing call to include in the prefix. Internal helpers are rarely relevant to end users. See the call argument of abort().

Backtrace

abort() saves a backtrace in the trace component of the error condition. You can print a simplified backtrace of the last error by calling last_error() and a full backtrace with summary(last_error()). Learn how to control what is displayed when an error is thrown with rlang_backtrace_on_error.

Muffling and silencing conditions

Signalling a condition with inform() or warn() displays a message in the console. These messages can be muffled as usual with base::suppressMessages() or base::suppressWarnings().

inform() and warn() messages can also be silenced with the global options rlib_message_verbosity and rlib_warning_verbosity. These options take the values:

• "default": Verbose unless the .frequency argument is supplied.

• "verbose": Always verbose.

• "quiet": Always quiet.

When set to quiet, the message is not displayed and the condition is not signalled.

stdout and stderr

By default, abort() and inform() print to standard output in interactive sessions. This allows rlang to be in control of the appearance of messages in IDEs like RStudio.

There are two situations where messages are streamed to stderr:

• In non-interactive sessions, messages are streamed to standard error so that R scripts can easily filter them out from normal output by redirecting stderr.

• If a sink is active (either on output or on messages) messages are always streamd to stderr.

These exceptions ensure consistency of behaviour in interactive and non-interactive sessions, and when sinks are active.

See Also

• Including function calls in error messages

• Including contextual information with error chains

Examples

# These examples are guarded to avoid throwing errors
if (FALSE) {

# Signal an error with a message just like stop():
abort("The error message.")


# Unhandled errors are saved automatically by `abort()` and can be
# retrieved with `last_error()`. The error prints with a simplified
# backtrace:
f <- function() try(g())
g <- function() evalq(h())
h <- function() abort("Tilt.")
last_error()

# Use `summary()` to print the full backtrace and the condition fields:
summary(last_error())


# Give a class to the error:
abort("The error message", "mypkg_bad_error")

# This allows callers to handle the error selectively
tryCatch(
  mypkg_function(),
  mypkg_bad_error = function(err) {
    warn(conditionMessage(err)) # Demote the error to a warning
    NA                          # Return an alternative value
  }
)

# You can also specify metadata that will be stored in the condition:
abort("The error message.", "mypkg_bad_error", data = 1:10)

# This data can then be consulted by user handlers:
tryCatch(
  mypkg_function(),
  mypkg_bad_error = function(err) {
    # Compute an alternative return value with the data:
    recover_error(err$data)
  }
)


# If you call low-level APIs it may be a good idea to create a
# chained error with the low-level error wrapped in a more
# user-friendly error. Use `try_fetch()` to fetch errors of a given
# class and rethrow them with the `parent` argument of `abort()`:
file <- "http://foo.bar/baz"
try(
  try_fetch(
    download(file),
    error = function(err) {
      msg <- sprintf("Can't download `%s`", file)
      abort(msg, parent = err)
  })
)

}

Description

This is equivalent to base::match.arg() with a few differences:

• Partial matches trigger an error.

• Error messages are a bit more informative and obey the tidyverse standards.

arg_match() derives the possible values from the caller function.

arg_match0() is a bare-bones version if performance is at a premium. It requires a string as arg and explicit character values. For convenience, arg may also be a character vector containing every element of values, possibly permuted. In this case, the first element of arg is used.

Usage

arg_match(
  arg,
  values = NULL,
  ...,
  multiple = FALSE,
  error_arg = caller_arg(arg),
  error_call = caller_env()
)

arg_match0(arg, values, arg_nm = caller_arg(arg), error_call = caller_env())

Arguments

Value

The string supplied to arg.

See Also

check_required()

Examples

fn <- function(x = c("foo", "bar")) arg_match(x)
fn("bar")

# Throws an informative error for mismatches:
try(fn("b"))
try(fn("baz"))

# Use the bare-bones version with explicit values for speed:
arg_match0("bar", c("foo", "bar", "baz"))

# For convenience:
fn1 <- function(x = c("bar", "baz", "foo")) fn3(x)
fn2 <- function(x = c("baz", "bar", "foo")) fn3(x)
fn3 <- function(x) arg_match0(x, c("foo", "bar", "baz"))
fn1()
fn2("bar")
try(fn3("zoo"))

Description

Use ⁠@inheritParams rlang::args_error_context⁠ in your package to document arg and call arguments (or equivalently their prefixed versions error_arg and error_call).

• arg parameters should be formatted as argument (e.g. using cli's .arg specifier) and included in error messages. See also caller_arg().

• call parameters should be included in error conditions in a field named call. An easy way to do this is by passing a call argument to abort(). See also local_error_call().

Arguments

Description

• as_box() boxes its input only if it is not already a box. The class is also checked if supplied.

• as_box_if() boxes its input only if it not already a box, or if the predicate .p returns TRUE.

Usage

as_box(x, class = NULL)

as_box_if(.x, .p, .class = NULL, ...)

Arguments

Description

A data mask is an environment (or possibly multiple environments forming an ancestry) containing user-supplied objects. Objects in the mask have precedence over objects in the environment (i.e. they mask those objects). Many R functions evaluate quoted expressions in a data mask so these expressions can refer to objects within the user data.

These functions let you construct a tidy eval data mask manually. They are meant for developers of tidy eval interfaces rather than for end users.

Usage

as_data_mask(data)

as_data_pronoun(data)

new_data_mask(bottom, top = bottom)

Arguments

Value

A data mask that you can supply to eval_tidy().

Why build a data mask?

Most of the time you can just call eval_tidy() with a list or a data frame and the data mask will be constructed automatically. There are three main use cases for manual creation of data masks:

• When eval_tidy() is called with the same data in a tight loop. Because there is some overhead to creating tidy eval data masks, constructing the mask once and reusing it for subsequent evaluations may improve performance.

• When several expressions should be evaluated in the exact same environment because a quoted expression might create new objects that can be referred in other quoted expressions evaluated at a later time. One example of this is tibble::lst() where new columns can refer to previous ones.

• When your data mask requires special features. For instance the data frame columns in dplyr data masks are implemented with active bindings.

Building your own data mask

Unlike base::eval() which takes any kind of environments as data mask, eval_tidy() has specific requirements in order to support quosures. For this reason you can't supply bare environments.

There are two ways of constructing an rlang data mask manually:

• as_data_mask() transforms a list or data frame to a data mask. It automatically installs the data pronoun .data.

• new_data_mask() is a bare bones data mask constructor for environments. You can supply a bottom and a top environment in case your data mask comprises multiple environments (see section below).

  Unlike as_data_mask() it does not install the .data pronoun so you need to provide one yourself. You can provide a pronoun constructed with as_data_pronoun() or your own pronoun class.

  as_data_pronoun() will create a pronoun from a list, an environment, or an rlang data mask. In the latter case, the whole ancestry is looked up from the bottom to the top of the mask. Functions stored in the mask are bypassed by the pronoun.

Once you have built a data mask, simply pass it to eval_tidy() as the data argument. You can repeat this as many times as needed. Note that any objects created there (perhaps because of a call to ⁠<-⁠) will persist in subsequent evaluations.

Top and bottom of data mask

In some cases you'll need several levels in your data mask. One good reason is when you include functions in the mask. It's a good idea to keep data objects one level lower than function objects, so that the former cannot override the definitions of the latter (see examples).

In that case, set up all your environments and keep track of the bottom child and the top parent. You'll need to pass both to new_data_mask().

Note that the parent of the top environment is completely undetermined, you shouldn't expect it to remain the same at all times. This parent is replaced during evaluation by eval_tidy() to one of the following environments:

• The default environment passed as the env argument of eval_tidy().

• The environment of the current quosure being evaluated, if applicable.

Consequently, all masking data should be contained between the bottom and top environment of the data mask.

Examples

# Evaluating in a tidy evaluation environment enables all tidy
# features:
mask <- as_data_mask(mtcars)
eval_tidy(quo(letters), mask)

# You can install new pronouns in the mask:
mask$.pronoun <- as_data_pronoun(list(foo = "bar", baz = "bam"))
eval_tidy(quo(.pronoun$foo), mask)

# In some cases the data mask can leak to the user, for example if
# a function or formula is created in the data mask environment:
cyl <- "user variable from the context"
fn <- eval_tidy(quote(function() cyl), mask)
fn()

# If new objects are created in the mask, they persist in the
# subsequent calls:
eval_tidy(quote(new <- cyl + am), mask)
eval_tidy(quote(new * 2), mask)


# In some cases your data mask is a whole chain of environments
# rather than a single environment. You'll have to use
# `new_data_mask()` and let it know about the bottom of the mask
# (the last child of the environment chain) and the topmost parent.

# A common situation where you'll want a multiple-environment mask
# is when you include functions in your mask. In that case you'll
# put functions in the top environment and data in the bottom. This
# will prevent the data from overwriting the functions.
top <- new_environment(list(`+` = base::paste, c = base::paste))

# Let's add a middle environment just for sport:
middle <- env(top)

# And finally the bottom environment containing data:
bottom <- env(middle, a = "a", b = "b", c = "c")

# We can now create a mask by supplying the top and bottom
# environments:
mask <- new_data_mask(bottom, top = top)

# This data mask can be passed to eval_tidy() instead of a list or
# data frame:
eval_tidy(quote(a + b + c), data = mask)

# Note how the function `c()` and the object `c` are looked up
# properly because of the multi-level structure:
eval_tidy(quote(c(a, b, c)), data = mask)

# new_data_mask() does not create data pronouns, but
# data pronouns can be added manually:
mask$.fns <- as_data_pronoun(top)

# The `.data` pronoun should generally be created from the
# mask. This will ensure data is looked up throughout the whole
# ancestry. Only non-function objects are looked up from this
# pronoun:
mask$.data <- as_data_pronoun(mask)
mask$.data$c

# Now we can reference values with the pronouns:
eval_tidy(quote(c(.data$a, .data$b, .data$c)), data = mask)

Description

as_environment() coerces named vectors (including lists) to an environment. The names must be unique. If supplied an unnamed string, it returns the corresponding package environment (see pkg_env()).

Usage

as_environment(x, parent = NULL)

Arguments

Details

If x is an environment and parent is not NULL, the environment is duplicated before being set a new parent. The return value is therefore a different environment than x.

Examples

# Coerce a named vector to an environment:
env <- as_environment(mtcars)

# By default it gets the empty environment as parent:
identical(env_parent(env), empty_env())


# With strings it is a handy shortcut for pkg_env():
as_environment("base")
as_environment("rlang")

# With NULL it returns the empty environment:
as_environment(NULL)

Description

as_function() transforms a one-sided formula into a function. This powers the lambda syntax in packages like purrr.

Usage

as_function(
  x,
  env = global_env(),
  ...,
  arg = caller_arg(x),
  call = caller_env()
)

is_lambda(x)

Arguments

Examples

f <- as_function(~ .x + 1)
f(10)

g <- as_function(~ -1 * .)
g(4)

h <- as_function(~ .x - .y)
h(6, 3)

# Functions created from a formula have a special class:
is_lambda(f)
is_lambda(as_function(function() "foo"))

Description

as_label() transforms R objects into a short, human-readable description. You can use labels to:

• Display an object in a concise way, for example to labellise axes in a graphical plot.

• Give default names to columns in a data frame. In this case, labelling is the first step before name repair.

See also as_name() for transforming symbols back to a string. Unlike as_label(), as_name() is a well defined operation that guarantees the roundtrip symbol -> string -> symbol.

In general, if you don't know for sure what kind of object you're dealing with (a call, a symbol, an unquoted constant), use as_label() and make no assumption about the resulting string. If you know you have a symbol and need the name of the object it refers to, use as_name(). For instance, use as_label() with objects captured with enquo() and as_name() with symbols captured with ensym().

Usage

as_label(x)

Arguments

Transformation to string

• Quosures are squashed before being labelled.

• Symbols are transformed to string with as_string().

• Calls are abbreviated.

• Numbers are represented as such.

• Other constants are represented by their type, such as ⁠<dbl>⁠ or ⁠<data.frame>⁠.

See Also

as_name() for transforming symbols back to a string deterministically.

Examples

# as_label() is useful with quoted expressions:
as_label(expr(foo(bar)))

as_label(expr(foobar))

# It works with any R object. This is also useful for quoted
# arguments because the user might unquote constant objects:
as_label(1:3)

as_label(base::list)

Description

as_name() converts symbols to character strings. The conversion is deterministic. That is, the roundtrip symbol -> name -> symbol always gives the same result.

• Use as_name() when you need to transform a symbol to a string to refer to an object by its name.

• Use as_label() when you need to transform any kind of object to a string to represent that object with a short description.

Usage

as_name(x)

Arguments

Details

rlang::as_name() is the opposite of base::as.name(). If you're writing base R code, we recommend using base::as.symbol() which is an alias of as.name() that follows a more modern terminology (R types instead of S modes).

Value

A character vector of length 1.

See Also

as_label() for converting any object to a single string suitable as a label. as_string() for a lower-level version that doesn't unwrap quosures.

Examples

# Let's create some symbols:
foo <- quote(foo)
bar <- sym("bar")

# as_name() converts symbols to strings:
foo
as_name(foo)

typeof(bar)
typeof(as_name(bar))

# as_name() unwraps quosured symbols automatically:
as_name(quo(foo))

Description

as_string() converts symbols to character strings.

Usage

as_string(x)

Arguments

Value

A character vector of length 1.

Unicode tags

Unlike base::as.symbol() and base::as.name(), as_string() automatically transforms unicode tags such as "<U+5E78>" to the proper UTF-8 character. This is important on Windows because:

• R on Windows has no UTF-8 support, and uses native encoding instead.

• The native encodings do not cover all Unicode characters. For example, Western encodings do not support CKJ characters.

• When a lossy UTF-8 -> native transformation occurs, uncovered characters are transformed to an ASCII unicode tag like "<U+5E78>".

• Symbols are always encoded in native. This means that transforming the column names of a data frame to symbols might be a lossy operation.

• This operation is very common in the tidyverse because of data masking APIs like dplyr where data frames are transformed to environments. While the names of a data frame are stored as a character vector, the bindings of environments are stored as symbols.

Because it reencodes the ASCII unicode tags to their UTF-8 representation, the string -> symbol -> string roundtrip is more stable with as_string().

See Also

as_name() for a higher-level variant of as_string() that automatically unwraps quosures.

Examples

# Let's create some symbols:
foo <- quote(foo)
bar <- sym("bar")

# as_string() converts symbols to strings:
foo
as_string(foo)

typeof(bar)
typeof(as_string(bar))

Description

These predicates check for a given type but only return TRUE for bare R objects. Bare objects have no class attributes. For example, a data frame is a list, but not a bare list.

Usage

is_bare_list(x, n = NULL)

is_bare_atomic(x, n = NULL)

is_bare_vector(x, n = NULL)

is_bare_double(x, n = NULL)

is_bare_complex(x, n = NULL)

is_bare_integer(x, n = NULL)

is_bare_numeric(x, n = NULL)

is_bare_character(x, n = NULL)

is_bare_logical(x, n = NULL)

is_bare_raw(x, n = NULL)

is_bare_string(x, n = NULL)

is_bare_bytes(x, n = NULL)

Arguments

Details

• The predicates for vectors include the n argument for pattern-matching on the vector length.

• Like is_atomic() and unlike base R is.atomic(), is_bare_atomic() does not return TRUE for NULL.

• Unlike base R is.numeric(), is_bare_double() only returns TRUE for floating point numbers.

See Also

type-predicates, scalar-type-predicates

Description

new_box() is similar to base::I() but it protects a value by wrapping it in a scalar list rather than by adding an attribute. unbox() retrieves the boxed value. is_box() tests whether an object is boxed with optional class. as_box() ensures that a value is wrapped in a box. as_box_if() does the same but only if the value matches a predicate.

Usage

new_box(.x, class = NULL, ...)

is_box(x, class = NULL)

unbox(box)

Arguments

Examples

boxed <- new_box(letters, "mybox")
is_box(boxed)
is_box(boxed, "mybox")
is_box(boxed, "otherbox")

unbox(boxed)

# as_box() avoids double-boxing:
boxed2 <- as_box(boxed, "mybox")
boxed2
unbox(boxed2)

# Compare to:
boxed_boxed <- new_box(boxed, "mybox")
boxed_boxed
unbox(unbox(boxed_boxed))

# Use `as_box_if()` with a predicate if you need to ensure a box
# only for a subset of values:
as_box_if(NULL, is_null, "null_box")
as_box_if("foo", is_null, "null_box")

Description

Construct, manipulate and display vectors of byte sizes. These are numeric vectors, so you can compare them numerically, but they can also be compared to human readable values such as '10MB'.

• parse_bytes() takes a character vector of human-readable bytes and returns a structured bytes vector.

• as_bytes() is a generic conversion function for objects representing bytes.

Note: A bytes() constructor will be exported soon.

Usage

as_bytes(x)

parse_bytes(x)

Arguments

Details

These memory sizes are always assumed to be base 1000, rather than 1024.

Examples

parse_bytes("1")
parse_bytes("1K")
parse_bytes("1Kb")
parse_bytes("1KiB")
parse_bytes("1MB")

parse_bytes("1KB") < "1MB"

sum(parse_bytes(c("1MB", "5MB", "500KB")))

Description

Extract arguments from a call

Usage

call_args(call)

call_args_names(call)

Arguments

Value

A named list of arguments.

See Also

fn_fmls() and fn_fmls_names()

Examples

call <- quote(f(a, b))

# Subsetting a call returns the arguments converted to a language
# object:
call[-1]

# On the other hand, call_args() returns a regular list that is
# often easier to work with:
str(call_args(call))

# When the arguments are unnamed, a vector of empty strings is
# supplied (rather than NULL):
call_args_names(call)

Description

This function is a wrapper around base::match.call(). It returns its own function call.

Usage

call_inspect(...)

Arguments

Examples

# When you call it directly, it simply returns what you typed
call_inspect(foo(bar), "" %>% identity())

# Pass `call_inspect` to functionals like `lapply()` or `map()` to
# inspect the calls they create around the supplied function
lapply(1:3, call_inspect)

Description

call_match() is like match.call() with these differences:

• It supports matching missing argument to their defaults in the function definition.

• It requires you to be a little more specific in some cases. Either all arguments are inferred from the call stack or none of them are (see the Inference section).

Usage

call_match(
  call = NULL,
  fn = NULL,
  ...,
  defaults = FALSE,
  dots_env = NULL,
  dots_expand = TRUE
)

Arguments

Inference from the call stack

When call is not supplied, it is inferred from the call stack along with fn and dots_env.

• call and fn are inferred from the calling environment: sys.call(sys.parent()) and sys.function(sys.parent()).

• dots_env is inferred from the caller of the calling environment: caller_env(2).

If call is supplied, then you must supply fn as well. Also consider supplying dots_env as it is set to the empty environment when not inferred.

Examples

# `call_match()` supports matching missing arguments to their
# defaults
fn <- function(x = "default") fn
call_match(quote(fn()), fn)
call_match(quote(fn()), fn, defaults = TRUE)

Description

If you are working with a user-supplied call, make sure the arguments are standardised with call_match() before modifying the call.

Usage

call_modify(
  .call,
  ...,
  .homonyms = c("keep", "first", "last", "error"),
  .standardise = NULL,
  .env = caller_env()
)

Arguments

Value

A quosure if .call is a quosure, a call otherwise.

Examples

call <- quote(mean(x, na.rm = TRUE))

# Modify an existing argument
call_modify(call, na.rm = FALSE)
call_modify(call, x = quote(y))

# Remove an argument
call_modify(call, na.rm = zap())

# Add a new argument
call_modify(call, trim = 0.1)

# Add an explicit missing argument:
call_modify(call, na.rm = )

# Supply a list of new arguments with `!!!`
newargs <- list(na.rm = NULL, trim = 0.1)
call <- call_modify(call, !!!newargs)
call

# Remove multiple arguments by splicing zaps:
newargs <- rep_named(c("na.rm", "trim"), list(zap()))
call <- call_modify(call, !!!newargs)
call


# Modify the `...` arguments as if it were a named argument:
call <- call_modify(call, ... = )
call

call <- call_modify(call, ... = zap())
call


# When you're working with a user-supplied call, standardise it
# beforehand in case it includes unmatched arguments:
user_call <- quote(matrix(x, nc = 3))
call_modify(user_call, ncol = 1)

# `call_match()` applies R's argument matching rules. Matching
# ensures you're modifying the intended argument.
user_call <- call_match(user_call, matrix)
user_call
call_modify(user_call, ncol = 1)


# By default, arguments with the same name are kept. This has
# subtle implications, for instance you can move an argument to
# last position by removing it and remapping it:
call <- quote(foo(bar = , baz))
call_modify(call, bar = NULL, bar = missing_arg())

# You can also choose to keep only the first or last homonym
# arguments:
args <-  list(bar = NULL, bar = missing_arg())
call_modify(call, !!!args, .homonyms = "first")
call_modify(call, !!!args, .homonyms = "last")

Description

call_name() and call_ns() extract the function name or namespace of simple calls as a string. They return NULL for complex calls.

• Simple calls: foo(), bar::foo().

• Complex calls: foo()(), bar::foo, foo$bar(), (function() NULL)().

The is_call_simple() predicate helps you determine whether a call is simple. There are two invariants you can count on:

1. If is_call_simple(x) returns TRUE, call_name(x) returns a string. Otherwise it returns NULL.

2. If is_call_simple(x, ns = TRUE) returns TRUE, call_ns() returns a string. Otherwise it returns NULL.

Usage

call_name(call)

call_ns(call)

is_call_simple(x, ns = NULL)

Arguments

Value

The function name or namespace as a string, or NULL if the call is not named or namespaced.

Examples

# Is the function named?
is_call_simple(quote(foo()))
is_call_simple(quote(foo[[1]]()))

# Is the function namespaced?
is_call_simple(quote(list()), ns = TRUE)
is_call_simple(quote(base::list()), ns = TRUE)

# Extract the function name from quoted calls:
call_name(quote(foo(bar)))
call_name(quo(foo(bar)))

# Namespaced calls are correctly handled:
call_name(quote(base::matrix(baz)))

# Anonymous and subsetted functions return NULL:
call_name(quote(foo$bar()))
call_name(quote(foo[[bar]]()))
call_name(quote(foo()()))

# Extract namespace of a call with call_ns():
call_ns(quote(base::bar()))

# If not namespaced, call_ns() returns NULL:
call_ns(quote(bar()))

Description

Quoted function calls are one of the two types of symbolic objects in R. They represent the action of calling a function, possibly with arguments. There are two ways of creating a quoted call:

• By quoting it. Quoting prevents functions from being called. Instead, you get the description of the function call as an R object. That is, a quoted function call.

• By constructing it with base::call(), base::as.call(), or call2(). In this case, you pass the call elements (the function to call and the arguments to call it with) separately.

See section below for the difference between call2() and the base constructors.

Usage

call2(.fn, ..., .ns = NULL)

Arguments

Difference with base constructors

call2() is more flexible than base::call():

• The function to call can be a string or a callable object: a symbol, another call (e.g. a $ or [[ call), or a function to inline. base::call() only supports strings and you need to use base::as.call() to construct a call with a callable object.

  call2(list, 1, 2)
  
  as.call(list(list, 1, 2))
  

• The .ns argument is convenient for creating namespaced calls.

  call2("list", 1, 2, .ns = "base")
  
  # Equivalent to
  ns_call <- call("::", as.symbol("list"), as.symbol("base"))
  as.call(list(ns_call, 1, 2))
  

• call2() has dynamic dots support. You can splice lists of arguments with ⁠!!!⁠ or unquote an argument name with glue syntax.

  args <- list(na.rm = TRUE, trim = 0)
  
  call2("mean", 1:10, !!!args)
  
  # Equivalent to
  as.call(c(list(as.symbol("mean"), 1:10), args))
  

Caveats of inlining objects in calls

call2() makes it possible to inline objects in calls, both in function and argument positions. Inlining an object or a function has the advantage that the correct object is used in all environments. If all components of the code are inlined, you can even evaluate in the empty environment.

However inlining also has drawbacks. It can cause issues with NSE functions that expect symbolic arguments. The objects may also leak in representations of the call stack, such as traceback().

See Also

call_modify

Examples

# fn can either be a string, a symbol or a call
call2("f", a = 1)
call2(quote(f), a = 1)
call2(quote(f()), a = 1)

#' Can supply arguments individually or in a list
call2(quote(f), a = 1, b = 2)
call2(quote(f), !!!list(a = 1, b = 2))

# Creating namespaced calls is easy:
call2("fun", arg = quote(baz), .ns = "mypkg")

# Empty arguments are preserved:
call2("[", quote(x), , drop = )

Description

caller_arg() is a variant of substitute() or ensym() for arguments that reference other arguments. Unlike substitute() which returns an expression, caller_arg() formats the expression as a single line string which can be included in error messages.

• When included in an error message, the resulting label should generally be formatted as argument, for instance using the .arg in the cli package.

• Use ⁠@inheritParams rlang::args_error_context⁠ to document an arg or error_arg argument that takes error_arg() as default.

Arguments

Examples

arg_checker <- function(x, arg = caller_arg(x), call = caller_env()) {
  cli::cli_abort("{.arg {arg}} must be a thingy.", arg = arg, call = call)
}

my_function <- function(my_arg) {
  arg_checker(my_arg)
}

try(my_function(NULL))

Description

This is a small wrapper around tryCatch() that captures any condition signalled while evaluating its argument. It is useful for situations where you expect a specific condition to be signalled, for debugging, and for unit testing.

Usage

catch_cnd(expr, classes = "condition")

Arguments

Value

A condition if any was signalled, NULL otherwise.

Examples

catch_cnd(10)
catch_cnd(abort("an error"))
catch_cnd(signal("my_condition", message = "a condition"))

Description

... can be inserted in a function signature to force users to fully name the details arguments. In this case, supplying data in ... is almost always a programming error. This function checks that ... is empty and fails otherwise.

Usage

check_dots_empty(
  env = caller_env(),
  error = NULL,
  call = caller_env(),
  action = abort
)

Arguments

Details

In packages, document ... with this standard tag:

 @inheritParams rlang::args_dots_empty

Examples

f <- function(x, ..., foofy = 8) {
  check_dots_empty()
  x + foofy
}

# This fails because `foofy` can't be matched positionally
try(f(1, 4))

# This fails because `foofy` can't be matched partially by name
try(f(1, foof = 4))

# Thanks to `...`, it must be matched exactly
f(1, foofy = 4)

Description

In functions like paste(), named arguments in ... are often a sign of misspelled argument names. Call check_dots_unnamed() to fail with an error when named arguments are detected.

Usage

check_dots_unnamed(
  env = caller_env(),
  error = NULL,
  call = caller_env(),
  action = abort
)

Arguments

Examples

f <- function(..., foofy = 8) {
  check_dots_unnamed()
  c(...)
}

f(1, 2, 3, foofy = 4)

try(f(1, 2, 3, foof = 4))

Description

When ... arguments are passed to methods, it is assumed there method will match and use these arguments. If this isn't the case, this often indicates a programming error. Call check_dots_used() to fail with an error when unused arguments are detected.

Usage

check_dots_used(
  env = caller_env(),
  call = caller_env(),
  error = NULL,
  action = deprecated()
)

Arguments

Details

In packages, document ... with this standard tag:

 @inheritParams rlang::args_dots_used

check_dots_used() implicitly calls on.exit() to check that all elements of ... have been used when the function exits. If you use on.exit() elsewhere in your function, make sure to use add = TRUE so that you don't override the handler set up by check_dots_used().

Examples

f <- function(...) {
  check_dots_used()
  g(...)
}

g <- function(x, y, ...) {
  x + y
}
f(x = 1, y = 2)

try(f(x = 1, y = 2, z = 3))

try(f(x = 1, y = 2, 3, 4, 5))

# Use an `error` handler to handle the error differently.
# For instance to demote the error to a warning:
fn <- function(...) {
  check_dots_empty(
    error = function(cnd) {
      warning(cnd)
    }
  )
  "out"
}
fn()

Description

check_exclusive() checks that only one argument is supplied out of a set of mutually exclusive arguments. An informative error is thrown if multiple arguments are supplied.

Usage

check_exclusive(..., .require = TRUE, .frame = caller_env(), .call = .frame)

Arguments

Value

The supplied argument name as a string. If .require is FALSE and no argument is supplied, the empty string "" is returned.

Examples

f <- function(x, y) {
  switch(
    check_exclusive(x, y),
    x = message("`x` was supplied."),
    y = message("`y` was supplied.")
  )
}

# Supplying zero or multiple arguments is forbidden
try(f())
try(f(NULL, NULL))

# The user must supply one of the mutually exclusive arguments
f(NULL)
f(y = NULL)


# With `.require` you can allow zero arguments
f <- function(x, y) {
  switch(
    check_exclusive(x, y, .require = FALSE),
    x = message("`x` was supplied."),
    y = message("`y` was supplied."),
    message("No arguments were supplied")
  )
}
f()

Description

Throws an error if x is missing.

Usage

check_required(x, arg = caller_arg(x), call = caller_env())

Arguments

See Also

arg_match()

Examples

f <- function(x)  {
  check_required(x)
}

# Fails because `x` is not supplied
try(f())

# Succeeds
f(NULL)

Description

Like any R objects, errors captured with catchers like tryCatch() have a class() which you can test with inherits(). However, with chained errors, the class of a captured error might be different than the error that was originally signalled. Use cnd_inherits() to detect whether an error or any of its parent inherits from a class.

Whereas inherits() tells you whether an object is a particular kind of error, cnd_inherits() answers the question whether an object is a particular kind of error or has been caused by such an error.

Some chained conditions carry parents that are not inherited. See the .inherit argument of abort(), warn(), and inform().

Usage

cnd_inherits(cnd, class)

Arguments

Capture an error with cnd_inherits()

Error catchers like tryCatch() and try_fetch() can only match the class of a condition, not the class of its parents. To match a class across the ancestry of an error, you'll need a bit of craftiness.

Ancestry matching can't be done with tryCatch() at all so you'll need to switch to withCallingHandlers(). Alternatively, you can use the experimental rlang function try_fetch() which is able to perform the roles of both tryCatch() and withCallingHandlers().

withCallingHandlers()

Unlike tryCatch(), withCallingHandlers() does not capture an error. If you don't explicitly jump with an error or a value throw, nothing happens.

Since we don't want to throw an error, we'll throw a value using callCC():

f <- function() {
  parent <- error_cnd("bar", message = "Bar")
  abort("Foo", parent = parent)
}

cnd <- callCC(function(throw) {
  withCallingHandlers(
    f(),
    error = function(x) if (cnd_inherits(x, "bar")) throw(x)
  )
})

class(cnd)
#> [1] "rlang_error" "error"       "condition"
class(cnd$parent)
#> [1] "bar"         "rlang_error" "error"       "condition"

try_fetch()

This pattern is easier with try_fetch(). Like withCallingHandlers(), it doesn't capture a matching error right away. Instead, it captures it only if the handler doesn't return a zap() value.

cnd <- try_fetch(
  f(),
  error = function(x) if (cnd_inherits(x, "bar")) x else zap()
)

class(cnd)
#> [1] "rlang_error" "error"       "condition"
class(cnd$parent)
#> [1] "bar"         "rlang_error" "error"       "condition"

Note that try_fetch() uses cnd_inherits() internally. This makes it very easy to match a parent condition:

cnd <- try_fetch(
  f(),
  bar = function(x) x
)

# This is the parent
class(cnd)
#> [1] "bar"         "rlang_error" "error"       "condition"

Description

cnd_message() assembles an error message from three generics:

• cnd_header()

• cnd_body()

• cnd_footer()

Methods for these generics must return a character vector. The elements are combined into a single string with a newline separator. Bullets syntax is supported, either through rlang (see format_error_bullets()), or through cli if the condition has use_cli_format set to TRUE.

The default method for the error header returns the message field of the condition object. The default methods for the body and footer return the the body and footer fields if any, or empty character vectors otherwise.

cnd_message() is automatically called by the conditionMessage() for rlang errors, warnings, and messages. Error classes created with abort() only need to implement header, body or footer methods. This provides a lot of flexibility for hierarchies of error classes, for instance you could inherit the body of an error message from a parent class while overriding the header and footer.

Usage

cnd_message(cnd, ..., inherit = TRUE, prefix = FALSE)

cnd_header(cnd, ...)

cnd_body(cnd, ...)

cnd_footer(cnd, ...)

Arguments

Overriding header, body, and footer methods

Sometimes the contents of an error message depends on the state of your checking routine. In that case, it can be tricky to lazily generate error messages with cnd_header(), cnd_body(), and cnd_footer(): you have the choice between overspecifying your error class hierarchies with one class per state, or replicating the type-checking control flow within the cnd_body() method. None of these options are ideal.

A better option is to define header, body, or footer fields in your condition object. These can be a static string, a lambda-formula, or a function with the same signature as cnd_header(), cnd_body(), or cnd_footer(). These fields override the message generics and make it easy to generate an error message tailored to the state in which the error was constructed.

Description

cnd_signal() takes a condition as argument and emits the corresponding signal. The type of signal depends on the class of the condition:

• A message is signalled if the condition inherits from "message". This is equivalent to signalling with inform() or base::message().

• A warning is signalled if the condition inherits from "warning". This is equivalent to signalling with warn() or base::warning().

• An error is signalled if the condition inherits from "error". This is equivalent to signalling with abort() or base::stop().

• An interrupt is signalled if the condition inherits from "interrupt". This is equivalent to signalling with interrupt().

Usage

cnd_signal(cnd, ...)

Arguments

See Also

• cnd_type() to determine the type of a condition.

• abort(), warn() and inform() for creating and signalling structured R conditions in one go.

• try_fetch() for establishing condition handlers for particular condition classes.

Examples

# The type of signal depends on the class. If the condition
# inherits from "warning", a warning is issued:
cnd <- warning_cnd("my_warning_class", message = "This is a warning")
cnd_signal(cnd)

# If it inherits from "error", an error is raised:
cnd <- error_cnd("my_error_class", message = "This is an error")
try(cnd_signal(cnd))

Description

A value boxed with done() signals to its caller that it should stop iterating. Use it to shortcircuit a loop.

Usage

done(x)

is_done_box(x, empty = NULL)

Arguments

Value

A boxed value.

Examples

done(3)

x <- done(3)
is_done_box(x)

Description

The .data and .env pronouns make it explicit where to find objects when programming with data-masked functions.

m <- 10
mtcars %>% mutate(disp = .data$disp * .env$m)

• .data retrieves data-variables from the data frame.

• .env retrieves env-variables from the environment.

Because the lookup is explicit, there is no ambiguity between both kinds of variables. Compare:

disp <- 10
mtcars %>% mutate(disp = .data$disp * .env$disp)
mtcars %>% mutate(disp = disp * disp)

Note that .data is only a pronoun, it is not a real data frame. This means that you can't take its names or map a function over the contents of .data. Similarly, .env is not an actual R environment. For instance, it doesn't have a parent and the subsetting operators behave differently.

.data versus the magrittr pronoun .

In a magrittr pipeline, .data is not necessarily interchangeable with the magrittr pronoun .. With grouped data frames in particular, .data represents the current group slice whereas the pronoun . represents the whole data frame. Always prefer using .data in data-masked context.

Where does .data live?

The .data pronoun is automatically created for you by data-masking functions using the tidy eval framework. You don't need to import rlang::.data or use library(rlang) to work with this pronoun.

However, the .data object exported from rlang is useful to import in your package namespace to avoid a ⁠R CMD check⁠ note when referring to objects from the data mask. R does not have any way of knowing about the presence or absence of .data in a particular scope so you need to import it explicitly or equivalently declare it with utils::globalVariables(".data").

Note that rlang::.data is a "fake" pronoun. Do not refer to rlang::.data with the ⁠rlang::⁠ qualifier in data masking code. Use the unqualified .data symbol that is automatically put in scope by data-masking functions.

Description

The base ... syntax supports:

• Forwarding arguments from function to function, matching them along the way to arguments.

• Collecting arguments inside data structures, e.g. with c() or list().

Dynamic dots offer a few additional features, injection in particular:

1. You can splice arguments saved in a list with the splice operator !!!.

2. You can inject names with glue syntax on the left-hand side of ⁠:=⁠.

3. Trailing commas are ignored, making it easier to copy and paste lines of arguments.

Add dynamic dots support in your functions

If your function takes dots, adding support for dynamic features is as easy as collecting the dots with list2() instead of list(). See also dots_list(), which offers more control over the collection.

In general, passing ... to a function that supports dynamic dots causes your function to inherit the dynamic behaviour.

In packages, document dynamic dots with this standard tag:

 @param ... <[`dynamic-dots`][rlang::dyn-dots]> What these dots do.

Examples

f <- function(...) {
  out <- list2(...)
  rev(out)
}

# Trailing commas are ignored
f(this = "that", )

# Splice lists of arguments with `!!!`
x <- list(alpha = "first", omega = "last")
f(!!!x)

# Inject a name using glue syntax
if (is_installed("glue")) {
  nm <- "key"
  f("{nm}" := "value")
  f("prefix_{nm}" := "value")
}

Description

The embrace operator ⁠{{⁠ is used to create functions that call other data-masking functions. It transports a data-masked argument (an argument that can refer to columns of a data frame) from one function to another.

my_mean <- function(data, var) {
  dplyr::summarise(data, mean = mean({{ var }}))
}

Under the hood

⁠{{⁠ combines enquo() and !! in one step. The snippet above is equivalent to:

my_mean <- function(data, var) {
  var <- enquo(var)
  dplyr::summarise(data, mean = mean(!!var))
}

See Also

• What is data-masking and why do I need {{?

• Data mask programming patterns

Description

The empty environment is the only one that does not have a parent. It is always used as the tail of an environment chain such as the search path (see search_envs()).

Usage

empty_env()

Examples

# Create environments with nothing in scope:
child_env(empty_env())

Description

englue() creates a string with the glue operators ⁠{⁠ and ⁠{{⁠. These operators are normally used to inject names within dynamic dots. englue() makes them available anywhere within a function.

englue() must be used inside a function. englue("{{ var }}") defuses the argument var and transforms it to a string using the default name operation.

Usage

englue(x, env = caller_env(), error_call = current_env(), error_arg = "x")

Arguments

Details

englue("{{ var }}") is equivalent to as_label(enquo(var)). It defuses arg and transforms the expression to a string with as_label().

In dynamic dots, using only ⁠{⁠ is allowed. In englue() you must use ⁠{{⁠ at least once. Use glue::glue() for simple interpolation.

Before using englue() in a package, first ensure that glue is installed by adding it to your ⁠Imports:⁠ section.

usethis::use_package("glue", "Imports")

Wrapping englue()

You can provide englue semantics to a user provided string by supplying env. In this example we create a variant of englue() that supports a special .qux pronoun by:

• Creating an environment masked_env that inherits from the user env, the one where their data lives.

• Overriding the error_arg and error_call arguments to point to our own argument name and call environment. This pattern is slightly different from usual error context passing because englue() is a backend function that uses its own error context by default (and not a checking function that uses your error context by default).

my_englue <- function(text) {
  masked_env <- env(caller_env(), .qux = "QUX")

  englue(
    text,
    env = masked_env,
    error_arg = "text",
    error_call = current_env()
  )
}

# Users can then use your wrapper as they would use `englue()`:
fn <- function(x) {
  foo <- "FOO"
  my_englue("{{ x }}_{.qux}_{foo}")
}

fn(bar)
#> [1] "bar_QUX_FOO"

If you are creating a low level package on top of englue(), you should also consider exposing env, error_arg and error_call in your englue() wrapper so users can wrap your wrapper.

See Also

• Injecting with !!, !!!, and glue syntax

Examples

g <- function(var) englue("{{ var }}")
g(cyl)
g(1 + 1)
g(!!letters)

# These are equivalent to
as_label(quote(cyl))
as_label(quote(1 + 1))
as_label(letters)

Description

enquo() and enquos() defuse function arguments. A defused expression can be examined, modified, and injected into other expressions.

Defusing function arguments is useful for:

• Creating data-masking functions.

• Interfacing with another data-masking function using the defuse-and-inject pattern.

These are advanced tools. Make sure to first learn about the embrace operator {{ in Data mask programming patterns. ⁠{{⁠ is easier to work with less theory, and it is sufficient in most applications.

Usage

enquo(arg)

enquos(
  ...,
  .named = FALSE,
  .ignore_empty = c("trailing", "none", "all"),
  .ignore_null = c("none", "all"),
  .unquote_names = TRUE,
  .homonyms = c("keep", "first", "last", "error"),
  .check_assign = FALSE
)

Arguments

Value

enquo() returns a quosure and enquos() returns a list of quosures.

Implicit injection

Arguments defused with enquo() and enquos() automatically gain injection support.

my_mean <- function(data, var) {
  var <- enquo(var)
  dplyr::summarise(data, mean(!!var))
}

# Can now use `!!` and `{{`
my_mean(mtcars, !!sym("cyl"))

See enquo0() and enquos0() for variants that don't enable injection.

See Also

• Defusing R expressions for an overview.

• expr() to defuse your own local expressions.

• Advanced defusal operators.

• base::eval() and eval_bare() for resuming evaluation of a defused expression.

Examples

# `enquo()` defuses the expression supplied by your user
f <- function(arg) {
  enquo(arg)
}

f(1 + 1)

# `enquos()` works with arguments and dots. It returns a list of
# expressions
f <- function(...) {
  enquos(...)
}

f(1 + 1, 2 * 10)


# `enquo()` and `enquos()` enable _injection_ and _embracing_ for
# your users
g <- function(arg) {
  f({{ arg }} * 2)
}
g(100)

column <- sym("cyl")
g(!!column)

Description

These functions create new environments.

• env() creates a child of the current environment by default and takes a variable number of named objects to populate it.

• new_environment() creates a child of the empty environment by default and takes a named list of objects to populate it.

Usage

env(...)

new_environment(data = list(), parent = empty_env())

Arguments

Environments as objects

Environments are containers of uniquely named objects. Their most common use is to provide a scope for the evaluation of R expressions. Not all languages have first class environments, i.e. can manipulate scope as regular objects. Reification of scope is one of the most powerful features of R as it allows you to change what objects a function or expression sees when it is evaluated.

Environments also constitute a data structure in their own right. They are a collection of uniquely named objects, subsettable by name and modifiable by reference. This latter property (see section on reference semantics) is especially useful for creating mutable OO systems (cf the R6 package and the ggproto system for extending ggplot2).

Inheritance

All R environments (except the empty environment) are defined with a parent environment. An environment and its grandparents thus form a linear hierarchy that is the basis for lexical scoping in R. When R evaluates an expression, it looks up symbols in a given environment. If it cannot find these symbols there, it keeps looking them up in parent environments. This way, objects defined in child environments have precedence over objects defined in parent environments.

The ability of overriding specific definitions is used in the tidyeval framework to create powerful domain-specific grammars. A common use of masking is to put data frame columns in scope. See for example as_data_mask().

Reference semantics

Unlike regular objects such as vectors, environments are an uncopyable object type. This means that if you have multiple references to a given environment (by assigning the environment to another symbol with ⁠<-⁠ or passing the environment as argument to a function), modifying the bindings of one of those references changes all other references as well.

See Also

env_has(), env_bind().

Examples

# env() creates a new environment that inherits from the current
# environment by default
env <- env(a = 1, b = "foo")
env$b
identical(env_parent(env), current_env())

# Supply one unnamed argument to inherit from another environment:
env <- env(base_env(), a = 1, b = "foo")
identical(env_parent(env), base_env())


# Both env() and child_env() support tidy dots features:
objs <- list(b = "foo", c = "bar")
env <- env(a = 1, !!! objs)
env$c

# You can also unquote names with the definition operator `:=`
var <- "a"
env <- env(!!var := "A")
env$a


# Use new_environment() to create containers with the empty
# environment as parent:
env <- new_environment()
env_parent(env)

# Like other new_ constructors, it takes an object rather than dots:
new_environment(list(a = "foo", b = "bar"))

Description

These functions create bindings in an environment. The bindings are supplied through ... as pairs of names and values or expressions. env_bind() is equivalent to evaluating a ⁠<-⁠ expression within the given environment. This function should take care of the majority of use cases but the other variants can be useful for specific problems.

• env_bind() takes named values which are bound in .env. env_bind() is equivalent to base::assign().

• env_bind_active() takes named functions and creates active bindings in .env. This is equivalent to base::makeActiveBinding(). An active binding executes a function each time it is evaluated. The arguments are passed to as_function() so you can supply formulas instead of functions.

  Remember that functions are scoped in their own environment. These functions can thus refer to symbols from this enclosure that are not actually in scope in the dynamic environment where the active bindings are invoked. This allows creative solutions to difficult problems (see the implementations of dplyr::do() methods for an example).

• env_bind_lazy() takes named expressions. This is equivalent to base::delayedAssign(). The arguments are captured with exprs() (and thus support call-splicing and unquoting) and assigned to symbols in .env. These expressions are not evaluated immediately but lazily. Once a symbol is evaluated, the corresponding expression is evaluated in turn and its value is bound to the symbol (the expressions are thus evaluated only once, if at all).

• ⁠%<~%⁠ is a shortcut for env_bind_lazy(). It works like ⁠<-⁠ but the RHS is evaluated lazily.

Usage

env_bind(.env, ...)

env_bind_lazy(.env, ..., .eval_env = caller_env())

env_bind_active(.env, ...)

lhs %<~% rhs

Arguments

Value

The input object .env, with its associated environment modified in place, invisibly.

Side effects

Since environments have reference semantics (see relevant section in env() documentation), modifying the bindings of an environment produces effects in all other references to that environment. In other words, env_bind() and its variants have side effects.

Like other side-effecty functions like par() and options(), env_bind() and variants return the old values invisibly.

See Also

env_poke() for binding a single element.

Examples

# env_bind() is a programmatic way of assigning values to symbols
# with `<-`. We can add bindings in the current environment:
env_bind(current_env(), foo = "bar")
foo

# Or modify those bindings:
bar <- "bar"
env_bind(current_env(), bar = "BAR")
bar

# You can remove bindings by supplying zap sentinels:
env_bind(current_env(), foo = zap())
try(foo)

# Unquote-splice a named list of zaps
zaps <- rep_named(c("foo", "bar"), list(zap()))
env_bind(current_env(), !!!zaps)
try(bar)

# It is most useful to change other environments:
my_env <- env()
env_bind(my_env, foo = "foo")
my_env$foo

# A useful feature is to splice lists of named values:
vals <- list(a = 10, b = 20)
env_bind(my_env, !!!vals, c = 30)
my_env$b
my_env$c

# You can also unquote a variable referring to a symbol or a string
# as binding name:
var <- "baz"
env_bind(my_env, !!var := "BAZ")
my_env$baz


# The old values of the bindings are returned invisibly:
old <- env_bind(my_env, a = 1, b = 2, baz = "baz")
old

# You can restore the original environment state by supplying the
# old values back:
env_bind(my_env, !!!old)

# env_bind_lazy() assigns expressions lazily:
env <- env()
env_bind_lazy(env, name = { cat("forced!\n"); "value" })

# Referring to the binding will cause evaluation:
env$name

# But only once, subsequent references yield the final value:
env$name

# You can unquote expressions:
expr <- quote(message("forced!"))
env_bind_lazy(env, name = !!expr)
env$name


# By default the expressions are evaluated in the current
# environment. For instance we can create a local binding and refer
# to it, even though the variable is bound in a different
# environment:
who <- "mickey"
env_bind_lazy(env, name = paste(who, "mouse"))
env$name

# You can specify another evaluation environment with `.eval_env`:
eval_env <- env(who = "minnie")
env_bind_lazy(env, name = paste(who, "mouse"), .eval_env = eval_env)
env$name

# Or by unquoting a quosure:
quo <- local({
  who <- "fievel"
  quo(paste(who, "mouse"))
})
env_bind_lazy(env, name = !!quo)
env$name

# You can create active bindings with env_bind_active(). Active
# bindings execute a function each time they are evaluated:
fn <- function() {
  cat("I have been called\n")
  rnorm(1)
}

env <- env()
env_bind_active(env, symbol = fn)

# `fn` is executed each time `symbol` is evaluated or retrieved:
env$symbol
env$symbol
eval_bare(quote(symbol), env)
eval_bare(quote(symbol), env)

# All arguments are passed to as_function() so you can use the
# formula shortcut:
env_bind_active(env, foo = ~ runif(1))
env$foo
env$foo

Description

• env_browse(env) is equivalent to evaluating browser() in env. It persistently sets the environment for step-debugging. Supply value = FALSE to disable browsing.

• env_is_browsed() is a predicate that inspects whether an environment is being browsed.

Usage

env_browse(env, value = TRUE)

env_is_browsed(env)

Arguments

Value

env_browse() returns the previous value of env_is_browsed() (a logical), invisibly.

Description

env_cache() is a wrapper around env_get() and env_poke() designed to retrieve a cached value from env.

• If the nm binding exists, it returns its value.

• Otherwise, it stores the default value in env and returns that.

Usage

env_cache(env, nm, default)

Arguments

Value

Either the value of nm or default if it did not exist yet.

Examples

e <- env(a = "foo")

# Returns existing binding
env_cache(e, "a", "default")

# Creates a `b` binding and returns its default value
env_cache(e, "b", "default")

# Now `b` is defined
e$b

Description

• env_clone() creates a new environment containing exactly the same bindings as the input, optionally with a new parent.

• env_coalesce() copies binding from the RHS environment into the LHS. If the RHS already contains bindings with the same name as in the LHS, those are kept as is.

Both these functions preserve active bindings and promises (the latter are only preserved on R >= 4.0.0).

Usage

env_clone(env, parent = env_parent(env))

env_coalesce(env, from)

Arguments

Examples

# A clone initially contains the same bindings as the original
# environment
env <- env(a = 1, b = 2)
clone <- env_clone(env)

env_print(clone)
env_print(env)

# But it can acquire new bindings or change existing ones without
# impacting the original environment
env_bind(clone, a = "foo", c = 3)

env_print(clone)
env_print(env)


# `env_coalesce()` copies bindings from one environment to another
lhs <- env(a = 1)
rhs <- env(a = "a", b = "b", c = "c")
env_coalesce(lhs, rhs)
env_print(lhs)

# To copy all the bindings from `rhs` into `lhs`, first delete the
# conflicting bindings from `rhs`
env_unbind(lhs, env_names(rhs))
env_coalesce(lhs, rhs)
env_print(lhs)

Description

This function returns the number of environments between env and the empty environment, including env. The depth of env is also the number of parents of env (since the empty environment counts as a parent).

Usage

env_depth(env)

Arguments

Value

An integer.

See Also

The section on inheritance in env() documentation.

Examples

env_depth(empty_env())
env_depth(pkg_env("rlang"))

Description

env_get() extracts an object from an enviroment env. By default, it does not look in the parent environments. env_get_list() extracts multiple objects from an environment into a named list.

Usage

env_get(env = caller_env(), nm, default, inherit = FALSE, last = empty_env())

env_get_list(
  env = caller_env(),
  nms,
  default,
  inherit = FALSE,
  last = empty_env()
)

Arguments

Value

An object if it exists. Otherwise, throws an error.

See Also

env_cache() for a variant of env_get() designed to cache a value in an environment.

Examples

parent <- child_env(NULL, foo = "foo")
env <- child_env(parent, bar = "bar")

# This throws an error because `foo` is not directly defined in env:
# env_get(env, "foo")

# However `foo` can be fetched in the parent environment:
env_get(env, "foo", inherit = TRUE)

# You can also avoid an error by supplying a default value:
env_get(env, "foo", default = "FOO")

Description

env_has() is a vectorised predicate that queries whether an environment owns bindings personally (with inherit set to FALSE, the default), or sees them in its own environment or in any of its parents (with inherit = TRUE).

Usage

env_has(env = caller_env(), nms, inherit = FALSE)

Arguments

Value

A named logical vector as long as nms.

Examples

parent <- child_env(NULL, foo = "foo")
env <- child_env(parent, bar = "bar")

# env does not own `foo` but sees it in its parent environment:
env_has(env, "foo")
env_has(env, "foo", inherit = TRUE)

Description

This returns TRUE if x has ancestor among its parents.

Usage

env_inherits(env, ancestor)

Arguments

Description

Detects if env is user-facing, that is, whether it's an environment that inherits from:

• The global environment, as would happen when called interactively

• A package that is currently being tested

If either is true, we consider env to belong to an evaluation frame that was called directly by the end user. This is by contrast to indirect calls by third party functions which are not user facing.

For instance the lifecycle package uses env_is_user_facing() to figure out whether a deprecated function was called directly or indirectly, and select an appropriate verbosity level as a function of that.

Usage

env_is_user_facing(env)

Arguments

Escape hatch

You can override the return value of env_is_user_facing() by setting the global option "rlang_user_facing" to:

• TRUE or FALSE.

• A package name as a string. Then env_is_user_facing(x) returns TRUE if x inherits from the namespace corresponding to that package name.

Examples

fn <- function() {
  env_is_user_facing(caller_env())
}

# Direct call of `fn()` from the global env
with(global_env(), fn())

# Indirect call of `fn()` from a package
with(ns_env("utils"), fn())

Description

Special environments like the global environment have their own names. env_name() returns:

• "global" for the global environment.

• "empty" for the empty environment.

• "base" for the base package environment (the last environment on the search path).

• "namespace:pkg" if env is the namespace of the package "pkg".

• The name attribute of env if it exists. This is how the package environments and the imports environments store their names. The name of package environments is typically "package:pkg".

• The empty string "" otherwise.

env_label() is exactly like env_name() but returns the memory address of anonymous environments as fallback.

Usage

env_name(env)

env_label(env)

Arguments

Examples

# Some environments have specific names:
env_name(global_env())
env_name(ns_env("rlang"))

# Anonymous environments don't have names but are labelled by their
# address in memory:
env_name(env())
env_label(env())

Description

env_names() returns object names from an enviroment env as a character vector. All names are returned, even those starting with a dot. env_length() returns the number of bindings.

Usage

env_names(env)

env_length(env)

Arguments

Value

A character vector of object names.

Names of symbols and objects

Technically, objects are bound to symbols rather than strings, since the R interpreter evaluates symbols (see is_expression() for a discussion of symbolic objects versus literal objects). However it is often more convenient to work with strings. In rlang terminology, the string corresponding to a symbol is called the name of the symbol (or by extension the name of an object bound to a symbol).

Encoding

There are deep encoding issues when you convert a string to symbol and vice versa. Symbols are always in the native encoding. If that encoding (let's say latin1) cannot support some characters, these characters are serialised to ASCII. That's why you sometimes see strings looking like ⁠<U+1234>⁠, especially if you're running Windows (as R doesn't support UTF-8 as native encoding on that platform).

To alleviate some of the encoding pain, env_names() always returns a UTF-8 character vector (which is fine even on Windows) with ASCII unicode points translated back to UTF-8.

Examples

env <- env(a = 1, b = 2)
env_names(env)

Description

• env_parent() returns the parent environment of env if called with n = 1, the grandparent with n = 2, etc.

• env_tail() searches through the parents and returns the one which has empty_env() as parent.

• env_parents() returns the list of all parents, including the empty environment. This list is named using env_name().

See the section on inheritance in env()'s documentation.

Usage

env_parent(env = caller_env(), n = 1)

env_tail(env = caller_env(), last = global_env())

env_parents(env = caller_env(), last = global_env())

Arguments

Value

An environment for env_parent() and env_tail(), a list of environments for env_parents().

Examples

# Get the parent environment with env_parent():
env_parent(global_env())

# Or the tail environment with env_tail():
env_tail(global_env())

# By default, env_parent() returns the parent environment of the
# current evaluation frame. If called at top-level (the global
# frame), the following two expressions are equivalent:
env_parent()
env_parent(base_env())

# This default is more handy when called within a function. In this
# case, the enclosure environment of the function is returned
# (since it is the parent of the evaluation frame):
enclos_env <- env()
fn <- set_env(function() env_parent(), enclos_env)
identical(enclos_env, fn())

Description

env_poke() will assign or reassign a binding in env if create is TRUE. If create is FALSE and a binding does not already exists, an error is issued.

Usage

env_poke(env = caller_env(), nm, value, inherit = FALSE, create = !inherit)

Arguments

Details

If inherit is TRUE, the parents environments are checked for an existing binding to reassign. If not found and create is TRUE, a new binding is created in env. The default value for create is a function of inherit: FALSE when inheriting, TRUE otherwise.

This default makes sense because the inheriting case is mostly for overriding an existing binding. If not found, something probably went wrong and it is safer to issue an error. Note that this is different to the base R operator ⁠<<-⁠ which will create a binding in the global environment instead of the current environment when no existing binding is found in the parents.

Value

The old value of nm or a zap sentinel if the binding did not exist yet.

See Also

env_bind() for binding multiple elements. env_cache() for a variant of env_poke() designed to cache values.

Description

This prints:

• The label and the parent label.

• Whether the environment is locked.

• The bindings in the environment (up to 20 bindings). They are printed succintly using pillar::type_sum() (if available, otherwise uses an internal version of that generic). In addition fancy bindings (actives and promises) are indicated as such.

• Locked bindings get a ⁠[L]⁠ tag

Note that printing a package namespace (see ns_env()) with env_print() will typically tag function bindings as ⁠<lazy>⁠ until they are evaluated the first time. This is because package functions are lazily-loaded from disk to improve performance when loading a package.

Usage

env_print(env = caller_env())

Arguments

Description

env_unbind() is the complement of env_bind(). Like env_has(), it ignores the parent environments of env by default. Set inherit to TRUE to track down bindings in parent environments.

Usage

env_unbind(env = caller_env(), nms, inherit = FALSE)

Arguments

Value

The input object env with its associated environment modified in place, invisibly.

Examples

env <- env(foo = 1, bar = 2)
env_has(env, c("foo", "bar"))

# Remove bindings with `env_unbind()`
env_unbind(env, c("foo", "bar"))
env_has(env, c("foo", "bar"))

# With inherit = TRUE, it removes bindings in parent environments
# as well:
parent <- env(empty_env(), foo = 1, bar = 2)
env <- env(parent, foo = "b")

env_unbind(env, "foo", inherit = TRUE)
env_has(env, c("foo", "bar"))
env_has(env, c("foo", "bar"), inherit = TRUE)

Description

eval_bare() is a lower-level version of function base::eval(). Technically, it is a simple wrapper around the C function Rf_eval(). You generally don't need to use eval_bare() instead of eval(). Its main advantage is that it handles stack-sensitive calls (such as return(), on.exit() or parent.frame()) more consistently when you pass an enviroment of a frame on the call stack.

Usage

eval_bare(expr, env = parent.frame())

Arguments

Details

These semantics are possible because eval_bare() creates only one frame on the call stack whereas eval() creates two frames, the second of which has the user-supplied environment as frame environment. When you supply an existing frame environment to base::eval() there will be two frames on the stack with the same frame environment. Stack-sensitive functions only detect the topmost of these frames. We call these evaluation semantics "stack inconsistent".

Evaluating expressions in the actual frame environment has useful practical implications for eval_bare():

• return() calls are evaluated in frame environments that might be burried deep in the call stack. This causes a long return that unwinds multiple frames (triggering the on.exit() event for each frame). By contrast eval() only returns from the eval() call, one level up.

• on.exit(), parent.frame(), sys.call(), and generally all the stack inspection functions sys.xxx() are evaluated in the correct frame environment. This is similar to how this type of calls can be evaluated deep in the call stack because of lazy evaluation, when you force an argument that has been passed around several times.

The flip side of the semantics of eval_bare() is that it can't evaluate break or next expressions even if called within a loop.

See Also

eval_tidy() for evaluation with data mask and quosure support.

Examples

# eval_bare() works just like base::eval() but you have to create
# the evaluation environment yourself:
eval_bare(quote(foo), env(foo = "bar"))

# eval() has different evaluation semantics than eval_bare(). It
# can return from the supplied environment even if its an
# environment that is not on the call stack (i.e. because you've
# created it yourself). The following would trigger an error with
# eval_bare():
ret <- quote(return("foo"))
eval(ret, env())
# eval_bare(ret, env())  # "no function to return from" error

# Another feature of eval() is that you can control surround loops:
bail <- quote(break)
while (TRUE) {
  eval(bail)
  # eval_bare(bail)  # "no loop for break/next" error
}

# To explore the consequences of stack inconsistent semantics, let's
# create a function that evaluates `parent.frame()` deep in the call
# stack, in an environment corresponding to a frame in the middle of
# the stack. For consistency with R's lazy evaluation semantics, we'd
# expect to get the caller of that frame as result:
fn <- function(eval_fn) {
  list(
    returned_env = middle(eval_fn),
    actual_env = current_env()
  )
}
middle <- function(eval_fn) {
  deep(eval_fn, current_env())
}
deep <- function(eval_fn, eval_env) {
  expr <- quote(parent.frame())
  eval_fn(expr, eval_env)
}

# With eval_bare(), we do get the expected environment:
fn(rlang::eval_bare)

# But that's not the case with base::eval():
fn(base::eval)

Description

eval_tidy() is a variant of base::eval() that powers the tidy evaluation framework. Like eval() it accepts user data as argument. Whereas eval() simply transforms the data to an environment, eval_tidy() transforms it to a data mask with as_data_mask(). Evaluating in a data mask enables the following features:

• Quosures. Quosures are expressions bundled with an environment. If data is supplied, objects in the data mask always have precedence over the quosure environment, i.e. the data masks the environment.

• Pronouns. If data is supplied, the .env and .data pronouns are installed in the data mask. .env is a reference to the calling environment and .data refers to the data argument. These pronouns are an escape hatch for the data mask ambiguity problem.

Usage

eval_tidy(expr, data = NULL, env = caller_env())

Arguments

When should eval_tidy() be used instead of eval()?

base::eval() is sufficient for simple evaluation. Use eval_tidy() when you'd like to support expressions referring to the .data pronoun, or when you need to support quosures.

If you're evaluating an expression captured with injection support, it is recommended to use eval_tidy() because users may inject quosures.

Note that unwrapping a quosure with quo_get_expr() does not guarantee that there is no quosures inside the expression. Quosures might be unquoted anywhere in the expression tree. For instance, the following does not work reliably in the presence of nested quosures:

my_quoting_fn <- function(x) {
  x <- enquo(x)
  expr <- quo_get_expr(x)
  env <- quo_get_env(x)
  eval(expr, env)
}

# Works:
my_quoting_fn(toupper(letters))

# Fails because of a nested quosure:
my_quoting_fn(toupper(!!quo(letters)))

Stack semantics of eval_tidy()

eval_tidy() always evaluates in a data mask, even when data is NULL. Because of this, it has different stack semantics than base::eval():

• Lexical side effects, such as assignment with ⁠<-⁠, occur in the mask rather than env.

• Functions that require the evaluation environment to correspond to a frame on the call stack do not work. This is why return() called from a quosure does not work.

• The mask environment creates a new branch in the tree representation of backtraces (which you can visualise in a browser() session with lobstr::cst()).

See also eval_bare() for more information about these differences.

See Also

• What is data-masking and why do I need {{?.

• What are quosures and when are they needed?.

• Defusing R expressions.

• new_data_mask() and as_data_mask() for manually creating data masks.

Examples

# With simple defused expressions eval_tidy() works the same way as
# eval():
fruit <- "apple"
vegetable <- "potato"
expr <- quote(paste(fruit, vegetable, sep = " or "))
expr

eval(expr)
eval_tidy(expr)

# Both accept a data mask as argument:
data <- list(fruit = "banana", vegetable = "carrot")
eval(expr, data)
eval_tidy(expr, data)

# The main difference is that eval_tidy() supports quosures:
with_data <- function(data, expr) {
  quo <- enquo(expr)
  eval_tidy(quo, data)
}
with_data(NULL, fruit)
with_data(data, fruit)

# eval_tidy() installs the `.data` and `.env` pronouns to allow
# users to be explicit about variable references:
with_data(data, .data$fruit)
with_data(data, .env$fruit)

Description

This function constructs and evaluates a call to .fn. It has two primary uses:

• To call a function with arguments stored in a list (if the function doesn't support dynamic dots). Splice the list of arguments with ⁠!!!⁠.

• To call every function stored in a list (in conjunction with map()/ lapply())

Usage

exec(.fn, ..., .env = caller_env())

Arguments

Examples

args <- list(x = c(1:10, 100, NA), na.rm = TRUE)
exec("mean", !!!args)
exec("mean", !!!args, trim = 0.2)

fs <- list(a = function() "a", b = function() "b")
lapply(fs, exec)

# Compare to do.call it will not automatically inline expressions
# into the evaluated call.
x <- 10
args <- exprs(x1 = x + 1, x2 = x * 2)
exec(list, !!!args)
do.call(list, args)

# exec() is not designed to generate pretty function calls. This is
# most easily seen if you call a function that captures the call:
f <- disp ~ cyl
exec("lm", f, data = mtcars)

# If you need finer control over the generated call, you'll need to
# construct it yourself. This may require creating a new environment
# with carefully constructed bindings
data_env <- env(data = mtcars)
eval(expr(lm(!!f, data)), data_env)

Description

expr() defuses an R expression with injection support.

It is equivalent to base::bquote().

Arguments

See Also

• Defusing R expressions for an overview.

• enquo() to defuse non-local expressions from function arguments.

• Advanced defusal operators.

• sym() and call2() for building expressions (symbols and calls respectively) programmatically.

• base::eval() and eval_bare() for resuming evaluation of a defused expression.

Examples

# R normally returns the result of an expression
1 + 1

# `expr()` defuses the expression that you have supplied and
# returns it instead of its value
expr(1 + 1)

expr(toupper(letters))

# It supports _injection_ with `!!` and `!!!`. This is a convenient
# way of modifying part of an expression by injecting other
# objects.
var <- "cyl"
expr(with(mtcars, mean(!!sym(var))))

vars <- c("cyl", "am")
expr(with(mtcars, c(!!!syms(vars))))

# Compare to the normal way of building expressions
call("with", call("mean", sym(var)))

call("with", call2("c", !!!syms(vars)))

Description

expr_print(), powered by expr_deparse(), is an alternative printer for R expressions with a few improvements over the base R printer.

• It colourises quosures according to their environment. Quosures from the global environment are printed normally while quosures from local environments are printed in unique colour (or in italic when all colours are taken).

• It wraps inlined objects in angular brackets. For instance, an integer vector unquoted in a function call (e.g. expr(foo(!!(1:3)))) is printed like this: ⁠foo(<int: 1L, 2L, 3L>)⁠ while by default R prints the code to create that vector: foo(1:3) which is ambiguous.

• It respects the width boundary (from the global option width) in more cases.

Usage

expr_print(x, ...)

expr_deparse(x, ..., width = peek_option("width"))

Arguments

Value

expr_deparse() returns a character vector of lines. expr_print() returns its input invisibly.

Examples

# It supports any object. Non-symbolic objects are always printed
# within angular brackets:
expr_print(1:3)
expr_print(function() NULL)

# Contrast this to how the code to create these objects is printed:
expr_print(quote(1:3))
expr_print(quote(function() NULL))

# The main cause of non-symbolic objects in expressions is
# quasiquotation:
expr_print(expr(foo(!!(1:3))))


# Quosures from the global environment are printed normally:
expr_print(quo(foo))
expr_print(quo(foo(!!quo(bar))))

# Quosures from local environments are colourised according to
# their environments (if you have crayon installed):
local_quo <- local(quo(foo))
expr_print(local_quo)

wrapper_quo <- local(quo(bar(!!local_quo, baz)))
expr_print(wrapper_quo)

Description

This gives default names to unnamed elements of a list of expressions (or expression wrappers such as formulas or quosures), deparsed with as_label().

Usage

exprs_auto_name(
  exprs,
  ...,
  repair_auto = c("minimal", "unique"),
  repair_quiet = FALSE
)

quos_auto_name(quos)

Arguments

Description

f_rhs extracts the righthand side, f_lhs extracts the lefthand side, and f_env extracts the environment. All functions throw an error if f is not a formula.

Usage

f_rhs(f)

f_rhs(x) <- value

f_lhs(f)

f_lhs(x) <- value

f_env(f)

f_env(x) <- value

Arguments

Value

f_rhs and f_lhs return language objects (i.e. atomic vectors of length 1, a name, or a call). f_env returns an environment.

Examples

f_rhs(~ 1 + 2 + 3)
f_rhs(~ x)
f_rhs(~ "A")
f_rhs(1 ~ 2)

f_lhs(~ y)
f_lhs(x ~ y)

f_env(~ x)

Description

Equivalent of expr_text() and expr_label() for formulas.

Usage

f_text(x, width = 60L, nlines = Inf)

f_name(x)

f_label(x)

Arguments

Examples

f <- ~ a + b + bc
f_text(f)
f_label(f)

# Names a quoted with ``
f_label(~ x)
# Strings are encoded
f_label(~ "a\nb")
# Long expressions are collapsed
f_label(~ foo({
  1 + 2
  print(x)
}))

Description

rlang has several options which may be set globally to control behavior. A brief description of each is given here. If any functions are referenced, refer to their documentation for additional details.

• rlang_interactive: A logical value used by is_interactive(). This can be set to TRUE to test interactive behavior in unit tests, for example.

• rlang_backtrace_on_error: A character string which controls whether backtraces are displayed with error messages, and the level of detail they print. See rlang_backtrace_on_error for the possible option values.

• rlang_trace_format_srcrefs: A logical value used to control whether srcrefs are printed as part of the backtrace.

• rlang_trace_top_env: An environment which will be treated as the top-level environment when printing traces. See trace_back() for examples.

Description

fn_body() is a simple wrapper around base::body(). It always returns a ⁠\{⁠ expression and throws an error when the input is a primitive function (whereas body() returns NULL). The setter version preserves attributes, unlike ⁠body<-⁠.

Usage

fn_body(fn = caller_fn())

fn_body(fn) <- value

Arguments

Examples

# fn_body() is like body() but always returns a block:
fn <- function() do()
body(fn)
fn_body(fn)

# It also throws an error when used on a primitive function:
try(fn_body(base::list))

Description

Closure environments define the scope of functions (see env()). When a function call is evaluated, R creates an evaluation frame that inherits from the closure environment. This makes all objects defined in the closure environment and all its parents available to code executed within the function.

Usage

fn_env(fn)

fn_env(x) <- value

Arguments

Details

fn_env() returns the closure environment of fn. There is also an assignment method to set a new closure environment.

Examples

env <- child_env("base")
fn <- with_env(env, function() NULL)
identical(fn_env(fn), env)

other_env <- child_env("base")
fn_env(fn) <- other_env
identical(fn_env(fn), other_env)

Description

fn_fmls() returns a named list of formal arguments. fn_fmls_names() returns the names of the arguments. fn_fmls_syms() returns formals as a named list of symbols. This is especially useful for forwarding arguments in constructed calls.

Usage

fn_fmls(fn = caller_fn())

fn_fmls_names(fn = caller_fn())

fn_fmls_syms(fn = caller_fn())

fn_fmls(fn) <- value

fn_fmls_names(fn) <- value

Arguments

Details

Unlike formals(), these helpers throw an error with primitive functions instead of returning NULL.

See Also

call_args() and call_args_names()

Examples

# Extract from current call:
fn <- function(a = 1, b = 2) fn_fmls()
fn()

# fn_fmls_syms() makes it easy to forward arguments:
call2("apply", !!! fn_fmls_syms(lapply))

# You can also change the formals:
fn_fmls(fn) <- list(A = 10, B = 20)
fn()

fn_fmls_names(fn) <- c("foo", "bar")
fn()

Description

format_error_bullets() takes a character vector and returns a single string (or an empty vector if the input is empty). The elements of the input vector are assembled as a list of bullets, depending on their names:

• Unnamed elements are unindented. They act as titles or subtitles.

• Elements named "*" are bulleted with a cyan "bullet" symbol.

• Elements named "i" are bulleted with a blue "info" symbol.

• Elements named "x" are bulleted with a red "cross" symbol.

• Elements named "v" are bulleted with a green "tick" symbol.

• Elements named "!" are bulleted with a yellow "warning" symbol.

• Elements named ">" are bulleted with an "arrow" symbol.

• Elements named " " start with an indented line break.

For convenience, if the vector is fully unnamed, the elements are formatted as "*" bullets.

The bullet formatting for errors follows the idea that sentences in error messages are best kept short and simple. The best way to present the information is in the cnd_body() method of an error conditon as a bullet list of simple sentences containing a single clause. The info and cross symbols of the bullets provide hints on how to interpret the bullet relative to the general error issue, which should be supplied as cnd_header().

Usage

format_error_bullets(x)

Arguments

Examples

# All bullets
writeLines(format_error_bullets(c("foo", "bar")))

# This is equivalent to
writeLines(format_error_bullets(set_names(c("foo", "bar"), "*")))

# Supply named elements to format info, cross, and tick bullets
writeLines(format_error_bullets(c(i = "foo", x = "bar", v = "baz", "*" = "quux")))

# An unnamed element breaks the line
writeLines(format_error_bullets(c(i = "foo\nbar")))

# A " " element breaks the line within a bullet (with indentation)
writeLines(format_error_bullets(c(i = "foo", " " = "bar")))

Description

These functions dispatch internally with methods for functions, formulas and frames. If called with a missing argument, the environment of the current evaluation frame is returned. If you call get_env() with an environment, it acts as the identity function and the environment is simply returned (this helps simplifying code when writing generic functions for environments).

Usage

get_env(env, default = NULL)

set_env(env, new_env = caller_env())

env_poke_parent(env, new_env)

Arguments

Details

While set_env() returns a modified copy and does not have side effects, env_poke_parent() operates changes the environment by side effect. This is because environments are uncopyable. Be careful not to change environments that you don't own, e.g. a parent environment of a function from a package.

See Also

quo_get_env() and quo_set_env() for versions of get_env() and set_env() that only work on quosures.

Examples

# Environment of closure functions:
fn <- function() "foo"
get_env(fn)

# Or of quosures or formulas:
get_env(~foo)
get_env(quo(foo))


# Provide a default in case the object doesn't bundle an environment.
# Let's create an unevaluated formula:
f <- quote(~foo)

# The following line would fail if run because unevaluated formulas
# don't bundle an environment (they didn't have the chance to
# record one yet):
# get_env(f)

# It is often useful to provide a default when you're writing
# functions accepting formulas as input:
default <- env()
identical(get_env(f, default), default)

# set_env() can be used to set the enclosure of functions and
# formulas. Let's create a function with a particular environment:
env <- child_env("base")
fn <- set_env(function() NULL, env)

# That function now has `env` as enclosure:
identical(get_env(fn), env)
identical(get_env(fn), current_env())

# set_env() does not work by side effect. Setting a new environment
# for fn has no effect on the original function:
other_env <- child_env(NULL)
set_env(fn, other_env)
identical(get_env(fn), other_env)

# Since set_env() returns a new function with a different
# environment, you'll need to reassign the result:
fn <- set_env(fn, other_env)
identical(get_env(fn), other_env)

Description

global_entrace() enriches base errors, warnings, and messages with rlang features.

• They are assigned a backtrace. You can configure whether to display a backtrace on error with the rlang_backtrace_on_error global option.

• They are recorded in last_error(), last_warnings(), or last_messages(). You can inspect backtraces at any time by calling these functions.

Set global entracing in your RProfile with:

rlang::global_entrace()

Usage

global_entrace(enable = TRUE, class = c("error", "warning", "message"))

Arguments

Inside RMarkdown documents

Call global_entrace() inside an RMarkdown document to cause errors and warnings to be promoted to rlang conditions that include a backtrace. This needs to be done in a separate setup chunk before the first error or warning.

This is useful in conjunction with rlang_backtrace_on_error_report and rlang_backtrace_on_warning_report. To get full entracing in an Rmd document, include this in a setup chunk before the first error or warning is signalled.

```{r setup}
rlang::global_entrace()
options(rlang_backtrace_on_warning_report = "full")
options(rlang_backtrace_on_error_report = "full")
```

Under the hood

On R 4.0 and newer, global_entrace() installs a global handler with globalCallingHandlers(). On older R versions, entrace() is set as an option(error = ) handler. The latter method has the disadvantage that only one handler can be set at a time. This means that you need to manually switch between entrace() and other handlers like recover(). Also this causes a conflict with IDE handlers (e.g. in RStudio).

Description

global_handle() sets up a default configuration for error, warning, and message handling. It calls:

• global_entrace() to enable rlang errors and warnings globally.

• global_prompt_install() to recover from packageNotFoundErrors with a user prompt to install the missing package. Note that at the time of writing (R 4.1), there are only very limited situations where this handler works.

Usage

global_handle(entrace = TRUE, prompt_install = TRUE)

Arguments

Description

When enabled, packageNotFoundError thrown by loadNamespace() cause a user prompt to install the missing package and continue without interrupting the current program.

This is similar to how check_installed() prompts users to install required packages. It uses the same install strategy, using pak if available and install.packages() otherwise.

Usage

global_prompt_install(enable = TRUE)

Arguments

Description

Dynamic dots (and data-masked dots which are dynamic by default) have built-in support for names interpolation with the glue package.

tibble::tibble(foo = 1)
#> # A tibble: 1 x 1
#>     foo
#>   <dbl>
#> 1     1

foo <- "name"
tibble::tibble("{foo}" := 1)
#> # A tibble: 1 x 1
#>    name
#>   <dbl>
#> 1     1

Inside functions, embracing an argument with {{ inserts the expression supplied as argument in the string. This gives an indication on the variable or computation supplied as argument:

tib <- function(x) {
  tibble::tibble("var: {{ x }}" := x)
}

tib(1 + 1)
#> # A tibble: 1 x 1
#>   `var: 1 + 1`
#>          <dbl>
#> 1            2

See also englue() to string-embrace outside of dynamic dots.

g <- function(x) {
  englue("var: {{ x }}")
}

g(1 + 1)
#> [1] "var: 1 + 1"

Technically, ⁠"{{"⁠ defuses a function argument, calls as_label() on the expression supplied as argument, and inserts the result in the string.

⁠"{"⁠ and ⁠"{{"⁠

While glue::glue() only supports ⁠"{"⁠, dynamic dots support both ⁠"{"⁠ and ⁠"{{"⁠. The double brace variant is similar to the embrace operator {{ available in data-masked arguments.

In the following example, the embrace operator is used in a glue string to name the result with a default name that represents the expression supplied as argument:

my_mean <- function(data, var) {
  data %>% dplyr::summarise("{{ var }}" := mean({{ var }}))
}

mtcars %>% my_mean(cyl)
#> # A tibble: 1 x 1
#>     cyl
#>   <dbl>
#> 1  6.19

mtcars %>% my_mean(cyl * am)
#> # A tibble: 1 x 1
#>   `cyl * am`
#>        <dbl>
#> 1       2.06

⁠"{{"⁠ is only meant for inserting an expression supplied as argument to a function. The result of the expression is not inspected or used. To interpolate a string stored in a variable, use the regular glue operator ⁠"{"⁠ instead:

my_mean <- function(data, var, name = "mean") {
  data %>% dplyr::summarise("{name}" := mean({{ var }}))
}

mtcars %>% my_mean(cyl)
#> # A tibble: 1 x 1
#>    mean
#>   <dbl>
#> 1  6.19

mtcars %>% my_mean(cyl, name = "cyl")
#> # A tibble: 1 x 1
#>     cyl
#>   <dbl>
#> 1  6.19

Using the wrong operator causes unexpected results:

x <- "name"

list2("{{ x }}" := 1)
#> $`"name"`
#> [1] 1

list2("{x}" := 1)
#> $name
#> [1] 1

Ideally, using ⁠{{⁠ on regular objects would be an error. However for technical reasons it is not possible to make a distinction between function arguments and ordinary variables. See Does {{ work on regular objects? for more information about this limitation.

Allow overriding default names

The implementation of my_mean() in the previous section forces a default name onto the result. But what if the caller wants to give it a different name? In functions that take dots, it is possible to just supply a named expression to override the default. In a function like my_mean() that takes a named argument we need a different approach.

This is where englue() becomes useful. We can pull out the default name creation in another user-facing argument like this:

my_mean <- function(data, var, name = englue("{{ var }}")) {
  data %>% dplyr::summarise("{name}" := mean({{ var }}))
}

Now the user may supply their own name if needed:

mtcars %>% my_mean(cyl * am)
#> # A tibble: 1 x 1
#>   `cyl * am`
#>        <dbl>
#> 1       2.06

mtcars %>% my_mean(cyl * am, name = "mean_cyl_am")
#> # A tibble: 1 x 1
#>   mean_cyl_am
#>         <dbl>
#> 1        2.06

What's the deal with ⁠:=⁠?

Name injection in dynamic dots was originally implemented with ⁠:=⁠ instead of = to allow complex expressions on the LHS:

x <- "name"
list2(!!x := 1)
#> $name
#> [1] 1

Name-injection with glue operations was an extension of this existing feature and so inherited the same interface. However, there is no technical barrier to using glue strings on the LHS of =.

As we are now moving away from !! for common tasks, we are considering enabling glue strings with = and superseding ⁠:=⁠ usage. Track the progress of this change in issue 1296.

Using glue syntax in packages

Since rlang does not depend directly on glue, you will have to ensure that glue is installed by adding it to your ⁠Imports:⁠ section.

usethis::use_package("glue", "Imports")

Description

This function returns a logical value that indicates if a data frame or another named object contains an element with a specific name. Note that has_name() only works with vectors. For instance, environments need the specialised function env_has().

Usage

has_name(x, name)

Arguments

Details

Unnamed objects are treated as if all names are empty strings. NA input gives FALSE as output.

Value

A logical vector of the same length as name

Examples

has_name(iris, "Species")
has_name(mtcars, "gears")

Description

• hash() hashes an arbitrary R object.

• hash_file() hashes the data contained in a file.

The generated hash is guaranteed to be reproducible across platforms that have the same endianness and are using the same R version.

Usage

hash(x)

hash_file(path)

Arguments

Details

These hashers use the XXH128 hash algorithm of the xxHash library, which generates a 128-bit hash. Both are implemented as streaming hashes, which generate the hash with minimal extra memory usage.

For hash(), objects are converted to binary using R's native serialization tools. On R >= 3.5.0, serialization version 3 is used, otherwise version 2 is used. See serialize() for more information about the serialization version.

Value

• For hash(), a single character string containing the hash.

• For hash_file(), a character vector containing one hash per file.

Examples

hash(c(1, 2, 3))
hash(mtcars)

authors <- file.path(R.home("doc"), "AUTHORS")
copying <- file.path(R.home("doc"), "COPYING")
hashes <- hash_file(c(authors, copying))
hashes

# If you need a single hash for multiple files,
# hash the result of `hash_file()`
hash(hashes)

Description

• inherits_any() is like base::inherits() but is more explicit about its behaviour with multiple classes. If classes contains several elements and the object inherits from at least one of them, inherits_any() returns TRUE.

• inherits_all() tests that an object inherits from all of the classes in the supplied order. This is usually the best way to test for inheritance of multiple classes.

• inherits_only() tests that the class vectors are identical. It is a shortcut for identical(class(x), class).