rlang

htmlhttps://lifecycle.r-lib.org/articles/stages.html#deprecatedlifecycle-deprecated.svgoptions: alt='[Deprecated]'[Deprecated] These operators are deprecated in favour of [=injection-operator]!! and [=splice-operator]!!!.

UQ(x) UQS(x)

These functions are equivalent to base functions [base:stop]base::stop(), [base:warning]base::warning(), and [base:message]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 [=topic-error-chaining]chained condition. Certain components of condition messages are formatted with unicode symbols and terminal colours by default. These aspects can be customised, see html[=topic-condition-customisation]Customising condition messages[=topic-condition-customisation]Customising condition messages.

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)

# 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 occurred in `my_function()` try(g())

htmlhttps://lifecycle.r-lib.org/articles/stages.html#questioninglifecycle-questioning.svgoptions: alt='[Questioning]'[Questioning] are_na() checks for missing values in a vector and is equivalent to [base:NA]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]missing types.

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)

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

This is equivalent to [base:match.arg]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_fn]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.

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

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

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

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

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

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]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]abort(). See also [=local_error_call]local_error_call().

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.

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

as_closure() is like [=as_function]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.

as_closure(x, env = caller_env())

# 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(`~`)

A [=topic-data-mask]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.

as_data_mask(data) as_data_pronoun(data) new_data_mask(bottom, top = bottom)

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

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

as_environment(x, parent = NULL)

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

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

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

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

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]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]as_name(). For instance, use as_label() with objects captured with enquo() and as_name() with symbols captured with ensym().

as_label(x)

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

as_name() converts [=sym]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]as_label() when you need to transform any kind of object to a string to represent that object with a short description.

as_name(x)

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

as_string() converts [=sym]symbols to character strings.

as_string(x)

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

htmlhttps://lifecycle.r-lib.org/articles/stages.html#experimentallifecycle-experimental.svgoptions: alt='[Experimental]'[Experimental] 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]chr_unserialise_unicode(). This helps to alleviate the effects of character-to-symbol-to-character roundtrips on systems with non-UTF-8 native encoding.

as_utf8_character(x)

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

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.

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)

new_box() is similar to [base:AsIs]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.

new_box(.x, class = NULL, ...) is_box(x, class = NULL) unbox(box)

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

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.

as_bytes(x) parse_bytes(x)

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

Quoted function calls are one of the two types of [=is_symbolic]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 [=nse-defuse]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::call(), [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.

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

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

Extract arguments from a call

call_args(call) call_args_names(call)

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)

htmlhttps://lifecycle.r-lib.org/articles/stages.html#deprecatedlifecycle-deprecated.svgoptions: alt='[Deprecated]'[Deprecated] Deprecated in rlang 0.4.11.

call_fn(call, env = caller_env())

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

call_inspect(...)

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

call_match() is like [=match.call]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).

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

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

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

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

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 = zap(), 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 = zap(), bar = missing_arg()) # You can also choose to keep only the first or last homonym # arguments: args <- list(bar = zap(), bar = missing_arg()) call_modify(call, !!!args, .homonyms = "first") call_modify(call, !!!args, .homonyms = "last")

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: If is_call_simple(x) returns TRUE, call_name(x) returns a string. Otherwise it returns NULL. If is_call_simple(x, ns = TRUE) returns TRUE, call_ns() returns a string. Otherwise it returns NULL.

call_name(call) call_ns(call) is_call_simple(x, ns = NULL)

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

htmlhttps://lifecycle.r-lib.org/articles/stages.html#deprecatedlifecycle-deprecated.svgoptions: alt='[Deprecated]'[Deprecated] Deprecated in rlang 0.4.11 in favour of [=call_match]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]call_match() as a simpler wrapper around [=match.call]match.call(). This is essentially equivalent to [base:match.call]base::match.call(), but with experimental handling of primitive functions.

call_standardise(call, env = caller_env())

caller_arg() is a variant of substitute() or [=ensym]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.

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

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.

catch_cnd(expr, classes = "condition")

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

htmlhttps://lifecycle.r-lib.org/articles/stages.html#experimentallifecycle-experimental.svgoptions: alt='[Experimental]'[Experimental] Checks that an argument is a data frame, producing a friendly error message on failure.

check_data_frame( x, ..., allow_null = FALSE, arg = caller_arg(x), call = caller_env() )

check_data_frame(mtcars) try(check_data_frame(1:5))

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

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

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_dots_empty0() is a more efficient version of [=check_dots_empty]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.

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

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.

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

f <- function(..., foofy = 8) check_dots_unnamed() c(...) f(1, 2, 3, foofy = 4) try(f(1, 2, 3, foof = 4))

When ... arguments are passed to a method, the method should 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.

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

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

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

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

Throws an error if x is missing.

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

f <- function(x) check_required(x) # Fails because `x` is not supplied try(f()) # Succeeds f(NULL)

htmlhttps://lifecycle.r-lib.org/articles/stages.html#experimentallifecycle-experimental.svgoptions: alt='[Experimental]'[Experimental] These functions check that an argument is a number, optionally with bounds, and produce friendly error messages otherwise.

check_number_decimal( x, ..., min = NULL, max = NULL, allow_infinite = TRUE, allow_na = FALSE, allow_null = FALSE, arg = caller_arg(x), call = caller_env() ) check_number_whole( x, ..., min = NULL, max = NULL, allow_infinite = FALSE, allow_na = FALSE, allow_null = FALSE, arg = caller_arg(x), call = caller_env() )

check_number_decimal(3.14) try(check_number_decimal("x")) check_number_whole(42) try(check_number_whole(3.5))

htmlhttps://lifecycle.r-lib.org/articles/stages.html#experimentallifecycle-experimental.svgoptions: alt='[Experimental]'[Experimental] These functions check that an argument is of the expected scalar type and produce friendly error messages otherwise.

check_bool( x, ..., allow_na = FALSE, allow_null = FALSE, arg = caller_arg(x), call = caller_env() ) check_string( x, ..., allow_empty = TRUE, allow_na = FALSE, allow_null = FALSE, arg = caller_arg(x), call = caller_env() )

check_bool(TRUE) try(check_bool(1)) check_string("hello") try(check_string(42))

htmlhttps://lifecycle.r-lib.org/articles/stages.html#deprecatedlifecycle-deprecated.svgoptions: alt='[Deprecated]'[Deprecated] [=env]env() now supports creating child environments, please use it instead.

child_env(.parent, ...)

htmlhttps://lifecycle.r-lib.org/articles/stages.html#experimentallifecycle-experimental.svgoptions: alt='[Experimental]'[Experimental] 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]env_names() and can be manually triggered with as_utf8_character() and chr_unserialise_unicode().

chr_unserialise_unicode(chr)

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

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]"rlang_error". Use [=cnd_signal]cnd_signal() to emit the relevant signal for a particular condition class.

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 )

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

Like any R objects, errors captured with catchers like [=tryCatch]tryCatch() have a [=class]class() which you can test with [=inherits]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]abort(), [=warn]warn(), and [=inform]inform().

cnd_inherits(cnd, class)

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

cnd_message(cnd, ..., inherit = TRUE, prefix = FALSE) cnd_header(cnd, ...) cnd_body(cnd, ...) cnd_footer(cnd, ...)

Unlike [=exiting]exiting() handlers, [=calling]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.

cnd_muffle(cnd)

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

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]inform() or [base:message]base::message(). A warning is signalled if the condition inherits from "warning". This is equivalent to signalling with [=warn]warn() or [base:warning]base::warning(). An error is signalled if the condition inherits from "error". This is equivalent to signalling with [=abort]abort() or [base:stop]base::stop(). An interrupt is signalled if the condition inherits from "interrupt". This is equivalent to signalling with [=interrupt]interrupt().

cnd_signal(cnd, ...)

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

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

cnd_type(cnd)

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

These advanced operators [=topic-defuse]defuse R expressions. [=expr]expr(), [=enquo]enquo(), and [=enquos]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:list]base::alist() but with [=nse-inject]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 html[=topic-quosure]What are quosures and when are they needed?[=topic-quosure]What are quosures and when are they needed?. enexpr() and enexprs() are like [=enquo]enquo() and [=enquos]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. html<div class="sourceCode">"foo" <- NULL list("foo" = NULL) html</div> 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]inject(). None of the features of [=dyn-dots]dynamic dots are available when defusing with enquos0(). For instance, trailing empty arguments are not automatically trimmed.

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

# `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

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

done(x) is_done_box(x, empty = NULL)

done(3) x <- done(3) is_done_box(x)

The .data and .env pronouns make it explicit where to find objects when programming with [=topic-data-mask]data-masked functions. html<div class="sourceCode">m <- 10 mtcars %>% mutate(disp = .data$disp * .env$m) html</div> .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: html<div class="sourceCode">disp <- 10 mtcars %>% mutate(disp = .data$disp * .env$disp) mtcars %>% mutate(disp = disp * disp) html</div> 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.

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

dots_n(...)

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

htmlhttps://lifecycle.r-lib.org/articles/stages.html#deprecatedlifecycle-deprecated.svgoptions: alt='[Deprecated]'[Deprecated] dots_splice() is like [=dots_list]dots_list() but automatically splices list inputs.

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

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

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

dots <- dots_values(!!! list(1, 2), 3) dots # Flatten the objects marked as spliced: flatten_if(dots, is_spliced)

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.

duplicate(x, shallow = FALSE)

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]c() or [=list]list(). Dynamic dots offer a few additional features, [=topic-inject]injection in particular: You can splice arguments saved in a list with the splice operator [=splice-operator]!!!. You can inject names with [=glue-operators]glue syntax on the left-hand side of :=. Trailing commas are ignored, making it easier to copy and paste lines of arguments.

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

The embrace operator \\ is used to create functions that call other [=topic-data-mask]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. html<div class="sourceCode r">my_mean <- function(data, var) \ dplyr::summarise(data, mean = mean(\\ var \\)) \ html</div>

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

empty_env()

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

englue() creates a string with the [=glue-operators]glue operators \ and \\. These operators are normally used to inject names within [=dyn-dots]dynamic dots. englue() makes them available anywhere within a function. englue() must be used inside a function. englue(" var ") [=topic-defuse]defuses the argument var and transforms it to a string using the default name operation.

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

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)

enquo() and enquos() [=topic-defuse]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 [=topic-data-mask]data-masking function using the [=topic-metaprogramming]defuse-and-inject pattern. These are advanced tools. Make sure to first learn about the embrace operator html[=embrace-operator]\\\\ in html[=topic-data-mask-programming]Data mask programming patterns[=topic-data-mask-programming]Data mask programming patterns. \\ is easier to work with less theory, and it is sufficient in most applications.

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 )

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

entrace() is a low level function. See [=global_entrace]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]last_error() and rethrown immediately. Messages and warnings are recorded into [=last_messages]last_messages() and [=last_warnings]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 invocation context from the backtrace.

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

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

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.

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

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

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]base::assign(). env_bind_active() takes named functions and creates active bindings in .env. This is equivalent to [base:bindenv]base::makeActiveBinding(). An active binding executes a function each time it is evaluated. The arguments are passed to [=as_function]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]base::delayedAssign(). The arguments are captured with [=exprs]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.

env_bind(.env, ...) env_bind_lazy(.env, ..., .eval_env = caller_env()) env_bind_active(.env, ...) lhs %<~% rhs

# 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!"); "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") 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

htmlhttps://lifecycle.r-lib.org/articles/stages.html#experimentallifecycle-experimental.svgoptions: alt='[Experimental]'[Experimental]

env_binding_are_active(env, nms = NULL) env_binding_are_lazy(env, nms = NULL)

htmlhttps://lifecycle.r-lib.org/articles/stages.html#experimentallifecycle-experimental.svgoptions: alt='[Experimental]'[Experimental] Locked environment bindings trigger an error when an attempt is made to redefine the binding.

env_binding_lock(env, nms = NULL) env_binding_unlock(env, nms = NULL) env_binding_are_locked(env, nms = NULL)

# 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

htmlhttps://lifecycle.r-lib.org/articles/stages.html#defunctlifecycle-defunct.svgoptions: alt='[Defunct]'[Defunct] 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.

env_browse(env, value = TRUE) env_is_browsed(env)

htmlhttps://lifecycle.r-lib.org/articles/stages.html#supersededlifecycle-superseded.svgoptions: alt='[Superseded]'[Superseded] This function is superseded. Please use [=env]env() (and possibly [=set_env]set_env() if you're masking the bindings for another object like a closure or a formula) instead. env_bury() is like [=env_bind]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).

env_bury(.env, ...)

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

env_cache() is a wrapper around [=env_get]env_get() and [=env_poke]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.

env_cache(env, nm, default)

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

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.

env_clone(env, parent = env_parent(env)) env_coalesce(env, from)

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

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

env_depth(env)

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

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.

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

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

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

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

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)

This returns TRUE if x has ancestor among its parents.

env_inherits(env, ancestor)

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 https://lifecycle.r-lib.org/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.

env_is_user_facing(env)

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

htmlhttps://lifecycle.r-lib.org/articles/stages.html#experimentallifecycle-experimental.svgoptions: alt='[Experimental]'[Experimental] 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]env_binding_lock() for locking individual bindings.

env_lock(env) env_is_locked(env)

# 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

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 [=search_envs]package environments and the [=ns_imports_env]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.

env_name(env) env_label(env)

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

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.

env_names(env) env_length(env)

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

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]empty_env() as parent. env_parents() returns the list of all parents, including the empty environment. This list is named using [=env_name]env_name(). See the section on inheritance in [=env]env()'s documentation.

env_parent(env = caller_env(), n = 1) env_tail(env = caller_env(), last = global_env()) env_parents(env = caller_env(), last = global_env())

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

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.

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

This prints: The [=env_label]label and the parent label. Whether the environment is [=env_lock]locked. The bindings in the environment (up to 20 bindings). They are printed succinctly using pillar::type_sum() (if available, otherwise uses an internal version of that generic). In addition [=env_bind_lazy]fancy bindings (actives and promises) are indicated as such. Locked bindings get a [L] tag Note that printing a package namespace (see [=ns_env]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.

env_print(env = caller_env())