rlang: Functions for Base Types and Core R and 'Tidyverse' Features

Description

A toolbox for working with base types, core R features like the condition system, and core 'Tidyverse' features like tidy evaluation.

Author(s)

Maintainer: Lionel Henry lionel@posit.co

Authors:

• Hadley Wickham hadley@posit.co

Other contributors:

• mikefc mikefc@coolbutuseless.com (Hash implementation based on Mike's xxhashlite) [copyright holder]

• Yann Collet (Author of the embedded xxHash library) [copyright holder]

• Posit, PBC [copyright holder, funder]

See Also

Useful links:

• https://rlang.r-lib.org

• https://github.com/r-lib/rlang

• Report bugs at https://github.com/r-lib/rlang/issues

Signal an error, warning, or message

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)
  })
)

# You can also hard-code the call when it's not easy to
# forward it from the caller
 f <- function() {
  abort("my message", call = call("my_function"))
}
g <- function() {
  f()
}
# Shows that the error occured in `my_function()`
try(g())

}

Test for missing values

Description

are_na() checks for missing values in a vector and is equivalent to base::is.na(). It is a vectorised predicate, meaning that its output is always the same length as its input. On the other hand, is_na() is a scalar predicate and always returns a scalar boolean, TRUE or FALSE. If its input is not scalar, it returns FALSE. Finally, there are typed versions that check for particular missing types.

Usage

are_na(x)

is_na(x)

is_lgl_na(x)

is_int_na(x)

is_dbl_na(x)

is_chr_na(x)

is_cpl_na(x)

Arguments

Details

The scalar predicates accept non-vector inputs. They are equivalent to is_null() in that respect. In contrast the vectorised predicate are_na() requires a vector input since it is defined over vector values.

Life cycle

These functions might be moved to the vctrs package at some point. This is why they are marked as questioning.

Examples

# are_na() is vectorised and works regardless of the type
are_na(c(1, 2, NA))
are_na(c(1L, NA, 3L))

# is_na() checks for scalar input and works for all types
is_na(NA)
is_na(na_dbl)
is_na(character(0))

# There are typed versions as well:
is_lgl_na(NA)
is_lgl_na(na_dbl)

Match an argument to a character vector

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"))

Argument type: data-masking

Description

This page describes the ⁠<data-masking>⁠ argument modifier which indicates that the argument uses tidy evaluation with data masking. If you've never heard of tidy evaluation before, start with vignette("programming", package = "dplyr").

Key terms

The primary motivation for tidy evaluation in tidyverse packages is that it provides data masking, which blurs the distinction between two types of variables:

• env-variables are "programming" variables and live in an environment. They are usually created with ⁠<-⁠. Env-variables can be any type of R object.

• data-variables are "statistical" variables and live in a data frame. They usually come from data files (e.g. .csv, .xls), or are created by manipulating existing variables. Data-variables live inside data frames, so must be vectors.

General usage

Data masking allows you to refer to variables in the "current" data frame (usually supplied in the .data argument), without any other prefix. It's what allows you to type (e.g.) filter(diamonds, x == 0 & y == 0 & z == 0) instead of diamonds[diamonds$x == 0 & diamonds$y == 0 & diamonds$z == 0, ].

Indirection

The main challenge of data masking arises when you introduce some indirection, i.e. instead of directly typing the name of a variable you want to supply it in a function argument or character vector.

There are two main cases:

• If you want the user to supply the variable (or function of variables) in a function argument, embrace the argument, e.g. filter(df, {{ var }}).

  dist_summary <- function(df, var) {
    df %>%
      summarise(n = n(), min = min({{ var }}), max = max({{ var }}))
  }
  mtcars %>% dist_summary(mpg)
  mtcars %>% group_by(cyl) %>% dist_summary(mpg)
  

• If you have the column name as a character vector, use the .data pronoun, e.g. summarise(df, mean = mean(.data[[var]])).

  for (var in names(mtcars)) {
    mtcars %>% count(.data[[var]]) %>% print()
  }
  
  lapply(names(mtcars), function(var) mtcars %>% count(.data[[var]]))
  

  (Note that the contents of [[, e.g. var above, is never evaluated in the data environment so you don't need to worry about a data-variable called var causing problems.)

Dot-dot-dot (...)

When this modifier is applied to ..., there is one other useful technique which solves the problem of creating a new variable with a name supplied by the user. Use the interpolation syntax from the glue package: "{var}" := expression. (Note the use of ⁠:=⁠ instead of = to enable this syntax).

var_name <- "l100km"
mtcars %>% mutate("{var_name}" := 235 / mpg)

Note that ... automatically provides indirection, so you can use it as is (i.e. without embracing) inside a function:

grouped_mean <- function(df, var, ...) {
  df %>%
    group_by(...) %>%
    summarise(mean = mean({{ var }}))
}

See Also

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

• Data mask programming patterns.

Helper for consistent documentation of empty dots

Description

Use ⁠@inheritParams rlang::args_dots_empty⁠ in your package to consistently document ... that must be empty.

Arguments

Helper for consistent documentation of used dots

Description

Use ⁠@inheritParams rlang::args_dots_used⁠ in your package to consistently document ... that must be used.

Arguments

Documentation anchor for error arguments

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

Convert object to a box

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

Transform to a closure

Description

as_closure() is like as_function() but also wraps primitive functions inside closures. Some special control flow primitives like if, for, or break can't be wrapped and will cause an error.

Usage

as_closure(x, env = caller_env())

Arguments

Examples

# Primitive functions are regularised as closures
as_closure(list)
as_closure("list")

# Operators have `.x` and `.y` as arguments, just like lambda
# functions created with the formula syntax:
as_closure(`+`)
as_closure(`~`)

Create a data mask

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)

Coerce to an environment

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)

Convert to function

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"))

Create a default name for an R object

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)

Extract names from symbols

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))

Cast symbol to string

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))

Coerce to a character vector and attempt encoding conversion

Description

Unlike specifying the encoding argument in as_string() and as_character(), which is only declarative, these functions actually attempt to convert the encoding of their input. There are two possible cases:

• The string is tagged as UTF-8 or latin1, the only two encodings for which R has specific support. In this case, converting to the same encoding is a no-op, and converting to native always works as expected, as long as the native encoding, the one specified by the LC_CTYPE locale has support for all characters occurring in the strings. Unrepresentable characters are serialised as unicode points: "<U+xxxx>".

• The string is not tagged. R assumes that it is encoded in the native encoding. Conversion to native is a no-op, and conversion to UTF-8 should work as long as the string is actually encoded in the locale codeset.

When translating to UTF-8, the strings are parsed for serialised unicode points (e.g. strings looking like "U+xxxx") with chr_unserialise_unicode(). This helps to alleviate the effects of character-to-symbol-to-character roundtrips on systems with non-UTF-8 native encoding.

Usage

as_utf8_character(x)

Arguments

Examples

# Let's create a string marked as UTF-8 (which is guaranteed by the
# Unicode escaping in the string):
utf8 <- "caf\uE9"
Encoding(utf8)
charToRaw(utf8)

Bare type predicates

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() for R < 4.4.0, is_bare_atomic() does not return TRUE for NULL. Starting in R 4.4.0, is.atomic(NULL) returns FALSE.

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

See Also

type-predicates, scalar-type-predicates

Box a value

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")

Human readable memory sizes

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")))

Extract arguments from a call

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)

Extract function from a call

Description

Deprecated in rlang 0.4.11.

Usage

call_fn(call, env = caller_env())

Arguments

Inspect a 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)

Match supplied arguments to function definition

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)

Modify the arguments of a call

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")

Extract function name or namespace of a call

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()))

Standardise a call

Description

Deprecated in rlang 0.4.11 in favour of call_match(). call_standardise() was designed for call wrappers that include an environment like formulas or quosures. The function definition was plucked from that environment. However in practice it is rare to use it with wrapped calls, and then it's easy to forget to supply the environment. For these reasons, we have designed call_match() as a simpler wrapper around match.call().

This is essentially equivalent to base::match.call(), but with experimental handling of primitive functions.

Usage

call_standardise(call, env = caller_env())

Arguments

Value

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

Create a call

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 = )

Find the caller argument for error messages

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))

Catch a condition

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"))

Check that dots are empty

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

See Also

Other dots checking functions: check_dots_unnamed(), check_dots_used()

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)

Check that dots are empty (low level variant)

Description

check_dots_empty0() is a more efficient version of check_dots_empty() with a slightly different interface. Instead of inspecting the current environment for dots, it directly takes .... It is only meant for very low level functions where a couple microseconds make a difference.

Usage

check_dots_empty0(..., call = caller_env())

Arguments

Check that all dots are unnamed

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

See Also

Other dots checking functions: check_dots_empty(), check_dots_used()

Examples

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

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

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

Check that all dots have been used

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().

See Also

Other dots checking functions: check_dots_empty(), check_dots_unnamed()

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()

Check that arguments are mutually exclusive

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()

Check that argument is supplied

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)

Create a child environment

Description

env() now supports creating child environments, please use it instead.

Usage

child_env(.parent, ...)

Translate unicode points to UTF-8

Description

For historical reasons, R translates strings to the native encoding when they are converted to symbols. This string-to-symbol conversion is not a rare occurrence and happens for instance to the names of a list of arguments converted to a call by do.call().

If the string contains unicode characters that cannot be represented in the native encoding, R serialises those as an ASCII sequence representing the unicode point. This is why Windows users with western locales often see strings looking like ⁠<U+xxxx>⁠. To alleviate some of the pain, rlang parses strings and looks for serialised unicode points to translate them back to the proper UTF-8 representation. This transformation occurs automatically in functions like env_names() and can be manually triggered with as_utf8_character() and chr_unserialise_unicode().

Usage

chr_unserialise_unicode(chr)

Arguments

Life cycle

This function is experimental.

Examples

ascii <- "<U+5E78>"
chr_unserialise_unicode(ascii)

identical(chr_unserialise_unicode(ascii), "\u5e78")

Create a condition object

Description

These constructors create subclassed conditions, the objects that power the error, warning, and message system in R.

• cnd() creates bare conditions that only inherit from condition.

• Conditions created with error_cnd(), warning_cnd(), and message_cnd() inherit from "error", "warning", or "message".

• error_cnd() creates subclassed errors. See "rlang_error".

Use cnd_signal() to emit the relevant signal for a particular condition class.

Usage

cnd(class, ..., message = "", call = NULL, use_cli_format = NULL)

error_cnd(
  class = NULL,
  ...,
  message = "",
  call = NULL,
  trace = NULL,
  parent = NULL,
  use_cli_format = NULL
)

warning_cnd(
  class = NULL,
  ...,
  message = "",
  call = NULL,
  use_cli_format = NULL
)

message_cnd(
  class = NULL,
  ...,
  message = "",
  call = NULL,
  use_cli_format = NULL
)

Arguments

See Also

cnd_signal(), try_fetch().

Examples

# Create a condition inheriting only from the S3 class "foo":
cnd <- cnd("foo")

# Signal the condition to potential handlers. Since this is a bare
# condition the signal has no effect if no handlers are set up:
cnd_signal(cnd)

# When a relevant handler is set up, the signal transfers control
# to the handler
with_handlers(cnd_signal(cnd), foo = function(c) "caught!")
tryCatch(cnd_signal(cnd), foo = function(c) "caught!")

Does a condition or its ancestors inherit from a class?

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"

Build an error message from parts

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.

Muffle a condition

Description

Unlike exiting() handlers, calling() handlers must be explicit that they have handled a condition to stop it from propagating to other handlers. Use cnd_muffle() within a calling handler (or as a calling handler, see examples) to prevent any other handlers from being called for that condition.

Usage

cnd_muffle(cnd)

Arguments

Value

If cnd is mufflable, cnd_muffle() jumps to the muffle restart and doesn't return. Otherwise, it returns FALSE.

Mufflable conditions

Most conditions signalled by base R are muffable, although the name of the restart varies. cnd_muffle() will automatically call the correct restart for you. It is compatible with the following conditions:

• warning and message conditions. In this case cnd_muffle() is equivalent to base::suppressMessages() and base::suppressWarnings().

• Bare conditions signalled with signal() or cnd_signal(). Note that conditions signalled with base::signalCondition() are not mufflable.

• Interrupts are sometimes signalled with a resume restart on recent R versions. When this is the case, you can muffle the interrupt with cnd_muffle(). Check if a restart is available with base::findRestart("resume").

If you call cnd_muffle() with a condition that is not mufflable you will cause a new error to be signalled.

• Errors are not mufflable since they are signalled in critical situations where execution cannot continue safely.

• Conditions captured with base::tryCatch(), with_handlers() or catch_cnd() are no longer mufflable. Muffling restarts must be called from a calling handler.

Examples

fn <- function() {
  inform("Beware!", "my_particular_msg")
  inform("On your guard!")
  "foobar"
}

# Let's install a muffling handler for the condition thrown by `fn()`.
# This will suppress all `my_particular_wng` warnings but let other
# types of warnings go through:
with_handlers(fn(),
  my_particular_msg = calling(function(cnd) {
    inform("Dealt with this particular message")
    cnd_muffle(cnd)
  })
)

# Note how execution of `fn()` continued normally after dealing
# with that particular message.

# cnd_muffle() can also be passed to with_handlers() as a calling
# handler:
with_handlers(fn(),
  my_particular_msg = calling(cnd_muffle)
)

Signal a condition object

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))

What type is a condition?

Description

Use cnd_type() to check what type a condition is.

Usage

cnd_type(cnd)

Arguments

Value

A string, either "condition", "message", "warning", "error" or "interrupt".

Examples

cnd_type(catch_cnd(abort("Abort!")))
cnd_type(catch_cnd(interrupt()))

Advanced defusal operators

Description

These advanced operators defuse R expressions. expr(), enquo(), and enquos() are sufficient for most purposes but rlang provides these other operations, either for completeness or because they are useful to experts.

• exprs() is the plural variant of expr(). It returns a list of expressions. It is like base::alist() but with injection support.

• quo() and quos() are like expr() and exprs() but return quosures instead of naked expressions. When you are defusing your own local expressions (by opposition to function arguments where non-local expressions are supplied by your users), there is generally no need to attach the current environment in a quosure. See What are quosures and when are they needed?.

• enexpr() and enexprs() are like enquo() and enquos() but return naked expressions instead of quosures. These operators should very rarely be used because they lose track of the environment of defused arguments.

• ensym() and ensyms() are like enexpr() and enexprs() but they throw an error when the defused expressions are not simple symbols. They also support strings which are interpreted as symbols. These functions are modelled on the behaviour of the left-hand side of = and ⁠<-⁠ where you can supply symbols and strings interchangeably.

  "foo" <- NULL
  list("foo" = NULL)
  

• enquo0 and enquos0() are like enquo() and enquos() but without injection support. The injection operators ⁠!!⁠, ⁠!!!⁠, and ⁠{{⁠ are not processed, instead they are preserved in the defused expression. This makes it possible to defuse expressions that potentially contain injection operators meant for later use. The trade off is that it makes it harder for users to inject expressions in your function. They have to enable injection explicitly with inject().

  None of the features of dynamic dots are available when defusing with enquos0(). For instance, trailing empty arguments are not automatically trimmed.

Usage

enexpr(arg)

exprs(
  ...,
  .named = FALSE,
  .ignore_empty = c("trailing", "none", "all"),
  .unquote_names = TRUE
)

enexprs(
  ...,
  .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
)

ensym(arg)

ensyms(
  ...,
  .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
)

quo(expr)

quos(
  ...,
  .named = FALSE,
  .ignore_empty = c("trailing", "none", "all"),
  .unquote_names = TRUE
)

enquo0(arg)

enquos0(...)

Arguments

Examples

# `exprs()` is the plural variant of `expr()`
exprs(foo, bar, bar)

# `quo()` and `quos()` are the quosure variants of `expr()` and `exprs()`
quo(foo)
quos(foo, bar)

# `enexpr()` and `enexprs()` are the naked variants of `enquo()` and `enquos()`
my_function1 <- function(arg) enexpr(arg)
my_function2 <- function(arg, ...) enexprs(arg, ...)
my_function1(1 + 1)
my_function2(1 + 1, 10 * 2)


# `ensym()` and `ensyms()` are symbol variants of `enexpr()` and `enexprs()`
my_function3 <- function(arg) ensym(arg)
my_function4 <- function(arg, ...) ensyms(arg, ...)

# The user must supply symbols
my_function3(foo)
my_function4(foo, bar)

# Complex expressions are an error
try(my_function3(1 + 1))
try(my_function4(1 + 1, 10 * 2))


# `enquo0()` and `enquos0()` disable injection operators
automatic_injection <- function(x) enquo(x)
no_injection <- function(x) enquo0(x)

automatic_injection(foo(!!!1:3))
no_injection(foo(!!!1:3))

# Injection can still be done explicitly
inject(no_injection(foo(!!!1:3)))

Development notes - dots.R

Description

Development notes - dots.R

.__error_call__. flag in dots collectors

Dots collectors like dots_list() are a little tricky because they may error out in different situations. Do we want to forward the context, i.e. set the call flag to the calling environment? Collectors throw errors in these cases:

1. While checking their own parameters, in which case the relevant context is the collector itself and we don't forward.

2. While collecting the dots, during evaluation of the supplied arguments. In this case forwarding or not is irrelevant because expressions in ... are evaluated in their own environment which is not connected to the collector's context.

3. While collecting the dots, during argument constraints checks such as determined by the .homonyms argument. In this case we want to forward the context because the caller of the dots collector is the one who determines the constraints for its users.

Box a final value for early termination

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)

.data and .env pronouns

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.

How many arguments are currently forwarded in dots?

Description

This returns the number of arguments currently forwarded in ... as an integer.

Usage

dots_n(...)

Arguments

Examples

fn <- function(...) dots_n(..., baz)
fn(foo, bar)

Splice lists

Description

dots_splice() is like dots_list() but automatically splices list inputs.

Usage

dots_splice(
  ...,
  .ignore_empty = c("trailing", "none", "all"),
  .preserve_empty = FALSE,
  .homonyms = c("keep", "first", "last", "error"),
  .check_assign = FALSE
)

Arguments

Evaluate dots with preliminary splicing

Description

This is a tool for advanced users. It captures dots, processes unquoting and splicing operators, and evaluates them. Unlike dots_list(), it does not flatten spliced objects, instead they are attributed a spliced class (see splice()). You can process spliced objects manually, perhaps with a custom predicate (see flatten_if()).

Usage

dots_values(
  ...,
  .ignore_empty = c("trailing", "none", "all"),
  .preserve_empty = FALSE,
  .homonyms = c("keep", "first", "last", "error"),
  .check_assign = FALSE
)

Arguments

Examples

dots <- dots_values(!!! list(1, 2), 3)
dots

# Flatten the objects marked as spliced:
flatten_if(dots, is_spliced)

Duplicate an R object

Description

duplicate() is an interface to the C-level duplicate() and shallow_duplicate() functions. It is mostly meant for users of the C API of R, e.g. for debugging, experimenting, or prototyping C code in R.

Usage

duplicate(x, shallow = FALSE)

Arguments

See Also

pairlist

Dynamic dots features

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")
}

Embrace operator ⁠{{⁠

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

Get the empty environment

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())

Defuse function arguments with glue

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)

Defuse function arguments

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)

Add backtrace from error handler

Description

entrace() is a low level function. See global_entrace() for a user-friendly way of enriching errors and other conditions from your RProfile.

• entrace() is meant to be used as a global handler. It enriches conditions with a backtrace. Errors are saved to last_error() and rethrown immediately. Messages and warnings are recorded into last_messages() and last_warnings() and let through.

• cnd_entrace() adds a backtrace to a condition object, without any other effect. It should be called from a condition handler.

entrace() also works as an option(error = ) handler for compatibility with versions of R older than 4.0.

When used as calling handler, rlang trims the handler invokation context from the backtrace.

Usage

entrace(cnd, ..., top = NULL, bottom = NULL)

cnd_entrace(cnd, ..., top = NULL, bottom = NULL)

Arguments

See Also

global_entrace() for configuring errors with entrace(). cnd_entrace() to manually add a backtrace to a condition.

Examples

quote({  # Not run

# Set `entrace()` globally in your RProfile
globalCallingHandlers(error = rlang::entrace)

# On older R versions which don't feature `globalCallingHandlers`,
# set the error handler like this:
options(error = rlang::entrace)

})

Create a new environment

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"))

Bind symbols to objects in an environment

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

What kind of environment binding?

Description

Usage

env_binding_are_active(env, nms = NULL)

env_binding_are_lazy(env, nms = NULL)

Arguments

Value

A logical vector as long as nms and named after it.

Lock or unlock environment bindings

Description

Locked environment bindings trigger an error when an attempt is made to redefine the binding.

Usage

env_binding_lock(env, nms = NULL)

env_binding_unlock(env, nms = NULL)

env_binding_are_locked(env, nms = NULL)

Arguments

Value

env_binding_are_unlocked() returns a logical vector as long as nms and named after it. env_binding_lock() and env_binding_unlock() return the old value of env_binding_are_unlocked() invisibly.

See Also

env_lock() for locking an environment.

Examples

# Bindings are unlocked by default:
env <- env(a = "A", b = "B")
env_binding_are_locked(env)

# But can optionally be locked:
env_binding_lock(env, "a")
env_binding_are_locked(env)

# If run, the following would now return an error because `a` is locked:
# env_bind(env, a = "foo")
# with_env(env, a <- "bar")

# Let's unlock it. Note that the return value indicate which
# bindings were locked:
were_locked <- env_binding_unlock(env)
were_locked

# Now that it is unlocked we can modify it again:
env_bind(env, a = "foo")
with_env(env, a <- "bar")
env$a

Browse environments

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.

Mask bindings by defining symbols deeper in a scope

Description

This function is superseded. Please use env() (and possibly set_env() if you're masking the bindings for another object like a closure or a formula) instead.

env_bury() is like env_bind() but it creates the bindings in a new child environment. This makes sure the new bindings have precedence over old ones, without altering existing environments. Unlike env_bind(), this function does not have side effects and returns a new environment (or object wrapping that environment).

Usage

env_bury(.env, ...)

Arguments

Value

A copy of .env enclosing the new environment containing bindings to ... arguments.

See Also

env_bind(), env_unbind()

Examples

orig_env <- env(a = 10)
fn <- set_env(function() a, orig_env)

# fn() currently sees `a` as the value `10`:
fn()

# env_bury() will bury the current scope of fn() behind a new
# environment:
fn <- env_bury(fn, a = 1000)
fn()

# Even though the symbol `a` is still defined deeper in the scope:
orig_env$a

Cache a value in an environment

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

Clone or coalesce an environment

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)

Depth of an environment chain

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"))

Get an object in an environment

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")

Does an environment have or see bindings?

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)

Does environment inherit from another environment?

Description

This returns TRUE if x has ancestor among its parents.

Usage

env_inherits(env, ancestor)

Arguments

Is frame environment user facing?

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())

Lock an environment

Description

Locked environments cannot be modified. An important example is namespace environments which are locked by R when loaded in a session. Once an environment is locked it normally cannot be unlocked.

Note that only the environment as a container is locked, not the individual bindings. You can't remove or add a binding but you can still modify the values of existing bindings. See env_binding_lock() for locking individual bindings.

Usage

env_lock(env)

env_is_locked(env)

Arguments

Value

The old value of env_is_locked() invisibly.

See Also

env_binding_lock()

Examples

# New environments are unlocked by default:
env <- env(a = 1)
env_is_locked(env)

# Use env_lock() to lock them:
env_lock(env)
env_is_locked(env)

# Now that `env` is locked, it is no longer possible to remove or
# add bindings. If run, the following would fail:
# env_unbind(env, "a")
# env_bind(env, b = 2)

# Note that even though the environment as a container is locked,
# the individual bindings are still unlocked and can be modified:
env$a <- 10

Label of an environment

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())

Names and numbers of symbols bound in an environment

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)

Get parent environments

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())

Poke an object in an environment

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.

Pretty-print an environment

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

Remove bindings from an environment

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)

Unlock an environment

Description

This function should only be used in development tools or interactively.

Usage

env_unlock(env)

Arguments

Value

Whether the environment has been unlocked.

Evaluate an expression in an environment

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)

Evaluate an expression with quosures and pronoun support

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)

Execute a function

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)

Defuse an R expression

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)))

Process unquote operators in a captured expression

Description

expr_interp() is deprecated, please use inject() instead.

Usage

expr_interp(x, env = NULL)

Arguments

Turn an expression to a label

Description

expr_text() turns the expression into a single string, which might be multi-line. expr_name() is suitable for formatting names. It works best with symbols and scalar types, but also accepts calls. expr_label() formats the expression nicely for use in messages.

Usage

expr_label(expr)

expr_name(expr)

expr_text(expr, width = 60L, nlines = Inf)

Arguments

Examples

# To labellise a function argument, first capture it with
# substitute():
fn <- function(x) expr_label(substitute(x))
fn(x:y)

# Strings are encoded
expr_label("a\nb")

# Names and expressions are quoted with ``
expr_label(quote(x))
expr_label(quote(a + b + c))

# Long expressions are collapsed
expr_label(quote(foo({
  1 + 2
  print(x)
})))

Print an expression

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)

Ensure that all elements of a list of expressions are named

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

Get or set formula components

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)

Turn RHS of formula into a string or label

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)
}))

Global options for rlang

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.

Internal API for standalone-types-check

Description

Internal API for standalone-types-check

Flatten or squash a list of lists into a simpler vector

Description

These functions are deprecated in favour of purrr::list_c() and purrr::list_flatten().

flatten() removes one level hierarchy from a list, while squash() removes all levels. These functions are similar to unlist() but they are type-stable so you always know what the type of the output is.

Usage

flatten(x)

flatten_lgl(x)

flatten_int(x)

flatten_dbl(x)

flatten_cpl(x)

flatten_chr(x)

flatten_raw(x)

squash(x)

squash_lgl(x)

squash_int(x)

squash_dbl(x)

squash_cpl(x)

squash_chr(x)

squash_raw(x)

flatten_if(x, predicate = is_spliced)

squash_if(x, predicate = is_spliced)

Arguments

Value

flatten() returns a list, flatten_lgl() a logical vector, flatten_int() an integer vector, flatten_dbl() a double vector, and flatten_chr() a character vector. Similarly for squash() and the typed variants (squash_lgl() etc).

Examples

x <- replicate(2, sample(4), simplify = FALSE)
x

flatten(x)
flatten_int(x)

# With flatten(), only one level gets removed at a time:
deep <- list(1, list(2, list(3)))
flatten(deep)
flatten(flatten(deep))

# But squash() removes all levels:
squash(deep)
squash_dbl(deep)

# The typed flatten functions remove one level and coerce to an atomic
# vector at the same time:
flatten_dbl(list(1, list(2)))

# Only bare lists are flattened, but you can splice S3 lists
# explicitly:
foo <- set_attrs(list("bar"), class = "foo")
str(flatten(list(1, foo, list(100))))
str(flatten(list(1, splice(foo), list(100))))

# Instead of splicing manually, flatten_if() and squash_if() let
# you specify a predicate function:
is_foo <- function(x) inherits(x, "foo") || is_bare_list(x)
str(flatten_if(list(1, foo, list(100)), is_foo))

# squash_if() does the same with deep lists:
deep_foo <- list(1, list(foo, list(foo, 100)))
str(deep_foo)

str(squash(deep_foo))
str(squash_if(deep_foo, is_foo))

Get or set function body

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))

Return the closure environment of a function

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)

Extract arguments from a function

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()

Format bullets for error messages

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")))

Validate and format a function call for use in error messages

Description

• error_call() takes either a frame environment or a call. If the input is an environment, error_call() acts like frame_call() with some additional logic, e.g. for S3 methods and for frames with a local_error_call().

• format_error_call() simplifies its input to a simple call (see section below) and formats the result as code (using cli if available). Use this function to generate the "in" part of an error message from a stack frame call.

  format_error_call() first passes its input to error_call() to fetch calls from frame environments.

Usage

format_error_call(call)

error_call(call)

Arguments

Value

Either a string formatted as code or NULL if a simple call could not be generated.

Details of formatting

• The arguments of function calls are stripped.

• Complex function calls containing inlined objects return NULL.

• Calls to if preserve the condition since it might be informative. Branches are dropped.

• Calls to operators and other special syntax are formatted using their names rather than the potentially confusing function form.

Examples

# Arguments are stripped
writeLines(format_error_call(quote(foo(bar, baz))))

# Returns `NULL` with complex calls such as those that contain
# inlined functions
format_error_call(call2(list))

# Operators are formatted using their names rather than in
# function call form
writeLines(format_error_call(quote(1 + 2)))

Format a type for error messages

Description

friendly_type() is deprecated. Please use the standalone-friendly-type.R file instead.

Usage

friendly_type(type)

Arguments

Value

A string of the prettified type, qualified with an indefinite article.

Get or set the environment of an object

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)

Entrace unexpected errors

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).

Register default global handlers

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

Prompt user to install missing packages

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

Name injection with "{" and "{{"

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")

How long is an object?

Description

This is a function for the common task of testing the length of an object. It checks the length of an object in a non-generic way: base::length() methods are ignored.

Usage

has_length(x, n = NULL)

Arguments

Examples

has_length(list())
has_length(list(), 0)

has_length(letters)
has_length(letters, 20)
has_length(letters, 26)

Does an object have an element with this name?

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")

Hashing

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)

Does an object inherit from a set of classes?

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).

Usage

inherits_any(x, class)

inherits_all(x, class)

inherits_only(x, class)

Arguments

Examples

obj <- structure(list(), class = c("foo", "bar", "baz"))

# With the _any variant only one class must match:
inherits_any(obj, c("foobar", "bazbaz"))
inherits_any(obj, c("foo", "bazbaz"))

# With the _all variant all classes must match:
inherits_all(obj, c("foo", "bazbaz"))
inherits_all(obj, c("foo", "baz"))

# The order of classes must match as well:
inherits_all(obj, c("baz", "foo"))

# inherits_only() checks that the class vectors are identical:
inherits_only(obj, c("foo", "baz"))
inherits_only(obj, c("foo", "bar", "baz"))

Inject objects in an R expression

Description

inject() evaluates an expression with injection support. There are three main usages:

• Splicing lists of arguments in a function call.

• Inline objects or other expressions in an expression with ⁠!!⁠ and ⁠!!!⁠. For instance to create functions or formulas programmatically.

• Pass arguments to NSE functions that defuse their arguments without injection support (see for instance enquo0()). You can use {{ arg }} with functions documented to support quosures. Otherwise, use !!enexpr(arg).

Usage

inject(expr, env = caller_env())

Arguments

Examples

# inject() simply evaluates its argument with injection
# support. These expressions are equivalent:
2 * 3
inject(2 * 3)
inject(!!2 * !!3)

# Injection with `!!` can be useful to insert objects or
# expressions within other expressions, like formulas:
lhs <- sym("foo")
rhs <- sym("bar")
inject(!!lhs ~ !!rhs + 10)

# Injection with `!!!` splices lists of arguments in function
# calls:
args <- list(na.rm = TRUE, finite = 0.2)
inject(mean(1:10, !!!args))

Injection operator ⁠!!⁠

Description

The injection operator ⁠!!⁠ injects a value or expression inside another expression. In other words, it modifies a piece of code before R evaluates it.

There are two main cases for injection. You can inject constant values to work around issues of scoping ambiguity, and you can inject defused expressions like symbolised column names.

Where does ⁠!!⁠ work?

⁠!!⁠ does not work everywhere, you can only use it within certain special functions:

• Functions taking defused and data-masked arguments.

  Technically, this means function arguments defused with {{ or en-prefixed operators like enquo(), enexpr(), etc.

• Inside inject().

All data-masking verbs in the tidyverse support injection operators out of the box. With base functions, you need to use inject() to enable ⁠!!⁠. Using ⁠!!⁠ out of context may lead to incorrect results, see What happens if I use injection operators out of context?.

The examples below are built around the base function with(). Since it's not a tidyverse function we will use inject() to enable ⁠!!⁠ usage.

Injecting values

Data-masking functions like with() are handy because you can refer to column names in your computations. This comes at the price of data mask ambiguity: if you have defined an env-variable of the same name as a data-variable, you get a name collisions. This collision is always resolved by giving precedence to the data-variable (it masks the env-variable):

cyl <- c(100, 110)
with(mtcars, mean(cyl))
#> [1] 6.1875

The injection operator offers one way of solving this. Use it to inject the env-variable inside the data-masked expression:

inject(
  with(mtcars, mean(!!cyl))
)
#> [1] 105

Note that the .env pronoun is a simpler way of solving the ambiguity. See The data mask ambiguity for more about this.

Injecting expressions

Injection is also useful for modifying parts of a defused expression. In the following example we use the symbolise-and-inject pattern to inject a column name inside a data-masked expression.

var <- sym("cyl")
inject(
  with(mtcars, mean(!!var))
)
#> [1] 6.1875

Since with() is a base function, you can't inject quosures, only naked symbols and calls. This isn't a problem here because we're injecting the name of a data frame column. If the environment is important, try injecting a pre-computed value instead.

When do I need ⁠!!⁠?

With tidyverse APIs, injecting expressions with ⁠!!⁠ is no longer a common pattern. First, the .env pronoun solves the ambiguity problem in a more intuitive way:

cyl <- 100
mtcars %>% dplyr::mutate(cyl = cyl * .env$cyl)

Second, the embrace operator {{ makes the defuse-and-inject pattern easier to learn and use.

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

# Equivalent to
my_mean <- function(data, var) {
  data %>% dplyr::summarise(mean(!!enquo(var)))
}

⁠!!⁠ is a good tool to learn for advanced applications but our hope is that it isn't needed for common data analysis cases.

See Also

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

• Metaprogramming patterns

Simulate interrupt condition

Description

interrupt() simulates a user interrupt of the kind that is signalled with Ctrl-C. It is currently not possible to create custom interrupt condition objects.

Usage

interrupt()

Invoke a function with a list of arguments

Description

Deprecated in rlang 0.4.0 in favour of exec().

Usage

invoke(.fn, .args = list(), ..., .env = caller_env(), .bury = c(".fn", ""))

Arguments

Is object a call?

Description

This function tests if x is a call. This is a pattern-matching predicate that returns FALSE if name and n are supplied and the call does not match these properties.

Usage

is_call(x, name = NULL, n = NULL, ns = NULL)

Arguments

See Also

is_expression()

Examples

is_call(quote(foo(bar)))

# You can pattern-match the call with additional arguments:
is_call(quote(foo(bar)), "foo")
is_call(quote(foo(bar)), "bar")
is_call(quote(foo(bar)), quote(foo))

# Match the number of arguments with is_call():
is_call(quote(foo(bar)), "foo", 1)
is_call(quote(foo(bar)), "foo", 2)


# By default, namespaced calls are tested unqualified:
ns_expr <- quote(base::list())
is_call(ns_expr, "list")

# You can also specify whether the call shouldn't be namespaced by
# supplying an empty string:
is_call(ns_expr, "list", ns = "")

# Or if it should have a namespace:
is_call(ns_expr, "list", ns = "utils")
is_call(ns_expr, "list", ns = "base")

# You can supply multiple namespaces:
is_call(ns_expr, "list", ns = c("utils", "base"))
is_call(ns_expr, "list", ns = c("utils", "stats"))

# If one of them is "", unnamespaced calls will match as well:
is_call(quote(list()), "list", ns = "base")
is_call(quote(list()), "list", ns = c("base", ""))
is_call(quote(base::list()), "list", ns = c("base", ""))


# The name argument is vectorised so you can supply a list of names
# to match with:
is_call(quote(foo(bar)), c("bar", "baz"))
is_call(quote(foo(bar)), c("bar", "foo"))
is_call(quote(base::list), c("::", ":::", "$", "@"))

Is an object callable?

Description

A callable object is an object that can appear in the function position of a call (as opposed to argument position). This includes symbolic objects that evaluate to a function or literal functions embedded in the call.

Usage

is_callable(x)

Arguments

Details

Note that strings may look like callable objects because expressions of the form "list"() are valid R code. However, that's only because the R parser transforms strings to symbols. It is not legal to manually set language heads to strings.

Examples

# Symbolic objects and functions are callable:
is_callable(quote(foo))
is_callable(base::identity)

# node_poke_car() lets you modify calls without any checking:
lang <- quote(foo(10))
node_poke_car(lang, current_env())

# Use is_callable() to check an input object is safe to put as CAR:
obj <- base::identity

if (is_callable(obj)) {
  lang <- node_poke_car(lang, obj)
} else {
  abort("`obj` must be callable")
}

eval_bare(lang)

Is object a condition?

Description

Is object a condition?

Usage

is_condition(x)

is_error(x)

is_warning(x)

is_message(x)

Arguments

Is an object copyable?

Description

When an object is modified, R generally copies it (sometimes lazily) to enforce value semantics. However, some internal types are uncopyable. If you try to copy them, either with ⁠<-⁠ or by argument passing, you actually create references to the original object rather than actual copies. Modifying these references can thus have far reaching side effects.

Usage

is_copyable(x)

Arguments

Examples

# Let's add attributes with structure() to uncopyable types. Since
# they are not copied, the attributes are changed in place:
env <- env()
structure(env, foo = "bar")
env

# These objects that can only be changed with side effect are not
# copyable:
is_copyable(env)

structure(base::list, foo = "bar")
str(base::list)

Is a vector uniquely named?

Description

Like is_named() but also checks that names are unique.

Usage

is_dictionaryish(x)

Arguments

Is object an empty vector or NULL?

Description

Is object an empty vector or NULL?

Usage

is_empty(x)

Arguments

Examples

is_empty(NULL)
is_empty(list())
is_empty(list(NULL))

Is object an environment?

Description

is_bare_environment() tests whether x is an environment without a s3 or s4 class.

Usage

is_environment(x)

is_bare_environment(x)

Arguments

Is an object an expression?

Description

In rlang, an expression is the return type of parse_expr(), the set of objects that can be obtained from parsing R code. Under this definition expressions include numbers, strings, NULL, symbols, and function calls. These objects can be classified as:

• Symbolic objects, i.e. symbols and function calls (for which is_symbolic() returns TRUE)

• Syntactic literals, i.e. scalar atomic objects and NULL (testable with is_syntactic_literal())

is_expression() returns TRUE if the input is either a symbolic object or a syntactic literal. If a call, the elements of the call must all be expressions as well. Unparsable calls are not considered expressions in this narrow definition.

Note that in base R, there exists expression() vectors, a data type similar to a list that supports special attributes created by the parser called source references. This data type is not supported in rlang.

Usage

is_expression(x)

is_syntactic_literal(x)

is_symbolic(x)

Arguments

Details

is_symbolic() returns TRUE for symbols and calls (objects with type language). Symbolic objects are replaced by their value during evaluation. Literals are the complement of symbolic objects. They are their own value and return themselves during evaluation.

is_syntactic_literal() is a predicate that returns TRUE for the subset of literals that are created by R when parsing text (see parse_expr()): numbers, strings and NULL. Along with symbols, these literals are the terminating nodes in an AST.

Note that in the most general sense, a literal is any R object that evaluates to itself and that can be evaluated in the empty environment. For instance, quote(c(1, 2)) is not a literal, it is a call. However, the result of evaluating it in base_env() is a literal(in this case an atomic vector).

As the data structure for function arguments, pairlists are also a kind of language objects. However, since they are mostly an internal data structure and can't be returned as is by the parser, is_expression() returns FALSE for pairlists.

See Also

is_call() for a call predicate.

Examples

q1 <- quote(1)
is_expression(q1)
is_syntactic_literal(q1)

q2 <- quote(x)
is_expression(q2)
is_symbol(q2)

q3 <- quote(x + 1)
is_expression(q3)
is_call(q3)


# Atomic expressions are the terminating nodes of a call tree:
# NULL or a scalar atomic vector:
is_syntactic_literal("string")
is_syntactic_literal(NULL)

is_syntactic_literal(letters)
is_syntactic_literal(quote(call()))

# Parsable literals have the property of being self-quoting:
identical("foo", quote("foo"))
identical(1L, quote(1L))
identical(NULL, quote(NULL))

# Like any literals, they can be evaluated within the empty
# environment:
eval_bare(quote(1L), empty_env())

# Whereas it would fail for symbolic expressions:
# eval_bare(quote(c(1L, 2L)), empty_env())


# Pairlists are also language objects representing argument lists.
# You will usually encounter them with extracted formals:
fmls <- formals(is_expression)
typeof(fmls)

# Since they are mostly an internal data structure, is_expression()
# returns FALSE for pairlists, so you will have to check explicitly
# for them:
is_expression(fmls)
is_pairlist(fmls)

Is object a formula?

Description

is_formula() tests whether x is a call to ~. is_bare_formula() tests in addition that x does not inherit from anything else than "formula".

Note: When we first implemented is_formula(), we thought it best to treat unevaluated formulas as formulas by default (see section below). Now we think this default introduces too many edge cases in normal code. We recommend always supplying scoped = TRUE. Unevaluated formulas can be handled via a is_call(x, "~") branch.

Usage

is_formula(x, scoped = NULL, lhs = NULL)

is_bare_formula(x, scoped = TRUE, lhs = NULL)

Arguments

Dealing with unevaluated formulas

At parse time, a formula is a simple call to ~ and it does not have a class or an environment. Once evaluated, the ~ call becomes a properly structured formula. Unevaluated formulas arise by quotation, e.g. ~~foo, quote(~foo), or substitute(arg) with arg being supplied a formula. Use the scoped argument to check whether the formula carries an environment.

Examples

is_formula(~10)
is_formula(10)

# If you don't supply `lhs`, both one-sided and two-sided formulas
# will return `TRUE`
is_formula(disp ~ am)
is_formula(~am)

# You can also specify whether you expect a LHS:
is_formula(disp ~ am, lhs = TRUE)
is_formula(disp ~ am, lhs = FALSE)
is_formula(~am, lhs = TRUE)
is_formula(~am, lhs = FALSE)

# Handling of unevaluated formulas is a bit tricky. These formulas
# are special because they don't inherit from `"formula"` and they
# don't carry an environment (they are not scoped):
f <- quote(~foo)
f_env(f)

# By default unevaluated formulas are treated as formulas
is_formula(f)

# Supply `scoped = TRUE` to ensure you have an evaluated formula
is_formula(f, scoped = TRUE)

# By default unevaluated formulas not treated as bare formulas
is_bare_formula(f)

# If you supply `scoped = TRUE`, they will be considered bare
# formulas even though they don't inherit from `"formula"`
is_bare_formula(f, scoped = TRUE)

Is object a function?

Description

The R language defines two different types of functions: primitive functions, which are low-level, and closures, which are the regular kind of functions.

Usage

is_function(x)

is_closure(x)

is_primitive(x)

is_primitive_eager(x)

is_primitive_lazy(x)

Arguments

Details

Closures are functions written in R, named after the way their arguments are scoped within nested environments (see https://en.wikipedia.org/wiki/Closure_(computer_programming)). The root environment of the closure is called the closure environment. When closures are evaluated, a new environment called the evaluation frame is created with the closure environment as parent. This is where the body of the closure is evaluated. These closure frames appear on the evaluation stack, as opposed to primitive functions which do not necessarily have their own evaluation frame and never appear on the stack.

Primitive functions are more efficient than closures for two reasons. First, they are written entirely in fast low-level code. Second, the mechanism by which they are passed arguments is more efficient because they often do not need the full procedure of argument matching (dealing with positional versus named arguments, partial matching, etc). One practical consequence of the special way in which primitives are passed arguments is that they technically do not have formal arguments, and formals() will return NULL if called on a primitive function. Finally, primitive functions can either take arguments lazily, like R closures do, or evaluate them eagerly before being passed on to the C code. The former kind of primitives are called "special" in R terminology, while the latter is referred to as "builtin". is_primitive_eager() and is_primitive_lazy() allow you to check whether a primitive function evaluates arguments eagerly or lazily.

You will also encounter the distinction between primitive and internal functions in technical documentation. Like primitive functions, internal functions are defined at a low level and written in C. However, internal functions have no representation in the R language. Instead, they are called via a call to base::.Internal() within a regular closure. This ensures that they appear as normal R function objects: they obey all the usual rules of argument passing, and they appear on the evaluation stack as any other closures. As a result, fn_fmls() does not need to look in the .ArgsEnv environment to obtain a representation of their arguments, and there is no way of querying from R whether they are lazy ('special' in R terminology) or eager ('builtin').

You can call primitive functions with .Primitive() and internal functions with .Internal(). However, calling internal functions in a package is forbidden by CRAN's policy because they are considered part of the private API. They often assume that they have been called with correctly formed arguments, and may cause R to crash if you call them with unexpected objects.

Examples

# Primitive functions are not closures:
is_closure(base::c)
is_primitive(base::c)

# On the other hand, internal functions are wrapped in a closure
# and appear as such from the R side:
is_closure(base::eval)

# Both closures and primitives are functions:
is_function(base::c)
is_function(base::eval)

# Many primitive functions evaluate arguments eagerly:
is_primitive_eager(base::c)
is_primitive_eager(base::list)
is_primitive_eager(base::`+`)

# However, primitives that operate on expressions, like quote() or
# substitute(), are lazy:
is_primitive_lazy(base::quote)
is_primitive_lazy(base::substitute)

Are packages installed in any of the libraries?

Description

These functions check that packages are installed with minimal side effects. If installed, the packages will be loaded but not attached.

• is_installed() doesn't interact with the user. It simply returns TRUE or FALSE depending on whether the packages are installed.

• In interactive sessions, check_installed() asks the user whether to install missing packages. If the user accepts, the packages are installed with pak::pkg_install() if available, or utils::install.packages() otherwise. If the session is non interactive or if the user chooses not to install the packages, the current evaluation is aborted.

You can disable the prompt by setting the rlib_restart_package_not_found global option to FALSE. In that case, missing packages always cause an error.

Usage

is_installed(pkg, ..., version = NULL, compare = NULL)

check_installed(
  pkg,
  reason = NULL,
  ...,
  version = NULL,
  compare = NULL,
  action = NULL,
  call = caller_env()
)

Arguments

Value

is_installed() returns TRUE if all package names provided in pkg are installed, FALSE otherwise. check_installed() either doesn't return or returns NULL.

Handling package not found errors

check_installed() signals error conditions of class rlib_error_package_not_found. The error includes pkg and version fields. They are vectorised and may include several packages.

The error is signalled with a rlib_restart_package_not_found restart on the stack to allow handlers to install the required packages. To do so, add a calling handler for rlib_error_package_not_found, install the required packages, and invoke the restart without arguments. This restarts the check from scratch.

The condition is not signalled in non-interactive sessions, in the restarting case, or if the rlib_restart_package_not_found user option is set to FALSE.

Examples

is_installed("utils")
is_installed(c("base", "ggplot5"))
is_installed(c("base", "ggplot5"), version = c(NA, "5.1.0"))

Is a vector integer-like?

Description

These predicates check whether R considers a number vector to be integer-like, according to its own tolerance check (which is in fact delegated to the C library). This function is not adapted to data analysis, see the help for base::is.integer() for examples of how to check for whole numbers.

Things to consider when checking for integer-like doubles:

• This check can be expensive because the whole double vector has to be traversed and checked.

• Large double values may be integerish but may still not be coercible to integer. This is because integers in R only support values up to 2^31 - 1 while numbers stored as double can be much larger.

Usage

is_integerish(x, n = NULL, finite = NULL)

is_bare_integerish(x, n = NULL, finite = NULL)

is_scalar_integerish(x, finite = NULL)

Arguments

See Also

is_bare_numeric() for testing whether an object is a base numeric type (a bare double or integer vector).

Examples

is_integerish(10L)
is_integerish(10.0)
is_integerish(10.0, n = 2)
is_integerish(10.000001)
is_integerish(TRUE)

Is R running interactively?

Description

Like base::interactive(), is_interactive() returns TRUE when the function runs interactively and FALSE when it runs in batch mode. It also checks, in this order:

• The rlang_interactive global option. If set to a single TRUE or FALSE, is_interactive() returns that value immediately. This escape hatch is useful in unit tests or to manually turn on interactive features in RMarkdown outputs.

• Whether knitr or testthat is in progress, in which case is_interactive() returns FALSE.

with_interactive() and local_interactive() set the global option conveniently.

Usage

is_interactive()

local_interactive(value = TRUE, frame = caller_env())

with_interactive(expr, value = TRUE)

Arguments

Is object a call?

Description

These functions are deprecated, please use is_call() and its n argument instead.

Usage

is_lang(x, name = NULL, n = NULL, ns = NULL)

Arguments

Is object named?

Description

• is_named() is a scalar predicate that checks that x has a names attribute and that none of the names are missing or empty (NA or "").

• is_named2() is like is_named() but always returns TRUE for empty vectors, even those that don't have a names attribute. In other words, it tests for the property that each element of a vector is named. is_named2() composes well with names2() whereas is_named() composes with names().

• have_name() is a vectorised variant.

Usage

is_named(x)

is_named2(x)

have_name(x)

Arguments

Details

is_named() always returns TRUE for empty vectors because

Value

is_named() and is_named2() are scalar predicates that return TRUE or FALSE. have_name() is vectorised and returns a logical vector as long as the input.

Examples

# is_named() is a scalar predicate about the whole vector of names:
is_named(c(a = 1, b = 2))
is_named(c(a = 1, 2))

# Unlike is_named2(), is_named() returns `FALSE` for empty vectors
# that don't have a `names` attribute.
is_named(list())
is_named2(list())

# have_name() is a vectorised predicate
have_name(c(a = 1, b = 2))
have_name(c(a = 1, 2))

# Empty and missing names are treated as invalid:
invalid <- set_names(letters[1:5])
names(invalid)[1] <- ""
names(invalid)[3] <- NA

is_named(invalid)
have_name(invalid)

# A data frame normally has valid, unique names
is_named(mtcars)
have_name(mtcars)

# A matrix usually doesn't because the names are stored in a
# different attribute
mat <- matrix(1:4, 2)
colnames(mat) <- c("a", "b")
is_named(mat)
names(mat)

Is an object a namespace environment?

Description

Is an object a namespace environment?

Usage

is_namespace(x)

Arguments

Is object a node or pairlist?

Description

• is_pairlist() checks that x has type pairlist.

• is_node() checks that x has type pairlist or language. It tests whether x is a node that has a CAR and a CDR, including callable nodes (language objects).

• is_node_list() checks that x has type pairlist or NULL. NULL is the empty node list.

Usage

is_pairlist(x)

is_node(x)

is_node_list(x)

Arguments

Life cycle

These functions are experimental. We are still figuring out a good naming convention to refer to the different lisp-like lists in R.

See Also

is_call() tests for language nodes.

Is an object referencing another?

Description

There are typically two situations where two symbols may refer to the same object.

• R objects usually have copy-on-write semantics. This is an optimisation that ensures that objects are only copied if needed. When you copy a vector, no memory is actually copied until you modify either the original object or the copy is modified.

  Note that the copy-on-write optimisation is an implementation detail that is not guaranteed by the specification of the R language.

• Assigning an uncopyable object (like an environment) creates a reference. These objects are never copied even if you modify one of the references.

Usage

is_reference(x, y)

Arguments

Examples

# Reassigning an uncopyable object such as an environment creates a
# reference:
env <- env()
ref <- env
is_reference(ref, env)

# Due to copy-on-write optimisation, a copied vector can
# temporarily reference the original vector:
vec <- 1:10
copy <- vec
is_reference(copy, vec)

# Once you modify on of them, the copy is triggered in the
# background and the objects cease to reference each other:
vec[[1]] <- 100
is_reference(copy, vec)

Is object a symbol?

Description

Is object a symbol?

Usage

is_symbol(x, name = NULL)

Arguments

Is object identical to TRUE or FALSE?

Description

These functions bypass R's automatic conversion rules and check that x is literally TRUE or FALSE.

Usage

is_true(x)

is_false(x)

Arguments

Examples

is_true(TRUE)
is_true(1)

is_false(FALSE)
is_false(0)

Is object a weak reference?

Description

Is object a weak reference?

Usage

is_weakref(x)

Arguments

Create a call

Description

These functions are deprecated, please use call2() and new_call() instead.

Usage

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

Arguments

Last abort() error

Description

• last_error() returns the last error entraced by abort() or global_entrace(). The error is printed with a backtrace in simplified form.

• last_trace() is a shortcut to return the backtrace stored in the last error. This backtrace is printed in full form.

Usage

last_error()

last_trace(drop = NULL)

Arguments

See Also

• rlang_backtrace_on_error to control what is displayed when an error is thrown.

• global_entrace() to enable last_error() logging for all errors.

• last_warnings() and last_messages().

Display last messages and warnings

Description

last_warnings() and last_messages() return a list of all warnings and messages that occurred during the last R command.

global_entrace() must be active in order to log the messages and warnings.

By default the warnings and messages are printed with a simplified backtrace, like last_error(). Use summary() to print the conditions with a full backtrace.

Usage

last_warnings(n = NULL)

last_messages(n = NULL)

Arguments

Examples

Enable backtrace capture with global_entrace():

global_entrace()

Signal some warnings in nested functions. The warnings inform about which function emitted a warning but they don't provide information about the call stack:

f <- function() { warning("foo"); g() }
g <- function() { warning("bar", immediate. = TRUE); h() }
h <- function() warning("baz")

f()
#> Warning in g() : bar
#> Warning messages:
#> 1: In f() : foo
#> 2: In h() : baz

Call last_warnings() to see backtraces for each of these warnings:

last_warnings()
#> [[1]]
#> <warning/rlang_warning>
#> Warning in `f()`:
#> foo
#> Backtrace:
#>     x
#>  1. \-global f()
#>
#> [[2]]
#> <warning/rlang_warning>
#> Warning in `g()`:
#> bar
#> Backtrace:
#>     x
#>  1. \-global f()
#>  2.   \-global g()
#>
#> [[3]]
#> <warning/rlang_warning>
#> Warning in `h()`:
#> baz
#> Backtrace:
#>     x
#>  1. \-global f()
#>  2.   \-global g()
#>  3.     \-global h()

This works similarly with messages:

f <- function() { inform("Hey!"); g() }
g <- function() { inform("Hi!"); h() }
h <- function() inform("Hello!")

f()
#> Hey!
#> Hi!
#> Hello!

rlang::last_messages()
#> [[1]]
#> <message/rlang_message>
#> Message:
#> Hey!
#> ---
#> Backtrace:
#>     x
#>  1. \-global f()
#>
#> [[2]]
#> <message/rlang_message>
#> Message:
#> Hi!
#> ---
#> Backtrace:
#>     x
#>  1. \-global f()
#>  2.   \-global g()
#>
#> [[3]]
#> <message/rlang_message>
#> Message:
#> Hello!
#> ---
#> Backtrace:
#>     x
#>  1. \-global f()
#>  2.   \-global g()
#>  3.     \-global h()

See Also

last_error()

Collect dynamic dots in a list

Description

list2(...) is equivalent to list(...) with a few additional features, collectively called dynamic dots. While list2() hard-code these features, dots_list() is a lower-level version that offers more control.

Usage

list2(...)

dots_list(
  ...,
  .named = FALSE,
  .ignore_empty = c("trailing", "none", "all"),
  .preserve_empty = FALSE,
  .homonyms = c("keep", "first", "last", "error"),
  .check_assign = FALSE
)

Arguments

Details

For historical reasons, dots_list() creates a named list by default. By comparison list2() implements the preferred behaviour of only creating a names vector when a name is supplied.

Value

A list containing the ... inputs.

Examples

# Let's create a function that takes a variable number of arguments:
numeric <- function(...) {
  dots <- list2(...)
  num <- as.numeric(dots)
  set_names(num, names(dots))
}
numeric(1, 2, 3)

# The main difference with list(...) is that list2(...) enables
# the `!!!` syntax to splice lists:
x <- list(2, 3)
numeric(1, !!! x, 4)

# As well as unquoting of names:
nm <- "yup!"
numeric(!!nm := 1)


# One useful application of splicing is to work around exact and
# partial matching of arguments. Let's create a function taking
# named arguments and dots:
fn <- function(data, ...) {
  list2(...)
}

# You normally cannot pass an argument named `data` through the dots
# as it will match `fn`'s `data` argument. The splicing syntax
# provides a workaround:
fn("wrong!", data = letters)  # exact matching of `data`
fn("wrong!", dat = letters)   # partial matching of `data`
fn(some_data, !!!list(data = letters))  # no matching

# Empty trailing arguments are allowed:
list2(1, )

# But non-trailing empty arguments cause an error:
try(list2(1, , ))

# Use the more configurable `dots_list()` function to preserve all
# empty arguments:
list3 <- function(...) dots_list(..., .preserve_empty = TRUE)

# Note how the last empty argument is still ignored because
# `.ignore_empty` defaults to "trailing":
list3(1, , )

# The list with preserved empty arguments is equivalent to:
list(1, missing_arg())


# Arguments with duplicated names are kept by default:
list2(a = 1, a = 2, b = 3, b = 4, 5, 6)

# Use the `.homonyms` argument to keep only the first of these:
dots_list(a = 1, a = 2, b = 3, b = 4, 5, 6, .homonyms = "first")

# Or the last:
dots_list(a = 1, a = 2, b = 3, b = 4, 5, 6, .homonyms = "last")

# Or raise an informative error:
try(dots_list(a = 1, a = 2, b = 3, b = 4, 5, 6, .homonyms = "error"))


# dots_list() can be configured to warn when a `<-` call is
# detected:
my_list <- function(...) dots_list(..., .check_assign = TRUE)
my_list(a <- 1)

# There is no warning if the assignment is wrapped in braces.
# This requires users to be explicit about their intent:
my_list({ a <- 1 })

Temporarily change bindings of an environment

Description

• local_bindings() temporarily changes bindings in .env (which is by default the caller environment). The bindings are reset to their original values when the current frame (or an arbitrary one if you specify .frame) goes out of scope.

• with_bindings() evaluates expr with temporary bindings. When with_bindings() returns, bindings are reset to their original values. It is a simple wrapper around local_bindings().

Usage

local_bindings(..., .env = .frame, .frame = caller_env())

with_bindings(.expr, ..., .env = caller_env())

Arguments

Value

local_bindings() returns the values of old bindings invisibly; with_bindings() returns the value of expr.

Examples

foo <- "foo"
bar <- "bar"

# `foo` will be temporarily rebinded while executing `expr`
with_bindings(paste(foo, bar), foo = "rebinded")
paste(foo, bar)

Set local error call in an execution environment

Description

local_error_call() is an alternative to explicitly passing a call argument to abort(). It sets the call (or a value that indicates where to find the call, see below) in a local binding that is automatically picked up by abort().

Usage

local_error_call(call, frame = caller_env())

Arguments

Motivation for setting local error calls

By default abort() uses the function call of its caller as context in error messages:

foo <- function() abort("Uh oh.")
foo()
#> Error in `foo()`: Uh oh.

This is not always appropriate. For example a function that checks an input on the behalf of another function should reference the latter, not the former:

arg_check <- function(arg,
                      error_arg = as_string(substitute(arg))) {
  abort(cli::format_error("{.arg {error_arg}} is failing."))
}

foo <- function(x) arg_check(x)
foo()
#> Error in `arg_check()`: `x` is failing.

The mismatch is clear in the example above. arg_check() does not have any x argument and so it is confusing to present arg_check() as being the relevant context for the failure of the x argument.

One way around this is to take a call or error_call argument and pass it to abort(). Here we name this argument error_call for consistency with error_arg which is prefixed because there is an existing arg argument. In other situations, taking arg and call arguments might be appropriate.

arg_check <- function(arg,
                      error_arg = as_string(substitute(arg)),
                      error_call = caller_env()) {
  abort(
    cli::format_error("{.arg {error_arg}} is failing."),
    call = error_call
  )
}

foo <- function(x) arg_check(x)
foo()
#> Error in `foo()`: `x` is failing.

This is the generally recommended pattern for argument checking functions. If you mention an argument in an error message, provide your callers a way to supply a different argument name and a different error call. abort() stores the error call in the call condition field which is then used to generate the "in" part of error messages.

In more complex cases it's often burdensome to pass the relevant call around, for instance if your checking and throwing code is structured into many different functions. In this case, use local_error_call() to set the call locally or instruct abort() to climb the call stack one level to find the relevant call. In the following example, the complexity is not so important that sparing the argument passing makes a big difference. However this illustrates the pattern:

arg_check <- function(arg,
                      error_arg = caller_arg(arg),
                      error_call = caller_env()) {
  # Set the local error call
  local_error_call(error_call)

  my_classed_stop(
    cli::format_error("{.arg {error_arg}} is failing.")
  )
}

my_classed_stop <- function(message) {
  # Forward the local error call to the caller's
  local_error_call(caller_env())

  abort(message, class = "my_class")
}

foo <- function(x) arg_check(x)
foo()
#> Error in `foo()`: `x` is failing.

Error call flags in performance-critical functions

The call argument can also be the string "caller". This is equivalent to caller_env() or parent.frame() but has a lower overhead because call stack introspection is only performed when an error is triggered. Note that eagerly calling caller_env() is fast enough in almost all cases.

If your function needs to be really fast, assign the error call flag directly instead of calling local_error_call():

.__error_call__. <- "caller"

Examples

# Set a context for error messages
function() {
  local_error_call(quote(foo()))
  local_error_call(sys.call())
}

# Disable the context
function() {
  local_error_call(NULL)
}

# Use the caller's context
function() {
  local_error_call(caller_env())
}

Change global options

Description

• local_options() changes options for the duration of a stack frame (by default the current one). Options are set back to their old values when the frame returns.

• with_options() changes options while an expression is evaluated. Options are restored when the expression returns.

• push_options() adds or changes options permanently.

• peek_option() and peek_options() return option values. The former returns the option directly while the latter returns a list.

Usage

local_options(..., .frame = caller_env())

with_options(.expr, ...)

push_options(...)

peek_options(...)

peek_option(name)

Arguments

Value

For local_options() and push_options(), the old option values. peek_option() returns the current value of an option while the plural peek_options() returns a list of current option values.

Life cycle

These functions are experimental.

Examples

# Store and retrieve a global option:
push_options(my_option = 10)
peek_option("my_option")

# Change the option temporarily:
with_options(my_option = 100, peek_option("my_option"))
peek_option("my_option")

# The scoped variant is useful within functions:
fn <- function() {
  local_options(my_option = 100)
  peek_option("my_option")
}
fn()
peek_option("my_option")

# The plural peek returns a named list:
peek_options("my_option")
peek_options("my_option", "digits")

Use cli to format error messages

Description

local_use_cli() marks a package namespace or the environment of a running function with a special flag that instructs abort() to use cli to format error messages. This formatting happens lazily, at print-time, in various places:

• When an unexpected error is displayed to the user.

• When a captured error is printed in the console, for instance via last_error().

• When conditionMessage() is called.

cli formats messages and bullets with indentation and width-wrapping to produce a polished display of messages.

Usage

local_use_cli(..., format = TRUE, inline = FALSE, frame = caller_env())

Arguments

Usage

To use cli formatting automatically in your package:

1. Make sure run_on_load() is called from your .onLoad() hook.

2. Call on_load(local_use_cli()) at the top level of your namespace.

It is also possible to call local_use_cli() inside a running function, in which case the flag only applies within that function.

Missing values

Description

Missing values are represented in R with the general symbol NA. They can be inserted in almost all data containers: all atomic vectors except raw vectors can contain missing values. To achieve this, R automatically converts the general NA symbol to a typed missing value appropriate for the target vector. The objects provided here are aliases for those typed NA objects.

Usage

na_lgl

na_int

na_dbl

na_chr

na_cpl

Format

An object of class logical of length 1.

An object of class integer of length 1.

An object of class numeric of length 1.

An object of class character of length 1.

An object of class complex of length 1.

Details

Typed missing values are necessary because R needs sentinel values of the same type (i.e. the same machine representation of the data) as the containers into which they are inserted. The official typed missing values are NA_integer_, NA_real_, NA_character_ and NA_complex_. The missing value for logical vectors is simply the default NA. The aliases provided in rlang are consistently named and thus simpler to remember. Also, na_lgl is provided as an alias to NA that makes intent clearer.

Since na_lgl is the default NA, expressions such as c(NA, NA) yield logical vectors as no data is available to give a clue of the target type. In the same way, since lists and environments can contain any types, expressions like list(NA) store a logical NA.

Life cycle

These shortcuts might be moved to the vctrs package at some point. This is why they are marked as questioning.

Examples

typeof(NA)
typeof(na_lgl)
typeof(na_int)

# Note that while the base R missing symbols cannot be overwritten,
# that's not the case for rlang's aliases:
na_dbl <- NA
typeof(na_dbl)

Generate or handle a missing argument

Description

These functions help using the missing argument as a regular R object.

• missing_arg() generates a missing argument.

• is_missing() is like base::missing() but also supports testing for missing arguments contained in other objects like lists. It is also more consistent with default arguments which are never treated as missing (see section below).

• maybe_missing() is useful to pass down an input that might be missing to another function, potentially substituting by a default value. It avoids triggering an "argument is missing" error.

Usage

missing_arg()

is_missing(x)

maybe_missing(x, default = missing_arg())

Arguments

Other ways to reify the missing argument

• base::quote(expr = ) is the canonical way to create a missing argument object.

• expr() called without argument creates a missing argument.

• quo() called without argument creates an empty quosure, i.e. a quosure containing the missing argument object.

is_missing() and default arguments

The base function missing() makes a distinction between default values supplied explicitly and default values generated through a missing argument:

fn <- function(x = 1) base::missing(x)

fn()
#> [1] TRUE
fn(1)
#> [1] FALSE

This only happens within a function. If the default value has been generated in a calling function, it is never treated as missing:

caller <- function(x = 1) fn(x)
caller()
#> [1] FALSE

rlang::is_missing() simplifies these rules by never treating default arguments as missing, even in internal contexts:

fn <- function(x = 1) rlang::is_missing(x)

fn()
#> [1] FALSE
fn(1)
#> [1] FALSE

This is a little less flexible because you can't specialise behaviour based on implicitly supplied default values. However, this makes the behaviour of is_missing() and functions using it simpler to understand.

Fragility of the missing argument object

The missing argument is an object that triggers an error if and only if it is the result of evaluating a symbol. No error is produced when a function call evaluates to the missing argument object. For instance, it is possible to bind the missing argument to a variable with an expression like x[[1]] <- missing_arg(). Likewise, x[[1]] is safe to use as argument, e.g. list(x[[1]]) even when the result is the missing object.

However, as soon as the missing argument is passed down between functions through a bare variable, it is likely to cause a missing argument error:

x <- missing_arg()
list(x)
#> Error:
#> ! argument "x" is missing, with no default

To work around this, is_missing() and maybe_missing(x) use a bit of magic to determine if the input is the missing argument without triggering a missing error.

x <- missing_arg()
list(maybe_missing(x))
#> [[1]]
#>

maybe_missing() is particularly useful for prototyping meta-programming algorithms in R. The missing argument is a likely input when computing on the language because it is a standard object in formals lists. While C functions are always allowed to return the missing argument and pass it to other C functions, this is not the case on the R side. If you're implementing your meta-programming algorithm in R, use maybe_missing() when an input might be the missing argument object.

Examples

# The missing argument usually arises inside a function when the
# user omits an argument that does not have a default:
fn <- function(x) is_missing(x)
fn()

# Creating a missing argument can also be useful to generate calls
args <- list(1, missing_arg(), 3, missing_arg())
quo(fn(!!! args))

# Other ways to create that object include:
quote(expr = )
expr()

# It is perfectly valid to generate and assign the missing
# argument in a list.
x <- missing_arg()
l <- list(missing_arg())

# Just don't evaluate a symbol that contains the empty argument.
# Evaluating the object `x` that we created above would trigger an
# error.
# x  # Not run

# On the other hand accessing a missing argument contained in a
# list does not trigger an error because subsetting is a function
# call:
l[[1]]
is.null(l[[1]])

# In case you really need to access a symbol that might contain the
# empty argument object, use maybe_missing():
maybe_missing(x)
is.null(maybe_missing(x))
is_missing(maybe_missing(x))


# Note that base::missing() only works on symbols and does not
# support complex expressions. For this reason the following lines
# would throw an error:

#> missing(missing_arg())
#> missing(l[[1]])

# while is_missing() will work as expected:
is_missing(missing_arg())
is_missing(l[[1]])

Inform about name repair

Description

Inform about name repair

Usage

names_inform_repair(old, new)

Arguments

Muffling and silencing messages

Name repair messages are signaled with inform() and are given the class "rlib_message_name_repair". These messages can be muffled with base::suppressMessages().

Name repair messages can also be silenced with the global option rlib_name_repair_verbosity. This option takes the values:

• "verbose": Always verbose.

• "quiet": Always quiet.

When set to quiet, the message is not displayed and the condition is not signaled. This is particularly useful for silencing messages during testing when combined with local_options().

Get names of a vector

Description

names2() always returns a character vector, even when an object does not have a names attribute. In this case, it returns a vector of empty names "". It also standardises missing names to "".

The replacement variant ⁠names2<-⁠ never adds NA names and instead fills unnamed vectors with "".

Usage

names2(x)

names2(x) <- value

Arguments

Examples

names2(letters)

# It also takes care of standardising missing names:
x <- set_names(1:3, c("a", NA, "b"))
names2(x)

# Replacing names with the base `names<-` function may introduce
# `NA` values when the vector is unnamed:
x <- 1:3
names(x)[1:2] <- "foo"
names(x)

# Use the `names2<-` variant to avoid this
x <- 1:3
names2(x)[1:2] <- "foo"
names(x)

Create a new call from components

Description

Create a new call from components

Usage

new_call(car, cdr = NULL)

Arguments

Create a formula

Description

Create a formula

Usage

new_formula(lhs, rhs, env = caller_env())

Arguments

Value

A formula object.

See Also

new_quosure()

Examples

new_formula(quote(a), quote(b))
new_formula(NULL, quote(b))

Create a function

Description

This constructs a new function given its three components: list of arguments, body code and parent environment.

Usage

new_function(args, body, env = caller_env())

Arguments

Examples

f <- function() letters
g <- new_function(NULL, quote(letters))
identical(f, g)

# Pass a list or pairlist of named arguments to create a function
# with parameters. The name becomes the parameter name and the
# argument the default value for this parameter:
new_function(list(x = 10), quote(x))
new_function(pairlist2(x = 10), quote(x))

# Use `exprs()` to create quoted defaults. Compare:
new_function(pairlist2(x = 5 + 5), quote(x))
new_function(exprs(x = 5 + 5), quote(x))

# Pass empty arguments to omit defaults. `list()` doesn't allow
# empty arguments but `pairlist2()` does:
new_function(pairlist2(x = , y = 5 + 5), quote(x + y))
new_function(exprs(x = , y = 5 + 5), quote(x + y))

Helpers for pairlist and language nodes

Description

Important: These functions are for expert R programmers only. You should only use them if you feel comfortable manipulating low level R data structures at the C level. We export them at the R level in order to make it easy to prototype C code. They don't perform any type checking and can crash R very easily (try to take the CAR of an integer vector — save any important objects beforehand!).

Usage

new_node(car, cdr = NULL)

node_car(x)

node_cdr(x)

node_caar(x)

node_cadr(x)

node_cdar(x)

node_cddr(x)

node_poke_car(x, newcar)

node_poke_cdr(x, newcdr)

node_poke_caar(x, newcar)

node_poke_cadr(x, newcar)

node_poke_cdar(x, newcdr)

node_poke_cddr(x, newcdr)

node_tag(x)

node_poke_tag(x, newtag)

Arguments

Value

Setters like node_poke_car() invisibly return x modified in place. Getters return the requested node component.

See Also

duplicate() for creating copy-safe objects and base::pairlist() for an easier way of creating a linked list of nodes.

Create a quosure from components

Description

• new_quosure() wraps any R object (including expressions, formulas, or other quosures) into a quosure.

• as_quosure() is similar but it does not rewrap formulas and quosures.

Usage

new_quosure(expr, env = caller_env())

as_quosure(x, env = NULL)

is_quosure(x)

Arguments

See Also

• enquo() and quo() for creating a quosure by argument defusal.

• What are quosures and when are they needed?

Examples

# `new_quosure()` creates a quosure from its components. These are
# equivalent:
new_quosure(quote(foo), current_env())

quo(foo)

# `new_quosure()` always rewraps its input into a new quosure, even
# if the input is itself a quosure:
new_quosure(quo(foo))

# This is unlike `as_quosure()` which preserves its input if it's
# already a quosure:
as_quosure(quo(foo))


# `as_quosure()` uses the supplied environment with naked expressions:
env <- env(var = "thing")
as_quosure(quote(var), env)

# If the expression already carries an environment, this
# environment is preserved. This is the case for formulas and
# quosures:
as_quosure(~foo, env)

as_quosure(~foo)

# An environment must be supplied when the input is a naked
# expression:
try(
  as_quosure(quote(var))
)

Create a list of quosures

Description

This small S3 class provides methods for [ and c() and ensures the following invariants:

• The list only contains quosures.

• It is always named, possibly with a vector of empty strings.

new_quosures() takes a list of quosures and adds the quosures class and a vector of empty names if needed. as_quosures() calls as_quosure() on all elements before creating the quosures object.

Usage

new_quosures(x)

as_quosures(x, env, named = FALSE)

is_quosures(x)

Arguments

Create a weak reference

Description

A weak reference is a special R object which makes it possible to keep a reference to an object without preventing garbage collection of that object. It can also be used to keep data about an object without preventing GC of the object, similar to WeakMaps in JavaScript.

Objects in R are considered reachable if they can be accessed by following a chain of references, starting from a root node; root nodes are specially-designated R objects, and include the global environment and base environment. As long as the key is reachable, the value will not be garbage collected. This is true even if the weak reference object becomes unreachable. The key effectively prevents the weak reference and its value from being collected, according to the following chain of ownership: weakref <- key -> value.

When the key becomes unreachable, the key and value in the weak reference object are replaced by NULL, and the finalizer is scheduled to execute.

Usage

new_weakref(key, value = NULL, finalizer = NULL, on_quit = FALSE)

Arguments

See Also

is_weakref(), wref_key() and wref_value().

Examples

e <- env()

# Create a weak reference to e
w <- new_weakref(e, finalizer = function(e) message("finalized"))

# Get the key object from the weak reference
identical(wref_key(w), e)

# When the regular reference (the `e` binding) is removed and a GC occurs,
# the weak reference will not keep the object alive.
rm(e)
gc()
identical(wref_key(w), NULL)


# A weak reference with a key and value. The value contains data about the
# key.
k <- env()
v <- list(1, 2, 3)
w <- new_weakref(k, v)

identical(wref_key(w), k)
identical(wref_value(w), v)

# When v is removed, the weak ref keeps it alive because k is still reachable.
rm(v)
gc()
identical(wref_value(w), list(1, 2, 3))

# When k is removed, the weak ref does not keep k or v alive.
rm(k)
gc()
identical(wref_key(w), NULL)
identical(wref_value(w), NULL)

Create vectors matching a given length

Description

These functions construct vectors of a given length, with attributes specified via dots. Except for new_list() and new_raw(), the empty vectors are filled with typed missing values. This is in contrast to the base function base::vector() which creates zero-filled vectors.

Usage

new_logical(n, names = NULL)

new_integer(n, names = NULL)

new_double(n, names = NULL)

new_character(n, names = NULL)

new_complex(n, names = NULL)

new_raw(n, names = NULL)

new_list(n, names = NULL)

Arguments

Lifecycle

These functions are likely to be replaced by a vctrs equivalent in the future. They are in the questioning lifecycle stage.

See Also

rep_along

Examples

new_list(10)
new_logical(10)

Get the namespace of a package

Description

Namespaces are the environment where all the functions of a package live. The parent environments of namespaces are the imports environments, which contain all the functions imported from other packages.

Usage

ns_env(x = caller_env())

ns_imports_env(x = caller_env())

ns_env_name(x = caller_env())

Arguments

See Also

pkg_env()

Return the namespace registry env

Description

Note that the namespace registry does not behave like a normal environment because the parent is NULL instead of the empty environment. This is exported for expert usage in development tools only.

Usage

ns_registry_env()

Address of an R object

Description

Address of an R object

Usage

obj_address(x)

Arguments

Value

Its address in memory in a string.

Run expressions on load

Description

• on_load() registers expressions to be run on the user's machine each time the package is loaded in memory. This is by contrast to normal R package code which is run once at build time on the packager's machine (e.g. CRAN).

  on_load() expressions require run_on_load() to be called inside .onLoad().

• on_package_load() registers expressions to be run each time another package is loaded.

on_load() is for your own package and runs expressions when the namespace is not sealed yet. This means you can modify existing binding or create new ones. This is not the case with on_package_load() which runs expressions after a foreign package has finished loading, at which point its namespace is sealed.

Usage

on_load(expr, env = parent.frame(), ns = topenv(env))

run_on_load(ns = topenv(parent.frame()))

on_package_load(pkg, expr, env = parent.frame())

Arguments

When should I run expressions on load?

There are two main use cases for running expressions on load:

1. When a side effect, such as registering a method with s3_register(), must occur in the user session rather than the package builder session.

2. To avoid hard-coding objects from other packages in your namespace. If you assign foo::bar or the result of foo::baz() in your package, they become constants. Any upstream changes in the foo package will not be reflected in the objects you've assigned in your namespace. This often breaks assumptions made by the authors of foo and causes all sorts of issues.

   Recreating the foreign objects each time your package is loaded makes sure that any such changes will be taken into account. In technical terms, running an expression on load introduces indirection.

Comparison with .onLoad()

on_load() has the advantage that hooked expressions can appear in any file, in context. This is unlike .onLoad() which gathers disparate expressions in a single block.

on_load() is implemented via .onLoad() and requires run_on_load() to be called from that hook.

The expressions inside on_load() do not undergo static analysis by ⁠R CMD check⁠. Therefore, it is advisable to only use simple function calls inside on_load().

Examples

quote({  # Not run

# First add `run_on_load()` to your `.onLoad()` hook,
# then use `on_load()` anywhere in your package
.onLoad <- function(lib, pkg) {
  run_on_load()
}

# Register a method on load
on_load({
  s3_register("foo::bar", "my_class")
})

# Assign an object on load
var <- NULL
on_load({
  var <- foo()
})

# To use `on_package_load()` at top level, wrap it in `on_load()`
on_load({
  on_package_load("foo", message("foo is loaded"))
})

# In functions it can be called directly
f <- function() on_package_load("foo", message("foo is loaded"))

})

Infix attribute accessor and setter

Description

This operator extracts or sets attributes for regular objects and S4 fields for S4 objects.

Usage

x %@% name

x %@% name <- value

Arguments

Examples

# Unlike `@`, this operator extracts attributes for any kind of
# objects:
factor(1:3) %@% "levels"
mtcars %@% class

mtcars %@% class <- NULL
mtcars

# It also works on S4 objects:
.Person <- setClass("Person", slots = c(name = "character", species = "character"))
fievel <- .Person(name = "Fievel", species = "mouse")
fievel %@% name

Replace missing values

Description

Note: This operator is now out of scope for rlang. It will be replaced by a vctrs-powered operator (probably in the funs package) at which point the rlang version of ⁠%|%⁠ will be deprecated.

This infix function is similar to %||% but is vectorised and provides a default value for missing elements. It is faster than using base::ifelse() and does not perform type conversions.

Usage

x %|% y

Arguments

See Also

op-null-default

Examples

c("a", "b", NA, "c") %|% "default"
c(1L, NA, 3L, NA, NA) %|% (6L:10L)

Default value for NULL

Description

This infix function makes it easy to replace NULLs with a default value. It's inspired by the way that Ruby's or operation (||) works.

Usage

x %||% y

Arguments

Examples

1 %||% 2
NULL %||% 2

Collect dynamic dots in a pairlist

Description

This pairlist constructor uses dynamic dots. Use it to manually create argument lists for calls or parameter lists for functions.

Usage

pairlist2(...)

Arguments

Examples

# Unlike `exprs()`, `pairlist2()` evaluates its arguments.
new_function(pairlist2(x = 1, y = 3 * 6), quote(x * y))
new_function(exprs(x = 1, y = 3 * 6), quote(x * y))

# It preserves missing arguments, which is useful for creating
# parameters without defaults:
new_function(pairlist2(x = , y = 3 * 6), quote(x * y))

Parse R code

Description

These functions parse and transform text into R expressions. This is the first step to interpret or evaluate a piece of R code written by a programmer.

• parse_expr() returns one expression. If the text contains more than one expression (separated by semicolons or new lines), an error is issued. On the other hand parse_exprs() can handle multiple expressions. It always returns a list of expressions (compare to base::parse() which returns a base::expression vector). All functions also support R connections.

• parse_expr() concatenates x with ⁠\\n⁠ separators prior to parsing in order to support the roundtrip parse_expr(expr_deparse(x)) (deparsed expressions might be multiline). On the other hand, parse_exprs() doesn't do any concatenation because it's designed to support named inputs. The names are matched to the expressions in the output, which is useful when a single named string creates multiple expressions.

  In other words, parse_expr() supports vector of lines whereas parse_exprs() expects vectors of complete deparsed expressions.

• parse_quo() and parse_quos() are variants that create a quosure. Supply env = current_env() if you're parsing code to be evaluated in your current context. Supply env = global_env() when you're parsing external user input to be evaluated in user context.

  Unlike quosures created with enquo(), enquos(), or ⁠{{⁠, a parsed quosure never contains injected quosures. It is thus safe to evaluate them with eval() instead of eval_tidy(), though the latter is more convenient as you don't need to extract expr and env.

Usage

parse_expr(x)

parse_exprs(x)

parse_quo(x, env)

parse_quos(x, env)

Arguments

Details

Unlike base::parse(), these functions never retain source reference information, as doing so is slow and rarely necessary.

Value

parse_expr() returns an expression, parse_exprs() returns a list of expressions. Note that for the plural variants the length of the output may be greater than the length of the input. This would happen is one of the strings contain several expressions (such as "foo; bar"). The names of x are preserved (and recycled in case of multiple expressions). The ⁠_quo⁠ suffixed variants return quosures.

See Also

base::parse()

Examples

# parse_expr() can parse any R expression:
parse_expr("mtcars %>% dplyr::mutate(cyl_prime = cyl / sd(cyl))")

# A string can contain several expressions separated by ; or \n
parse_exprs("NULL; list()\n foo(bar)")

# Use names to figure out which input produced an expression:
parse_exprs(c(foo = "1; 2", bar = "3"))

# You can also parse source files by passing a R connection. Let's
# create a file containing R code:
path <- tempfile("my-file.R")
cat("1; 2; mtcars", file = path)

# We can now parse it by supplying a connection:
parse_exprs(file(path))

Name of a primitive function

Description

Name of a primitive function

Usage

prim_name(prim)

Arguments

Show injected expression

Description

qq_show() helps examining injected expressions inside a function. This is useful for learning about injection and for debugging injection code.

Arguments

Examples

qq_show() shows the intermediary expression before it is evaluated by R:

list2(!!!1:3)
#> [[1]]
#> [1] 1
#> 
#> [[2]]
#> [1] 2
#> 
#> [[3]]
#> [1] 3

qq_show(list2(!!!1:3))
#> list2(1L, 2L, 3L)

It is especially useful inside functions to reveal what an injected expression looks like:

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

mtcars %>% my_mean(cyl)
#> data %>% dplyr::summarise(mean(^cyl))

See Also

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

Squash a quosure

Description

This function is deprecated, please use quo_squash() instead.

Usage

quo_expr(quo, warn = FALSE)

Arguments

Format quosures for printing or labelling

Description

Note: You should now use as_label() or as_name() instead of quo_name(). See life cycle section below.

These functions take an arbitrary R object, typically an expression, and represent it as a string.

• quo_name() returns an abbreviated representation of the object as a single line string. It is suitable for default names.

• quo_text() returns a multiline string. For instance block expressions like { foo; bar } are represented on 4 lines (one for each symbol, and the curly braces on their own lines).

These deparsers are only suitable for creating default names or printing output at the console. The behaviour of your functions should not depend on deparsed objects. If you are looking for a way of transforming symbols to strings, use as_string() instead of quo_name(). Unlike deparsing, the transformation between symbols and strings is non-lossy and well defined.

Usage

quo_label(quo)

quo_text(quo, width = 60L, nlines = Inf)

quo_name(quo)

Arguments

Life cycle

These functions are superseded.

• as_label() and as_name() should be used instead of quo_name(). as_label() transforms any R object to a string but should only be used to create a default name. Labelisation is not a well defined operation and no assumption should be made about the label. On the other hand, as_name() only works with (possibly quosured) symbols, but is a well defined and deterministic operation.

• We don't have a good replacement for quo_text() yet. See https://github.com/r-lib/rlang/issues/636 to follow discussions about a new deparsing API.

See Also

expr_label(), f_label()

Examples

# Quosures can contain nested quosures:
quo <- quo(foo(!! quo(bar)))
quo

# quo_squash() unwraps all quosures and returns a raw expression:
quo_squash(quo)

# This is used by quo_text() and quo_label():
quo_text(quo)

# Compare to the unwrapped expression:
expr_text(quo)

# quo_name() is helpful when you need really short labels:
quo_name(quo(sym))
quo_name(quo(!! sym))

Squash a quosure

Description

quo_squash() flattens all nested quosures within an expression. For example it transforms ⁠^foo(^bar(), ^baz)⁠ to the bare expression foo(bar(), baz).

This operation is safe if the squashed quosure is used for labelling or printing (see as_label(), but note that as_label() squashes quosures automatically). However if the squashed quosure is evaluated, all expressions of the flattened quosures are resolved in a single environment. This is a source of bugs so it is good practice to set warn to TRUE to let the user know about the lossy squashing.

Usage

quo_squash(quo, warn = FALSE)

Arguments