Movatterモバイル変換

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 Henrylionel@posit.co

Authors:

• Hadley Wickhamhadley@posit.co

Other contributors:

• mikefcmikefc@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 athttps://github.com/r-lib/rlang/issues

DeprecatedUQ() andUQS() operators

Description

These operators are deprecated in favour of!! and!!!.

Usage

UQ(x)UQS(x)

Signal an error, warning, or message

Description

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

• Supplyclass to create a classed condition that can be caughtor handled selectively, allowing for finer-grained errorhandling.

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

• Supplycall to inform users about which function the erroroccurred in.

• Supply another condition asparent to create achained condition.

Certain components of condition messages are formatted with unicodesymbols and terminal colours by default. These aspects can becustomised, seeCustomising 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 thewarning.length global option tothe maximum value (8170), unless that option has been changedfrom the default value. The default limit (1000 characters) isespecially easy to hit when the message contains a lot of ANSIescapes, as created by the crayon or cli packages

Error prefix

As withbase::stop(), errors thrown withabort() are prefixedwith"Error: ". Calls and source references are included in theprefix, e.g.⁠"Error in ⁠my_function()⁠ at myfile.R:1:2:"⁠. Thereare a few cosmetic differences:

• The call is stripped from its arguments to keep it simple. It isthen formatted using thecli package ifavailable.

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

If your throwing code is highly structured, you may have toexplicitly informabort() about the relevant user-facing call toinclude in the prefix. Internal helpers are rarely relevant to endusers. See thecall argument ofabort().

Backtrace

abort() saves a backtrace in thetrace component of the errorcondition. You can print a simplified backtrace of the last errorby callinglast_error() and a full backtrace withsummary(last_error()). Learn how to control what is displayedwhen an error is thrown withrlang_backtrace_on_error.

Muffling and silencing conditions

Signalling a condition withinform() orwarn() displays amessage in the console. These messages can be muffled as usual withbase::suppressMessages() orbase::suppressWarnings().

inform() andwarn() messages can also be silenced with theglobal optionsrlib_message_verbosity andrlib_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 conditionis not signalled.

stdout andstderr

By default,abort() andinform() print to standard output ininteractive sessions. This allows rlang to be in control of theappearance of messages in IDEs like RStudio.

There are two situations where messages are streamed tostderr:

• In non-interactive sessions, messages are streamed to standarderror so that R scripts can easily filter them out from normaloutput by redirectingstderr.

• If a sink is active (either on output or on messages) messagesare always streamd tostderr.

These exceptions ensure consistency of behaviour in interactive andnon-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 errorsif (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 selectivelytryCatch(  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 equivalenttobase::is.na(). It is a vectorised predicate, meaning that itsoutput is always the same length as its input. On the other hand,is_na() is a scalar predicate and always returns a scalarboolean,TRUE orFALSE. If its input is not scalar, it returnsFALSE. Finally, there are typed versions that check forparticularmissing 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 equivalenttois_null() in that respect. In contrast the vectorisedpredicateare_na() requires a vector input since it is definedover vector values.

Life cycle

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

Examples

# are_na() is vectorised and works regardless of the typeare_na(c(1, 2, NA))are_na(c(1L, NA, 3L))# is_na() checks for scalar input and works for all typesis_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 tobase::match.arg() with a few differences:

• Partial matches trigger an error.

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

arg_match() derives the possible values from thecaller function.

arg_match0() is a bare-bones version if performance is at a premium.It requires a string asarg and explicit charactervalues.For convenience,arg may also be a character vector containingevery element ofvalues, possibly permuted.In this case, the first element ofarg 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 toarg.

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 whichindicates that the argument uses tidy evaluation withdata masking.If you've never heard of tidy evaluation before, start withvignette("programming", package = "dplyr").

Key terms

The primary motivation for tidy evaluation in tidyverse packages is that itprovidesdata masking, which blurs the distinction between two types ofvariables:

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

• data-variables are "statistical" variables and live in a data frame.They usually come from data files (e.g..csv,.xls), or are created bymanipulating 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 ofdiamonds[diamonds$x == 0 & diamonds$y == 0 & diamonds$z == 0, ].

Indirection in wrapper functions

The main challenge of data masking arises when you introduce someindirection, i.e. instead of directly typing the name of a variable youwant 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.datapronoun, 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 evaluatedin the data environment so you don't need to worry about a data-variablecalledvar causing problems.)

Dot-dot-dot (...)

When this modifier is applied to..., there is one other useful techniquewhich solves the problem of creating a new variable with a name supplied bythe 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 packageto consistently document... that must be empty.

Arguments

Helper for consistent documentation of used dots

Description

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

Arguments

Documentation anchor for error arguments

Description

Use⁠@inheritParams rlang::args_error_context⁠ in your package todocumentarg andcall arguments (or equivalently their prefixedversionserror_arg anderror_call).

• arg parameters should be formatted as argument (e.g. usingcli's.arg specifier) and included in error messages. See alsocaller_arg().

• call parameters should be included in error conditions in afield namedcall. An easy way to do this is by passing acallargument toabort(). See alsolocal_error_call().

Arguments

Convert object to a box

Description

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

• as_box_if() boxes its input only if it not already a box, or ifthe predicate.p returnsTRUE.

Usage

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

Arguments

Transform to a closure

Description

as_closure() is likeas_function() but also wraps primitivefunctions inside closures. Some special control flow primitiveslikeif,for, orbreak can't be wrapped and will cause anerror.

Usage

as_closure(x, env = caller_env())

Arguments

Examples

# Primitive functions are regularised as closuresas_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

Adata mask is an environment (or possiblymultiple environments forming an ancestry) containing user-suppliedobjects. Objects in the mask have precedence over objects in theenvironment (i.e. they mask those objects). Many R functionsevaluate quoted expressions in a data mask so these expressions canrefer 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 thanfor 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 toeval_tidy().

Why build a data mask?

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

• Wheneval_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 subsequentevaluations may improve performance.

• When several expressions should be evaluated in the exact sameenvironment because a quoted expression might create new objectsthat can be referred in other quoted expressions evaluated at alater time. One example of this istibble::lst() where newcolumns can refer to previous ones.

• When your data mask requires special features. For instance thedata frame columns in dplyr data masks are implemented withactive bindings.

Building your own data mask

Unlikebase::eval() which takes any kind of environments as datamask,eval_tidy() has specific requirements in order to supportquosures. For this reason you can't supply bareenvironments.

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 forenvironments. You can supply a bottom and a top environment incase your data mask comprises multiple environments (see sectionbelow).

  Unlikeas_data_mask() it does not install the.data pronounso you need to provide one yourself. You can provide a pronounconstructed withas_data_pronoun() or your own pronoun class.

  as_data_pronoun() will create a pronoun from a list, anenvironment, or an rlang data mask. In the latter case, the wholeancestry 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 toeval_tidy() asthedata argument. You can repeat this as many times asneeded. Note that any objects created there (perhaps because of acall to⁠<-⁠) will persist in subsequent evaluations.

Top and bottom of data mask

In some cases you'll need several levels in your data mask. Onegood reason is when you include functions in the mask. It's a goodidea to keep data objects one level lower than function objects, sothat the former cannot override the definitions of the latter (seeexamples).

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

Note that the parent of the top environment is completelyundetermined, you shouldn't expect it to remain the same at alltimes. This parent is replaced during evaluation byeval_tidy()to one of the following environments:

• The default environment passed as theenv argument ofeval_tidy().

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

Consequently, all masking data should be contained between thebottom 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 anenvironment. The names must be unique. If supplied an unnamedstring, it returns the corresponding package environment (seepkg_env()).

Usage

as_environment(x, parent = NULL)

Arguments

Details

Ifx is an environment andparent is notNULL, theenvironment is duplicated before being set a new parent. The returnvalue is therefore a different environment thanx.

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-readabledescription. You can use labels to:

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

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

See alsoas_name() for transforming symbols back to astring. Unlikeas_label(),as_name() is a well definedoperation that guarantees the roundtrip symbol -> string ->symbol.

In general, if you don't know for sure what kind of object you'redealing with (a call, a symbol, an unquoted constant), useas_label() and make no assumption about the resulting string. Ifyou know you have a symbol and need the name of the object itrefers to, useas_name(). For instance, useas_label() withobjects captured withenquo() andas_name() with symbolscaptured withensym().

Usage

as_label(x)

Arguments

Transformation to string

• Quosures aresquashed before being labelled.

• Symbols are transformed to string withas_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 stringdeterministically.

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() convertssymbols to character strings. Theconversion is deterministic. That is, the roundtripsymbol -> name -> symbol always gives the same result.

• Useas_name() when you need to transform a symbol to a stringtorefer to an object by its name.

• Useas_label() when you need to transform any kind of object toa string torepresent that object with a short description.

Usage

as_name(x)

Arguments

Details

rlang::as_name() is theopposite ofbase::as.name(). Ifyou're writing base R code, we recommend usingbase::as.symbol()which is an alias ofas.name() that follows a more modernterminology (R types instead of S modes).

Value

A character vector of length 1.

See Also

as_label() for converting any object to a single stringsuitable as a label.as_string() for a lower-level version thatdoesn't unwrap quosures.

Examples

# Let's create some symbols:foo <- quote(foo)bar <- sym("bar")# as_name() converts symbols to strings:fooas_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() convertssymbols to character strings.

Usage

as_string(x)

Arguments

Value

A character vector of length 1.

Unicode tags

Unlikebase::as.symbol() andbase::as.name(),as_string()automatically transforms unicode tags such as"<U+5E78>" to theproper 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. Forexample, Western encodings do not support CKJ characters.

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

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

• This operation is very common in the tidyverse because of datamasking APIs like dplyr where data frames are transformed toenvironments. While the names of a data frame are stored as acharacter vector, the bindings of environments are stored assymbols.

Because it reencodes the ASCII unicode tags to their UTF-8representation, the string -> symbol -> string roundtrip ismore stable withas_string().

See Also

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

Examples

# Let's create some symbols:foo <- quote(foo)bar <- sym("bar")# as_string() converts symbols to strings:fooas_string(foo)typeof(bar)typeof(as_string(bar))

Coerce to a character vector and attempt encoding conversion

Description

Unlike specifying theencoding argument inas_string() andas_character(), which is only declarative, these functionsactually attempt to convert the encoding of their input. There aretwo possible cases:

• The string is tagged as UTF-8 or latin1, the only two encodingsfor which R has specific support. In this case, converting to thesame encoding is a no-op, and converting to native always worksas expected, as long as the native encoding, the one specified bytheLC_CTYPE locale has support for all characters occurring inthe strings. Unrepresentable characters are serialised as unicodepoints: "<U+xxxx>".

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

When translating to UTF-8, the strings are parsed for serialisedunicode points (e.g. strings looking like "U+xxxx") withchr_unserialise_unicode(). This helps to alleviate the effects ofcharacter-to-symbol-to-character roundtrips on systems withnon-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 returnTRUE forbare 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 then argument forpattern-matching on the vector length.

• Likeis_atomic() and unlike base Ris.atomic() for R < 4.4.0,is_bare_atomic() does not returnTRUE forNULL. Starting inR 4.4.0,is.atomic(NULL) returns FALSE.

• Unlike base Ris.numeric(),is_bare_double() only returnsTRUE for floating point numbers.

See Also

type-predicates,scalar-type-predicates

Box a value

Description

new_box() is similar tobase::I() but it protects a value bywrapping it in a scalar list rather than by adding an attribute.unbox() retrieves the boxed value.is_box() tests whether anobject is boxed with optional class.as_box() ensures that avalue is wrapped in a box.as_box_if() does the same but only ifthe 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")boxed2unbox(boxed2)# Compare to:boxed_boxed <- new_box(boxed, "mybox")boxed_boxedunbox(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 numericvectors, so you can compare them numerically, but they can also be comparedto human readable values such as '10MB'.

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

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

Note: Abytes() 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")))

Create a call

Description

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

• Byquoting it. Quoting prevents functions from beingcalled. Instead, you get the description of the function call asan R object. That is, a quoted function call.

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

See section below for the difference betweencall2() and the baseconstructors.

Usage

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

Arguments

Difference with base constructors

call2() is more flexible thanbase::call():

• The function to call can be a string or acallableobject: a symbol, another call (e.g. a$ or[[ call), or afunction to inline.base::call() only supports strings and youneed to usebase::as.call() to construct a call with a callableobject.

  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 tons_call <- call("::", as.symbol("list"), as.symbol("base"))as.call(list(ns_call, 1, 2))

• call2() hasdynamic dots support. You can splice listsof arguments with⁠!!!⁠ or unquote an argument name with gluesyntax.

  args <- list(na.rm = TRUE, trim = 0)call2("mean", 1:10, !!!args)# Equivalent toas.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 infunction and argument positions. Inlining an object or a functionhas the advantage that the correct object is used in allenvironments. If all components of the code are inlined, you caneven evaluate in theempty environment.

However inlining also has drawbacks. It can cause issues with NSEfunctions that expect symbolic arguments. The objects may also leakin representations of the call stack, such astraceback().

See Also

call_modify()

Examples

# fn can either be a string, a symbol or a callcall2("f", a = 1)call2(quote(f), a = 1)call2(quote(f()), a = 1)#' Can supply arguments individually or in a listcall2(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

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() andfn_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 aroundbase::match.call(). It returnsits own function call.

Usage

call_inspect(...)

Arguments

Examples

# When you call it directly, it simply returns what you typedcall_inspect(foo(bar), "" %>% identity())# Pass `call_inspect` to functionals like `lapply()` or `map()` to# inspect the calls they create around the supplied functionlapply(1:3, call_inspect)

Match supplied arguments to function definition

Description

call_match() is likematch.call() with these differences:

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

• It requires you to be a little more specific in some cases.Either all arguments are inferred from the call stack or none ofthem 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

Whencall is not supplied, it is inferred from the call stackalong withfn anddots_env.

• call andfn are inferred from the calling environment:sys.call(sys.parent()) andsys.function(sys.parent()).

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

Ifcall is supplied, then you must supplyfn as well. Alsoconsider supplyingdots_env as it is set to the empty environmentwhen not inferred.

Examples

# `call_match()` supports matching missing arguments to their# defaultsfn <- function(x = "default") fncall_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 thearguments are standardised withcall_match() beforemodifying 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 argumentcall_modify(call, na.rm = FALSE)call_modify(call, x = quote(y))# Remove an argumentcall_modify(call, na.rm = zap())# Add a new argumentcall_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, ... = )callcall <- 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_callcall_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")

Extract function name or namespace of a call

Description

call_name() andcall_ns() extract the function name ornamespace ofsimple calls as a string. They returnNULL forcomplex calls.

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

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

Theis_call_simple() predicate helps you determine whether a callis simple. There are two invariants you can count on:

1. Ifis_call_simple(x) returnsTRUE,call_name(x) returns astring. Otherwise it returnsNULL.

2. Ifis_call_simple(x, ns = TRUE) returnsTRUE,call_ns()returns a string. Otherwise it returnsNULL.

Usage

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

Arguments

Value

The function name or namespace as a string, orNULL ifthe 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 ofcall_match().call_standardise() was designed for call wrappers that include anenvironment like formulas or quosures. The function definition wasplucked from that environment. However in practice it is rare touse it with wrapped calls, and then it's easy to forget to supplythe environment. For these reasons, we have designedcall_match()as a simpler wrapper aroundmatch.call().

This is essentially equivalent tobase::match.call(), but withexperimental handling of primitive functions.

Usage

call_standardise(call, env = caller_env())

Arguments

Value

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

Find the caller argument for error messages

Description

caller_arg() is a variant ofsubstitute() orensym() forarguments that reference other arguments. Unlikesubstitute()which returns an expression,caller_arg() formats the expressionas a single line string which can be included in error messages.

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

• Use⁠@inheritParams rlang::args_error_context⁠ to document anarg orerror_arg argument that takeserror_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 aroundtryCatch() that captures anycondition signalled while evaluating its argument. It is useful forsituations 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 tofully name the details arguments. In this case, supplying data in... is almost always a programming error. This function checksthat... 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 positionallytry(f(1, 4))# This fails because `foofy` can't be matched partially by nametry(f(1, foof = 4))# Thanks to `...`, it must be matched exactlyf(1, foofy = 4)

Check that dots are empty (low level variant)

Description

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

Usage

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

Arguments

Check that all dots are unnamed

Description

In functions likepaste(), named arguments in... are often asign of misspelled argument names. Callcheck_dots_unnamed() tofail 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 a method, the method should matchand use these arguments. If this isn't the case, this often indicatesa programming error. Callcheck_dots_used() to fail with an error whenunused 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 callson.exit() to check that allelements of... have been used when the function exits. If youuseon.exit() elsewhere in your function, make sure to useadd = TRUE so that you don't override the handler set up bycheck_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 ofa set of mutually exclusive arguments. An informative error isthrown 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 isFALSE and no argument is supplied, the empty string"" isreturned.

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 forbiddentry(f())try(f(NULL, NULL))# The user must supply one of the mutually exclusive argumentsf(NULL)f(y = NULL)# With `.require` you can allow zero argumentsf <- 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 ifx 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 suppliedtry(f())# Succeedsf(NULL)

Create a child environment

Description

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

Usage

child_env(.parent, ...)

Translate unicode points to UTF-8

Description

For historical reasons, R translates strings to the native encodingwhen they are converted to symbols. This string-to-symbolconversion is not a rare occurrence and happens for instance to thenames of a list of arguments converted to a call bydo.call().

If the string contains unicode characters that cannot berepresented in the native encoding, R serialises those as an ASCIIsequence representing the unicode point. This is why Windows userswith western locales often see strings looking like⁠<U+xxxx>⁠. Toalleviate some of the pain, rlang parses strings and looks forserialised unicode points to translate them back to the properUTF-8 representation. This transformation occurs automatically infunctions likeenv_names() and can be manually triggered withas_utf8_character() andchr_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 thatpower the error, warning, and message system in R.

• cnd() creates bare conditions that only inherit fromcondition.

• Conditions created witherror_cnd(),warning_cnd(), andmessage_cnd() inherit from"error","warning", or"message".

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

Usecnd_signal() to emit the relevant signal for a particularcondition 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 handlerwith_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 liketryCatch()have aclass() which you can test withinherits(). However,with chained errors, the class of a captured error might bedifferent than the error that was originally signalled. Usecnd_inherits() to detect whether an error or any of itsparentinherits from a class.

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

Some chained conditions carry parents that are not inherited. Seethe.inherit argument ofabort(),warn(), andinform().

Usage

cnd_inherits(cnd, class)

Arguments

Capture an error withcnd_inherits()

Error catchers liketryCatch() andtry_fetch() can only matchthe class of a condition, not the class of its parents. To match aclass across the ancestry of an error, you'll need a bit ofcraftiness.

Ancestry matching can't be done withtryCatch() at all so you'llneed to switch towithCallingHandlers(). Alternatively, you canuse the experimental rlang functiontry_fetch() which is able toperform the roles of bothtryCatch() andwithCallingHandlers().

withCallingHandlers()

UnliketryCatch(),withCallingHandlers() does not capture anerror. If you don't explicitly jump with anerror or avaluethrow, nothing happens.

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

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 withtry_fetch(). LikewithCallingHandlers(), it doesn't capture a matching error rightaway. Instead, it captures it only if the handler doesn't return azap() 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 thattry_fetch() usescnd_inherits() internally. Thismakes it very easy to match a parent condition:

cnd <- try_fetch(  f(),  bar = function(x) x)# This is the parentclass(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. Theelements are combined into a single string with a newlineseparator. Bullets syntax is supported, either through rlang (seeformat_error_bullets()), or through cli if the condition hasuse_cli_format set toTRUE.

The default method for the error header returns themessage fieldof the condition object. The default methods for the body andfooter return the thebody andfooter fields if any, or emptycharacter vectors otherwise.

cnd_message() is automatically called by theconditionMessage()for rlang errors, warnings, and messages. Error classes createdwithabort() only need to implement header, body or footermethods. This provides a lot of flexibility for hierarchies oferror classes, for instance you could inherit the body of an errormessage 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 ofyour checking routine. In that case, it can be tricky to lazilygenerate error messages withcnd_header(),cnd_body(), andcnd_footer(): you have the choice between overspecifying yourerror class hierarchies with one class per state, or replicatingthe type-checking control flow within thecnd_body() method. Noneof these options are ideal.

A better option is to defineheader,body, orfooter fieldsin your condition object. These can be a static string, alambda-formula, or a function with the samesignature ascnd_header(),cnd_body(), orcnd_footer(). Thesefields override the message generics and make it easy to generatean error message tailored to the state in which the error wasconstructed.

Muffle a condition

Description

Unlikeexiting() handlers,calling() handlers must be explicitthat they have handled a condition to stop it from propagating toother handlers. Usecnd_muffle() within a calling handler (or asa calling handler, see examples) to prevent any other handlers frombeing called for that condition.

Usage

cnd_muffle(cnd)

Arguments

Value

Ifcnd is mufflable,cnd_muffle() jumps to the mufflerestart and doesn't return. Otherwise, it returnsFALSE.

Mufflable conditions

Most conditions signalled by base R are muffable, although the nameof the restart varies. cnd_muffle() will automatically call thecorrect restart for you. It is compatible with the followingconditions:

• warning andmessage conditions. In this casecnd_muffle()is equivalent tobase::suppressMessages() andbase::suppressWarnings().

• Bare conditions signalled withsignal() orcnd_signal(). Notethat conditions signalled withbase::signalCondition() are notmufflable.

• Interrupts are sometimes signalled with aresume restart onrecent R versions. When this is the case, you can muffle theinterrupt withcnd_muffle(). Check if a restart is availablewithbase::findRestart("resume").

If you callcnd_muffle() with a condition that is not mufflableyou will cause a new error to be signalled.

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

• Conditions captured withbase::tryCatch(),with_handlers() orcatch_cnd() are no longer mufflable. Muffling restartsmustbe called from acalling 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 thecorresponding signal. The type of signal depends on the class ofthe condition:

• A message is signalled if the condition inherits from"message". This is equivalent to signalling withinform() orbase::message().

• A warning is signalled if the condition inherits from"warning". This is equivalent to signalling withwarn() orbase::warning().

• An error is signalled if the condition inherits from"error". This is equivalent to signalling withabort() orbase::stop().

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

Usage

cnd_signal(cnd, ...)

Arguments

See Also

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

• abort(),warn() andinform() for creating and signallingstructured R conditions in one go.

• try_fetch() for establishing condition handlers forparticular 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

Usecnd_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 operatorsdefuse R expressions.expr(),enquo(), andenquos() are sufficient for mostpurposes but rlang provides these other operations, either forcompleteness or because they are useful to experts.

• exprs() is the plural variant ofexpr(). It returns a list ofexpressions. It is likebase::alist() but withinjection support.

• quo() andquos() are likeexpr() andexprs() but returnquosures instead of naked expressions. When you are defusingyour own local expressions (by opposition to function argumentswhere non-local expressions are supplied by your users), thereis generally no need to attach the current environment in aquosure. SeeWhat are quosures and when are they needed?.

• enexpr() andenexprs() are likeenquo() andenquos() butreturn naked expressions instead of quosures. These operatorsshould very rarely be used because they lose track of theenvironment of defused arguments.

• ensym() andensyms() are likeenexpr() andenexprs() butthey throw an error when the defused expressions are not simplesymbols. They also support strings which are interpreted assymbols. These functions are modelled on the behaviour of theleft-hand side of= and⁠<-⁠ where you can supply symbols andstrings interchangeably.

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

• enquo0 andenquos0() are likeenquo() andenquos() butwithout injection support. The injection operators⁠!!⁠,⁠!!!⁠,and⁠{{⁠ are not processed, instead they are preserved in thedefused expression. This makes it possible to defuseexpressions that potentially contain injection operators meantfor later use. The trade off is that it makes it harder forusers to inject expressions in your function. They have toenable injection explicitly withinject().

  None of the features ofdynamic dots are availablewhen defusing withenquos0(). For instance, trailing emptyarguments 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 symbolsmy_function3(foo)my_function4(foo, bar)# Complex expressions are an errortry(my_function3(1 + 1))try(my_function4(1 + 1, 10 * 2))# `enquo0()` and `enquos0()` disable injection operatorsautomatic_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 explicitlyinject(no_injection(foo(!!!1:3)))

Development notes -dots.R

Description

Development notes -dots.R

.__error_call__. flag in dots collectors

Dots collectors likedots_list() are a little tricky because theymay error out in different situations. Do we want to forward thecontext, 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 relevantcontext is the collector itself and we don't forward.

2. While collecting the dots, during evaluation of the suppliedarguments. In this case forwarding or not is irrelevant becauseexpressions in... are evaluated in their own environmentwhich is not connected to the collector's context.

3. While collecting the dots, during argument constraints checkssuch as determined by the.homonyms argument. In this case wewant to forward the context because the caller of the dotscollector is the one who determines the constraints for itsusers.

Box a final value for early termination

Description

A value boxed withdone() signals to its caller that itshould stop iterating. Use it to shortcircuit a loop.

Usage

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

Arguments

Value

Aboxed 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 findobjects when programming withdata-maskedfunctions.

m <- 10mtcars %>% 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 bothkinds of variables. Compare:

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

Note that.data is only a pronoun, it is not a real dataframe. This means that you can't take its names or map a functionover the contents of.data. Similarly,.env is not an actual Renvironment. For instance, it doesn't have a parent and thesubsetting operators behave differently.

.data versus the magrittr pronoun.

In amagrittr pipeline,.datais not necessarily interchangeable with the magrittr pronoun..With grouped data frames in particular,.data represents thecurrent group slice whereas the pronoun. represents the wholedata frame. Always prefer using.data in data-masked context.

Where does.data live?

The.data pronoun is automatically created for you bydata-masking functions using thetidy eval framework.You don't need to importrlang::.data or uselibrary(rlang) towork with this pronoun.

However, the.data object exported from rlang is useful to importin your package namespace to avoid a⁠R CMD check⁠ note whenreferring to objects from the data mask. R does not have any way ofknowing about the presence or absence of.data in a particularscope so you need to import it explicitly or equivalently declareit withutils::globalVariables(".data").

Note thatrlang::.data is a "fake" pronoun. Do not refer torlang::.data with the⁠rlang::⁠ qualifier in data maskingcode. Use the unqualified.data symbol that is automatically putin 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 likedots_list() but automatically spliceslist 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, processesunquoting and splicing operators, and evaluates them. Unlikedots_list(), it does not flatten spliced objects, instead theyare attributed aspliced class (seesplice()). You can processspliced objects manually, perhaps with a custom predicate (seeflatten_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-levelduplicate() andshallow_duplicate() functions. It is mostly meant for users ofthe C API of R, e.g. for debugging, experimenting, or prototyping Ccode 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 themalong the way to arguments.

• Collecting arguments inside data structures, e.g. withc() orlist().

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

1. You cansplice arguments saved in a list with the spliceoperator!!!.

2. You caninject names withglue syntax onthe left-hand side of⁠:=⁠.

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

Add dynamic dots support in your functions

If your function takes dots, adding support for dynamic features isas easy as collecting the dots withlist2() instead oflist().See alsodots_list(), which offers more control over the collection.

In general, passing... to a function that supports dynamic dotscauses 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 ignoredf(this = "that", )# Splice lists of arguments with `!!!`x <- list(alpha = "first", omega = "last")f(!!!x)# Inject a name using glue syntaxif (is_installed("glue")) {  nm <- "key"  f("{nm}" := "value")  f("prefix_{nm}" := "value")}

Embrace operator⁠{{⁠

Description

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

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

Under the hood

⁠{{⁠ combinesenquo() and!! in onestep. 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 thesearch path (seesearch_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 theglue operators⁠{⁠ and⁠{{⁠. These operators arenormally used to inject names withindynamic dots.englue() makes them available anywhere within a function.

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

Usage

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

Arguments

Details

englue("{{ var }}") is equivalent toas_label(enquo(var)). Itdefusesarg and transforms the expression to astring withas_label().

In dynamic dots, using only⁠{⁠ is allowed. Inenglue() you mustuse⁠{{⁠ at least once. Useglue::glue() for simpleinterpolation.

Before usingenglue() in a package, first ensure that glue isinstalled by adding it to your⁠Imports:⁠ section.

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

Wrappingenglue()

You can provide englue semantics to a user provided string by supplyingenv.In this example we create a variant ofenglue() that supports aspecial.qux pronoun by:

• Creating an environmentmasked_env that inherits from the userenv, the one where their data lives.

• Overriding theerror_arg anderror_call arguments to point toour own argument name and call environment. This pattern isslightly different from usual error context passing becauseenglue() is a backend function that uses its own error contextby default (and not a checking function that usesyour errorcontext 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(), youshould also consider exposingenv,error_arg anderror_callin yourenglue() 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 toas_label(quote(cyl))as_label(quote(1 + 1))as_label(letters)

Defuse function arguments

Description

enquo() andenquos()defuse function arguments.A defused expression can be examined, modified, and injected intoother expressions.

Defusing function arguments is useful for:

• Creating data-masking functions.

• Interfacing with anotherdata-masking functionusing thedefuse-and-inject pattern.

These are advanced tools. Make sure to first learn about the embraceoperator{{ inData mask programming patterns.⁠{{⁠ is easier to work with less theory, and it is sufficientin 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 aquosure andenquos()returns a list of quosures.

Implicit injection

Arguments defused withenquo() andenquos() automatically gaininjection support.

my_mean <- function(data, var) {  var <- enquo(var)  dplyr::summarise(data, mean(!!var))}# Can now use `!!` and `{{`my_mean(mtcars, !!sym("cyl"))

Seeenquo0() andenquos0() for variants that don't enableinjection.

See Also

• Defusing R expressions for an overview.

• expr() to defuse your own local expressions.

• Advanced defusal operators.

• base::eval() andeval_bare() for resuming evaluationof a defused expression.

Examples

# `enquo()` defuses the expression supplied by your userf <- function(arg) {  enquo(arg)}f(1 + 1)# `enquos()` works with arguments and dots. It returns a list of# expressionsf <- function(...) {  enquos(...)}f(1 + 1, 2 * 10)# `enquo()` and `enquos()` enable _injection_ and _embracing_ for# your usersg <- function(arg) {  f({{ arg }} * 2)}g(100)column <- sym("cyl")g(!!column)

Add backtrace from error handler

Description

entrace() is a low level function. Seeglobal_entrace() for auser-friendly way of enriching errors and other conditions fromyour RProfile.

• entrace() is meant to be used as a global handler. It enrichesconditions with a backtrace. Errors are saved tolast_error()and rethrown immediately. Messages and warnings are recorded intolast_messages() andlast_warnings() and let through.

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

entrace() also works as anoption(error = ) handler forcompatibility with versions of R older than 4.0.

When used as calling handler, rlang trims the handler invokationcontext 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 withentrace().cnd_entrace() to manually add a backtrace to acondition.

Examples

quote({  # Not run# Set `entrace()` globally in your RProfileglobalCallingHandlers(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 defaultand takes a variable number of named objects to populate it.

• new_environment() creates a child of the empty environment bydefault 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 mostcommon use is to provide a scope for the evaluation of Rexpressions. Not all languages have first class environments,i.e. can manipulate scope as regular objects. Reification of scopeis one of the most powerful features of R as it allows you to changewhat objects a function or expression sees when it is evaluated.

Environments also constitute a data structure in their ownright. They are a collection of uniquely named objects, subsettableby name and modifiable by reference. This latter property (seesection on reference semantics) is especially useful for creatingmutable OO systems (cf theR6 packageand theggproto systemfor extending ggplot2).

Inheritance

All R environments (except theempty environment) aredefined with a parent environment. An environment and itsgrandparents thus form a linear hierarchy that is the basis forlexical scoping inR. When R evaluates an expression, it looks up symbols in a givenenvironment. If it cannot find these symbols there, it keepslooking them up in parent environments. This way, objects definedin child environments have precedence over objects defined inparent environments.

The ability of overriding specific definitions is used in thetidyeval framework to create powerful domain-specific grammars. Acommon use of masking is to put data frame columns in scope. Seefor exampleas_data_mask().

Reference semantics

Unlike regular objects such as vectors, environments are anuncopyable object type. This means that if youhave multiple references to a given environment (by assigning theenvironment to another symbol with⁠<-⁠ or passing the environmentas argument to a function), modifying the bindings of one of thosereferences 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 defaultenv <- env(a = 1, b = "foo")env$bidentical(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 aresupplied through... as pairs of names and values or expressions.env_bind() is equivalent to evaluating a⁠<-⁠ expression withinthe given environment. This function should take care of themajority of use cases but the other variants can be useful forspecific problems.

• env_bind() takes namedvalues which are bound in.env.env_bind() is equivalent tobase::assign().

• env_bind_active() takes namedfunctions and creates activebindings in.env. This is equivalent tobase::makeActiveBinding(). An active binding executes afunction each time it is evaluated. The arguments are passed toas_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 enclosurethat are not actually in scope in the dynamic environment wherethe active bindings are invoked. This allows creative solutionsto difficult problems (see the implementations ofdplyr::do()methods for an example).

• env_bind_lazy() takes namedexpressions. This is equivalenttobase::delayedAssign(). The arguments are captured withexprs() (and thus support call-splicing and unquoting) andassigned to symbols in.env. These expressions are notevaluated immediately but lazily. Once a symbol is evaluated, thecorresponding expression is evaluated in turn and its value isbound to the symbol (the expressions are thus evaluated onlyonce, if at all).

• ⁠%<~%⁠ is a shortcut forenv_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 environmentmodified in place, invisibly.

Side effects

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

Like other side-effecty functions likepar() andoptions(),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 zapszaps <- 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$bmy_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$symbolenv$symboleval_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$fooenv$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 asnms and named after it.

Lock or unlock environment bindings

Description

Locked environment bindings trigger an error when an attempt ismade 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 aslong asnms and named after it.env_binding_lock() andenv_binding_unlock() return the old value ofenv_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 evaluatingbrowser() inenv. It persistently sets the environment for step-debugging.Supplyvalue = FALSE to disable browsing.

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

Usage

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

Arguments

Value

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

Mask bindings by defining symbols deeper in a scope

Description

This function is superseded. Please useenv() (and possiblyset_env() if you're masking the bindings for another object likea closure or a formula) instead.

env_bury() is likeenv_bind() but it creates the bindings in anew child environment. This makes sure the new bindings haveprecedence over old ones, without altering existing environments.Unlikeenv_bind(), this function does not have side effects andreturns a new environment (or object wrapping that environment).

Usage

env_bury(.env, ...)

Arguments

Value

A copy of.env enclosing the new environment containingbindings 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 aroundenv_get() andenv_poke()designed to retrieve a cached value fromenv.

• If thenm binding exists, it returns its value.

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

Usage

env_cache(env, nm, default)

Arguments

Value

Either the value ofnm ordefault if it did not existyet.

Examples

e <- env(a = "foo")# Returns existing bindingenv_cache(e, "a", "default")# Creates a `b` binding and returns its default valueenv_cache(e, "b", "default")# Now `b` is definede$b

Clone or coalesce an environment

Description

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

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

Both these functions preserve active bindings and promises (thelatter 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# environmentenv <- 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 environmentenv_bind(clone, a = "foo", c = 3)env_print(clone)env_print(env)# `env_coalesce()` copies bindings from one environment to anotherlhs <- 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 betweenenv andtheempty environment, includingenv. The depth ofenv is also the number of parents ofenv (since the emptyenvironment counts as a parent).

Usage

env_depth(env)

Arguments

Value

An integer.

See Also

The section on inheritance inenv() 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 enviromentenv. Bydefault, it does not look in the parent environments.env_get_list() extracts multiple objects from an environment intoa 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 ofenv_get() designed tocache 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 anenvironment owns bindings personally (withinherit set toFALSE, the default), or sees them in its own environment or inany of its parents (withinherit = TRUE).

Usage

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

Arguments

Value

A named logical vector as long asnms.

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 returnsTRUE ifx hasancestor among its parents.

Usage

env_inherits(env, ancestor)

Arguments

Is frame environment user facing?

Description

Detects ifenv is user-facing, that is, whether it's an environmentthat inherits from:

• The global environment, as would happen when called interactively

• A package that is currently being tested

If either is true, we considerenv to belong to an evaluationframe that was calleddirectly by the end user. This is bycontrast toindirect calls by third party functions which are notuser facing.

For instance thelifecycle packageusesenv_is_user_facing() to figure out whether a deprecated functionwas called directly or indirectly, and select an appropriateverbosity level as a function of that.

Usage

env_is_user_facing(env)

Arguments

Escape hatch

You can override the return value ofenv_is_user_facing() bysetting the global option"rlang_user_facing" to:

• TRUE orFALSE.

• A package name as a string. Thenenv_is_user_facing(x) returnsTRUE ifx inherits from the namespace corresponding to thatpackage name.

Examples

fn <- function() {  env_is_user_facing(caller_env())}# Direct call of `fn()` from the global envwith(global_env(), fn())# Indirect call of `fn()` from a packagewith(ns_env("utils"), fn())

Lock an environment

Description

Locked environments cannot be modified. An important example isnamespace environments which are locked by R when loaded in asession. Once an environment is locked it normally cannot beunlocked.

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

Usage

env_lock(env)env_is_locked(env)

Arguments

Value

The old value ofenv_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 ownnames.env_name() returns:

• "global" for the global environment.

• "empty" for the empty environment.

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

• "namespace:pkg" ifenv is the namespace of the package "pkg".

• Thename attribute ofenv if it exists. This is how thepackage environments and theimports environments store their names. The name of packageenvironments is typically "package:pkg".

• The empty string"" otherwise.

env_label() is exactly likeenv_name() but returns the memoryaddress 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 enviromentenv as acharacter vector. All names are returned, even those starting witha 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 (seeis_expression() for adiscussion of symbolic objects versus literal objects). However itis often more convenient to work with strings. In rlangterminology, the string corresponding to a symbol is called thename of the symbol (or by extension the name of an object boundto a symbol).

Encoding

There are deep encoding issues when you convert a string to symboland vice versa. Symbols arealways in the native encoding. Ifthat encoding (let's say latin1) cannot support some characters,these characters are serialised to ASCII. That's why you sometimessee strings looking like⁠<U+1234>⁠, especially if you're runningWindows (as R doesn't support UTF-8 as native encoding on thatplatform).

To alleviate some of the encoding pain,env_names() alwaysreturns 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 ofenv if calledwithn = 1, the grandparent withn = 2, etc.

• env_tail() searches through the parents and returns the onewhich hasempty_env() as parent.

• env_parents() returns the list of all parents, including theempty environment. This list is named usingenv_name().

See the section oninheritance inenv()'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 forenv_parent() andenv_tail(), a listof environments forenv_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 inenv ifcreateisTRUE. Ifcreate isFALSE and a binding does not alreadyexists, an error is issued.

Usage

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

Arguments

Details

Ifinherit isTRUE, the parents environments are checked foran existing binding to reassign. If not found andcreate isTRUE, a new binding is created inenv. The default value forcreate is a function ofinherit:FALSE when inheriting,TRUE otherwise.

This default makes sense because the inheriting case is mostlyfor overriding an existing binding. If not found, somethingprobably went wrong and it is safer to issue an error. Note thatthis is different to the base R operator⁠<<-⁠ which will createa binding in the global environment instead of the currentenvironment when no existing binding is found in the parents.

Value

The old value ofnm or azap sentinel if thebinding did not exist yet.

See Also

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

Pretty-print an environment

Description

This prints:

• Thelabel and the parent label.

• Whether the environment islocked.

• The bindings in the environment (up to 20 bindings). They areprinted succintly usingpillar::type_sum() (if available,otherwise uses an internal version of that generic). In additionfancy bindings (actives and promises) areindicated as such.

• Locked bindings get a⁠[L]⁠ tag

Note that printing a package namespace (seens_env()) withenv_print() will typically tag function bindings as⁠<lazy>⁠until they are evaluated the first time. This is because packagefunctions are lazily-loaded from disk to improve performance whenloading a package.

Usage

env_print(env = caller_env())

Arguments

Remove bindings from an environment

Description

env_unbind() is the complement ofenv_bind(). Likeenv_has(),it ignores the parent environments ofenv by default. Setinherit toTRUE to track down bindings in parent environments.

Usage

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

Arguments

Value

The input objectenv with its associated environmentmodified 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 is now defunctbecause recent versions of R no longer make it possible tounlock an environment.

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 functionbase::eval().Technically, it is a simple wrapper around the C functionRf_eval(). You generally don't need to useeval_bare() insteadofeval(). Its main advantage is that it handles stack-sensitivecalls (such asreturn(),on.exit() orparent.frame()) moreconsistently when you pass an enviroment of a frame on the callstack.

Usage

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

Arguments

Details

These semantics are possible becauseeval_bare() creates only oneframe on the call stack whereaseval() creates two frames, thesecond of which has the user-supplied environment as frameenvironment. When you supply an existing frame environment tobase::eval() there will be two frames on the stack with the sameframe environment. Stack-sensitive functions only detect thetopmost of these frames. We call these evaluation semantics"stack inconsistent".

Evaluating expressions in the actual frame environment has usefulpractical implications foreval_bare():

• return() calls are evaluated in frame environments that mightbe burried deep in the call stack. This causes a long return thatunwinds multiple frames (triggering theon.exit() event foreach frame). By contrasteval() only returns from theeval()call, one level up.

• on.exit(),parent.frame(),sys.call(), and generally allthe stack inspection functionssys.xxx() are evaluated in thecorrect frame environment. This is similar to how this type ofcalls can be evaluated deep in the call stack because of lazyevaluation, when you force an argument that has been passedaround several times.

The flip side of the semantics ofeval_bare() is that it can'tevaluatebreak ornext expressions even if called within aloop.

See Also

eval_tidy() for evaluation with data mask and quosuresupport.

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 ofbase::eval() that powers the tidyevaluation framework. Likeeval() it accepts user data asargument. Whereaseval() simply transforms the data to anenvironment,eval_tidy() transforms it to adata mask withas_data_mask(). Evaluating in a datamask enables the following features:

• Quosures. Quosures are expressions bundled withan environment. Ifdata is supplied, objects in the data maskalways have precedence over the quosure environment, i.e. thedata masks the environment.

• Pronouns. Ifdata is supplied, the.env and.datapronouns are installed in the data mask..env is a reference tothe calling environment and.data refers to thedataargument. These pronouns are an escape hatch for thedata 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. Useeval_tidy() when you'd like to support expressions referring tothe.data pronoun, or when you need to support quosures.

If you're evaluating an expression captured withinjection support, it is recommended to useeval_tidy() because users may inject quosures.

Note that unwrapping a quosure withquo_get_expr() does notguarantee that there is no quosures inside the expression. Quosuresmight be unquoted anywhere in the expression tree. For instance,the following does not work reliably in the presence of nestedquosures:

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

eval_tidy() always evaluates in a data mask, even whendata isNULL. Because of this, it has different stack semantics thanbase::eval():

• Lexical side effects, such as assignment with⁠<-⁠, occur in themask rather thanenv.

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

• The mask environment creates a new branch in the treerepresentation of backtraces (which you can visualise in abrowser() session withlobstr::cst()).

See alsoeval_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() andas_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 "))expreval(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 thefunction doesn't supportdynamic dots). Splice thelist of arguments with⁠!!!⁠.

• To call every function stored in a list (in conjunction withmap()/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 <- 10args <- 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 ~ cylexec("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 bindingsdata_env <- env(data = mtcars)eval(expr(lm(!!f, data)), data_env)

Defuse an R expression

Description

expr()defuses an R expression withinjection support.

It is equivalent tobase::bquote().

Arguments

See Also

• Defusing R expressions for an overview.

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

• Advanced defusal operators.

• sym() andcall2() for building expressions (symbols and callsrespectively) programmatically.

• base::eval() andeval_bare() for resuming evaluationof a defused expression.

Examples

# R normally returns the result of an expression1 + 1# `expr()` defuses the expression that you have supplied and# returns it instead of its valueexpr(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 expressionscall("with", call("mean", sym(var)))call("with", call2("c", !!!syms(vars)))

Process unquote operators in a captured expression

Description

expr_interp() is deprecated, please useinject() instead.

Usage

expr_interp(x, env = NULL)

Arguments

Turn an expression to a label

Description

expr_text() turns the expression into a single string, whichmight be multi-line.expr_name() is suitable for formattingnames. It works best with symbols and scalar types, but alsoaccepts calls.expr_label() formats the expression nicely for usein 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 encodedexpr_label("a\nb")# Names and expressions are quoted with ``expr_label(quote(x))expr_label(quote(a + b + c))# Long expressions are collapsedexpr_label(quote(foo({  1 + 2  print(x)})))

Print an expression

Description

expr_print(), powered byexpr_deparse(), is an alternativeprinter for R expressions with a few improvements over the base Rprinter.

• It colourisesquosures according to their environment.Quosures from the global environment are printed normally whilequosures from local environments are printed in unique colour (orin italic when all colours are taken).

• It wraps inlined objects in angular brackets. For instance, aninteger 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 optionwidth)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 ofexpressions (or expression wrappers such as formulas orquosures), deparsed withas_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 lefthandside, andf_env extracts the environment. All functions throw anerror iff is not a formula.

Usage

f_rhs(f)f_rhs(x) <- valuef_lhs(f)f_lhs(x) <- valuef_env(f)f_env(x) <- value

Arguments

Value

f_rhs andf_lhs return language objects (i.e. atomicvectors of length 1, a name, or a call).f_env returns anenvironment.

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 ofexpr_text() andexpr_label() for formulas.

Usage

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

Arguments

Examples

f <- ~ a + b + bcf_text(f)f_label(f)# Names a quoted with ``f_label(~ x)# Strings are encodedf_label(~ "a\nb")# Long expressions are collapsedf_label(~ foo({  1 + 2  print(x)}))

Global options for rlang

Description

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

• rlang_interactive: A logical value used byis_interactive(). Thiscan be set toTRUE to test interactive behavior in unit tests,for example.

• rlang_backtrace_on_error: A character string which controls whetherbacktraces are displayed with error messages, and the level ofdetail they print. Seerlang_backtrace_on_error for the possible option values.

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

• rlang_trace_top_env: An environment which will be treated as thetop-level environment when printing traces. Seetrace_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 ofpurrr::list_c() andpurrr::list_flatten().

flatten() removes one level hierarchy from a list, whilesquash() removes all levels. These functions are similar tounlist() but they are type-stable so you always know what thetype 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 logicalvector,flatten_int() an integer vector,flatten_dbl() adouble vector, andflatten_chr() a character vector. Similarlyforsquash() and the typed variants (squash_lgl() etc).

Examples

x <- replicate(2, sample(4), simplify = FALSE)xflatten(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 aroundbase::body(). It alwaysreturns a⁠\{⁠ expression and throws an error when the input is aprimitive function (whereasbody() returnsNULL). The setterversion 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 (seeenv()).When a function call is evaluated, R creates an evaluation framethat inherits from the closure environment. This makes all objectsdefined in the closure environment and all its parents available tocode executed within the function.

Usage

fn_env(fn)fn_env(x) <- value

Arguments

Details

fn_env() returns the closure environment offn. There is alsoan 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_envidentical(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. Thisis especially useful for forwarding arguments inconstructed calls.

Usage

fn_fmls(fn = caller_fn())fn_fmls_names(fn = caller_fn())fn_fmls_syms(fn = caller_fn())fn_fmls(fn) <- valuefn_fmls_names(fn) <- value

Arguments

Details

Unlikeformals(), these helpers throw an error with primitivefunctions instead of returningNULL.

See Also

call_args() andcall_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 singlestring (or an empty vector if the input is empty). The elements ofthe input vector are assembled as a list of bullets, depending ontheir 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 areformatted as "*" bullets.

The bullet formatting for errors follows the idea that sentences inerror messages are best kept short and simple. The best way topresent the information is in thecnd_body() method of an errorconditon as a bullet list of simple sentences containing a singleclause. The info and cross symbols of the bullets provide hints onhow to interpret the bullet relative to the general error issue,which should be supplied ascnd_header().

Usage

format_error_bullets(x)

Arguments

Examples

# All bulletswriteLines(format_error_bullets(c("foo", "bar")))# This is equivalent towriteLines(format_error_bullets(set_names(c("foo", "bar"), "*")))# Supply named elements to format info, cross, and tick bulletswriteLines(format_error_bullets(c(i = "foo", x = "bar", v = "baz", "*" = "quux")))# An unnamed element breaks the linewriteLines(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 theinput is an environment,error_call() acts likeframe_call()with some additional logic, e.g. for S3 methods and for frameswith alocal_error_call().

• format_error_call() simplifies its input to a simple call (seesection below) and formats the result as code (using cli ifavailable). Use this function to generate the "in" part of anerror message from a stack frame call.

  format_error_call() first passes its input toerror_call() tofetch calls from frame environments.

Usage

format_error_call(call)error_call(call)

Arguments

Value

Either a string formatted as code orNULL if a simplecall could not be generated.

Details of formatting

• The arguments of function calls are stripped.

• Complex function calls containing inlined objects returnNULL.

• Calls toif preserve the condition since it might beinformative. Branches are dropped.

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

Examples

# Arguments are strippedwriteLines(format_error_call(quote(foo(bar, baz))))# Returns `NULL` with complex calls such as those that contain# inlined functionsformat_error_call(call2(list))# Operators are formatted using their names rather than in# function call formwriteLines(format_error_call(quote(1 + 2)))

Format a type for error messages

Description

friendly_type() is deprecated. Please use thestandalone-obj-type.R file instead. You can import itin your package withusethis::use_standalone("r-lib/rlang", "obj-type").

Usage

friendly_type(type)

Arguments

Value

A string of the prettified type, qualified with anindefinite 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, theenvironment of the current evaluation frame is returned. If youcallget_env() with an environment, it acts as the identityfunction and the environment is simply returned (this helpssimplifying 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

Whileset_env() returns a modified copy and does not have sideeffects,env_poke_parent() operates changes the environment byside effect. This is because environments areuncopyable. Be careful not to change environmentsthat you don't own, e.g. a parent environment of a function from apackage.

See Also

quo_get_env() andquo_set_env() for versions ofget_env() andset_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 messageswith rlang features.

• They are assigned a backtrace. You can configure whether todisplay a backtrace on error with therlang_backtrace_on_errorglobal option.

• They are recorded inlast_error(),last_warnings(), orlast_messages(). You can inspect backtraces at any time bycalling 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

Callglobal_entrace() inside an RMarkdown document to causeerrors and warnings to be promoted to rlang conditions that includea backtrace. This needs to be done in a separate setup chunk beforethe first error or warning.

This is useful in conjunction withrlang_backtrace_on_error_report andrlang_backtrace_on_warning_report. To get full entracing in anRmd document, include this in a setup chunk before the first erroror 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 handlerwithglobalCallingHandlers(). On older R versions,entrace() isset as anoption(error = ) handler. The latter method has thedisadvantage that only one handler can be set at a time. This meansthat you need to manually switch betweenentrace() and otherhandlers likerecover(). Also this causes a conflict with IDEhandlers (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 frompackageNotFoundErrorswith a user prompt to install the missing package. Note that atthe time of writing (R 4.1), there are only very limitedsituations where this handler works.

Usage

global_handle(entrace = TRUE, prompt_install = TRUE)

Arguments

Prompt user to install missing packages

Description

When enabled,packageNotFoundError thrown byloadNamespace()cause a user prompt to install the missing package and continuewithout interrupting the current program.

This is similar to howcheck_installed() prompts users to installrequired packages. It uses the same install strategy, using pak ifavailable andinstall.packages() otherwise.

Usage

global_prompt_install(enable = TRUE)

Arguments

Name injection with"{" and"{{"

Description

Dynamic dots (anddata-masked dots which are dynamic by default) have built-in support for names interpolation with theglue package.

tibble::tibble(foo = 1)#> # A tibble: 1 x 1#>     foo#>   <dbl>#> 1     1foo <- "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 alsoenglue() 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, callsas_label() on the expression supplied as argument, and inserts the result in the string.

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

Whileglue::glue() only supports⁠"{"⁠, dynamic dots support both⁠"{"⁠ and⁠"{{"⁠. The double brace variant is similar to the embrace operator{{ available indata-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.19mtcars %>% 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.19mtcars %>% 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] 1list2("{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. SeeDoes {{ work on regular objects? for more information about this limitation.

Allow overriding default names

The implementation ofmy_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 likemy_mean() that takes a named argument we need a different approach.

This is whereenglue() 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.06mtcars %>% 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=.

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 anobject. 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 dataframe or another named object contains an element with a specificname. Note thathas_name() only works with vectors. For instance,environments need the specialised functionenv_has().

Usage

has_name(x, name)

Arguments

Details

Unnamed objects are treated as if all names are empty strings.NAinput givesFALSE as output.

Value

A logical vector of the same length asname

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 thathave 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, whichgenerates a 128-bit hash. Both are implemented as streaming hashes, whichgenerate the hash with minimal extra memory usage.

Forhash(), objects are converted to binary using R's native serializationtools. On R >= 3.5.0, serialization version 3 is used, otherwise version 2 isused. Seeserialize() for more information about the serialization version.

Value

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

• Forhash_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 likebase::inherits() but is more explicitabout its behaviour with multiple classes. Ifclasses containsseveral elements and the object inherits from at least one ofthem,inherits_any() returnsTRUE.

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

• inherits_only() tests that the class vectors are identical. Itis a shortcut foridentical(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 withinjectionsupport. 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 formulasprogrammatically.

• Pass arguments to NSE functions thatdefuse theirarguments without injection support (see for instanceenquo0()). You can use{{ arg }} with functions documentedto 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 * 3inject(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

Theinjection operator⁠!!⁠ injects a value orexpression inside another expression. In other words, it modifies apiece of code before R evaluates it.

There are two main cases for injection. You can inject constantvalues to work around issues ofscoping ambiguity, and you can injectdefused expressions likesymbolised column names.

Where does⁠!!⁠ work?

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

• Functions takingdefused anddata-masked arguments.

  Technically, this means function arguments defused with{{ oren-prefixed operators likeenquo(),enexpr(), etc.

• Insideinject().

All data-masking verbs in the tidyverse support injection operatorsout of the box. With base functions, you need to useinject() toenable⁠!!⁠. Using⁠!!⁠ out of context may lead to incorrectresults, seeWhat happens if I use injection operators out of context?.

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

Injecting values

Data-masking functions likewith() are handy because you canrefer to column names in your computations. This comes at the priceof data mask ambiguity: if you have defined an env-variable of thesame name as a data-variable, you get a name collisions. Thiscollision is always resolved by giving precedence to thedata-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 toinject 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 theambiguity. SeeThe data mask ambiguity for more aboutthis.

Injecting expressions

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

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

Sincewith() is a base function, you can't injectquosures, only naked symbols and calls. Thisisn't a problem here because we're injecting the name of a dataframe column. If the environment is important, try injecting apre-computed value instead.

When do I need⁠!!⁠?

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

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

Second, the embrace operator{{ makes thedefuse-and-inject pattern easier tolearn and use.

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

⁠!!⁠ is a good tool to learn for advanced applications but ourhope 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 issignalled withCtrl-C. It is currently not possible to createcustom interrupt condition objects.

Usage

interrupt()

Invoke a function with a list of arguments

Description

Deprecated in rlang 0.4.0 in favour ofexec().

Usage

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

Arguments

Is object a call?

Description

This function tests ifx is acall. This is apattern-matching predicate that returnsFALSE ifname andnare 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 functionposition of a call (as opposed to argument position). This includessymbolic objects that evaluate to a function orliteral functions embedded in the call.

Usage

is_callable(x)

Arguments

Details

Note that strings may look like callable objects becauseexpressions of the form"list"() are valid R code. However,that's only because the R parser transforms strings to symbols. Itis 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::identityif (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 (sometimeslazily) to enforcevalue semantics.However, some internal types are uncopyable. If you try to copythem, either with⁠<-⁠ or by argument passing, you actually createreferences to the original object rather than actualcopies. Modifying these references can thus have far reaching sideeffects.

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)

Is a vector uniquely named?

Description

Likeis_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 whetherx is an environment without a s3 ors4 class.

Usage

is_environment(x)is_bare_environment(x)

Arguments

Is an object an expression?

Description

In rlang, anexpression is the return type ofparse_expr(), theset of objects that can be obtained from parsing R code. Under thisdefinition expressions include numbers, strings,NULL, symbols,and function calls. These objects can be classified as:

• Symbolic objects, i.e. symbols and function calls (for whichis_symbolic() returnsTRUE)

• Syntactic literals, i.e. scalar atomic objects andNULL(testable withis_syntactic_literal())

is_expression() returnsTRUE if the input is either a symbolicobject or a syntactic literal. If a call, the elements of the callmust all be expressions as well. Unparsable calls are notconsidered expressions in this narrow definition.

Note that in base R, there existsexpression() vectors, a datatype similar to a list that supports special attributes created bythe parser called source references. This data type is notsupported in rlang.

Usage

is_expression(x)is_syntactic_literal(x)is_symbolic(x)

Arguments

Details

is_symbolic() returnsTRUE for symbols and calls (objects withtypelanguage). Symbolic objects are replaced by their valueduring evaluation. Literals are the complement of symbolicobjects. They are their own value and return themselves duringevaluation.

is_syntactic_literal() is a predicate that returnsTRUE for thesubset of literals that are created by R when parsing text (seeparse_expr()): numbers, strings andNULL. 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 thatevaluates to itself and that can be evaluated in the emptyenvironment. For instance,quote(c(1, 2)) is not a literal, it isa call. However, the result of evaluating it inbase_env() is aliteral(in this case an atomic vector).

As the data structure for function arguments, pairlists are also akind of language objects. However, since they are mostly aninternal data structure and can't be returned as is by the parser,is_expression() returnsFALSE 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 whetherx is a call to~.is_bare_formula()tests in addition thatx does not inherit from anything else than"formula".

Note: When we first implementedis_formula(), we thought itbest to treat unevaluated formulas as formulas by default (seesection below). Now we think this default introduces too many edgecases in normal code. We recommend always supplyingscoped = TRUE. Unevaluated formulas can be handled via ais_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 nothave a class or an environment. Once evaluated, the~ callbecomes a properly structured formula. Unevaluated formulas ariseby quotation, e.g.~~foo,quote(~foo), orsubstitute(arg)witharg being supplied a formula. Use thescoped argument tocheck 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 formulasis_formula(f)# Supply `scoped = TRUE` to ensure you have an evaluated formulais_formula(f, scoped = TRUE)# By default unevaluated formulas not treated as bare formulasis_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: primitivefunctions, which are low-level, and closures, which are the regularkind 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 theirarguments are scoped within nested environments (seehttps://en.wikipedia.org/wiki/Closure_(computer_programming)). Theroot environment of the closure is called the closureenvironment. When closures are evaluated, a new environment calledthe evaluation frame is created with the closure environment asparent. This is where the body of the closure is evaluated. Theseclosure frames appear on the evaluation stack, as opposed toprimitive functions which do not necessarily have their ownevaluation frame and never appear on the stack.

Primitive functions are more efficient than closures for tworeasons. First, they are written entirely in fast low-levelcode. Second, the mechanism by which they are passed arguments ismore efficient because they often do not need the full procedure ofargument matching (dealing with positional versus named arguments,partial matching, etc). One practical consequence of the specialway in which primitives are passed arguments is that theytechnically do not have formal arguments, andformals() willreturnNULL if called on a primitive function. Finally, primitivefunctions 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()andis_primitive_lazy() allow you to check whether a primitivefunction evaluates arguments eagerly or lazily.

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

You can call primitive functions with.Primitive() and internalfunctions with.Internal(). However, calling internal functionsin a package is forbidden by CRAN's policy because they areconsidered part of the private API. They often assume that theyhave been called with correctly formed arguments, and may cause Rto 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 sideeffects. If installed, the packages will be loaded but notattached.

• is_installed() doesn't interact with the user. It simplyreturnsTRUE orFALSE depending on whether the packages areinstalled.

• In interactive sessions,check_installed() asks the userwhether to install missing packages. If the user accepts, thepackages are installed withpak::pkg_install() if available, orutils::install.packages() otherwise. If the session is noninteractive or if the user chooses not to install the packages,the current evaluation is aborted.

You can disable the prompt by setting therlib_restart_package_not_found global option toFALSE. In thatcase, 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() returnsTRUE ifall package namesprovided inpkg are installed,FALSEotherwise.check_installed() either doesn't return or returnsNULL.

Handling package not found errors

check_installed() signals error conditions of classrlib_error_package_not_found. The error includespkg andversion fields. They are vectorised and may include severalpackages.

The error is signalled with arlib_restart_package_not_foundrestart on the stack to allow handlers to install the requiredpackages. To do so, add acalling handlerforrlib_error_package_not_found, install the required packages,and invoke the restart without arguments. This restarts the checkfrom scratch.

The condition is not signalled in non-interactive sessions, in therestarting case, or if therlib_restart_package_not_found useroption is set toFALSE.

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 beinteger-like, according to its own tolerance check (which is infact delegated to the C library). This function is not adapted todata analysis, see the help forbase::is.integer() for examplesof 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 hasto be traversed and checked.

• Large double values may be integerish but may still not becoercible to integer. This is because integers in R only supportvalues up to2^31 - 1 while numbers stored as double can bemuch 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 abase 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

Likebase::interactive(),is_interactive() returnsTRUE whenthe function runs interactively andFALSE when it runs in batchmode. It also checks, in this order:

• Therlang_interactive global option. If set to a singleTRUEorFALSE,is_interactive() returns that value immediately. Thisescape hatch is useful in unit tests or to manually turn oninteractive features in RMarkdown outputs.

• Whether knitr or testthat is in progress, in which caseis_interactive() returnsFALSE.

with_interactive() andlocal_interactive() set the globaloption 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 useis_call() and itsnargument instead.

Usage

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

Arguments

Is object named?

Description

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

• is_named2() is likeis_named() but always returnsTRUE forempty vectors, even those that don't have anames attribute.In other words, it tests for the property that each element of avector is named.is_named2() composes well withnames2()whereasis_named() composes withnames().

• have_name() is a vectorised variant.

Usage

is_named(x)is_named2(x)have_name(x)

Arguments

Details

is_named() always returnsTRUE for empty vectors because

Value

is_named() andis_named2() are scalar predicates thatreturnTRUE orFALSE.have_name() is vectorised and returnsa 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 predicatehave_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] <- NAis_named(invalid)have_name(invalid)# A data frame normally has valid, unique namesis_named(mtcars)have_name(mtcars)# A matrix usually doesn't because the names are stored in a# different attributemat <- 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 thatx has typepairlist.

• is_node() checks thatx has typepairlist orlanguage.It tests whetherx is a node that has a CAR and a CDR,including callable nodes (language objects).

• is_node_list() checks thatx has typepairlist orNULL.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 goodnaming 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 tothe same object.

• R objects usually have copy-on-write semantics. This is anoptimisation that ensures that objects are only copied ifneeded. When you copy a vector, no memory is actually copieduntil you modify either the original object or the copy ismodified.

  Note that the copy-on-write optimisation is an implementationdetail that is not guaranteed by the specification of the Rlanguage.

• Assigning anuncopyable object (like anenvironment) creates a reference. These objects are never copiedeven 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 <- envis_reference(ref, env)# Due to copy-on-write optimisation, a copied vector can# temporarily reference the original vector:vec <- 1:10copy <- vecis_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]] <- 100is_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 checkthatx is literallyTRUE orFALSE.

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 usecall2() andnew_call() instead.

Usage

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

Arguments

Lastabort() error

Description

• last_error() returns the last error entraced byabort() orglobal_entrace(). The error is printed with a backtrace insimplified form.

• last_trace() is a shortcut to return the backtrace stored inthe 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 anerror is thrown.

• global_entrace() to enablelast_error() logging for all errors.

• last_warnings() andlast_messages().

Display last messages and warnings

Description

last_warnings() andlast_messages() return a list of allwarnings and messages that occurred during the last R command.

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

By default the warnings and messages are printed with a simplifiedbacktrace, likelast_error(). Usesummary() to print theconditions with a full backtrace.

Usage

last_warnings(n = NULL)last_messages(n = NULL)

Arguments

Examples

Enable backtrace capture withglobal_entrace():

global_entrace()

Signal some warnings in nested functions. The warnings inform aboutwhich function emitted a warning but they don't provide informationabout 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

Calllast_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 tolist(...) with a few additionalfeatures, collectively calleddynamic dots. Whilelist2() hard-code these features,dots_list() is a lower-levelversion 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 bydefault. By comparisonlist2() implements the preferred behaviourof 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 (whichis by default the caller environment). The bindings are reset totheir original values when the current frame (or an arbitrary oneif you specify.frame) goes out of scope.

• with_bindings() evaluatesexpr with temporary bindings. Whenwith_bindings() returns, bindings are reset to their originalvalues. It is a simple wrapper aroundlocal_bindings().

Usage

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

Arguments

Value

local_bindings() returns the values of old bindingsinvisibly;with_bindings() returns the value ofexpr.

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 acall argument toabort(). It sets the call (or a value thatindicates where to find the call, see below) in a local bindingthat is automatically picked up byabort().

Usage

local_error_call(call, frame = caller_env())

Arguments

Motivation for setting local error calls

By defaultabort() uses the function call of its caller ascontext in error messages:

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

This is not always appropriate. For example a function that checksan input on the behalf of another function should reference thelatter, 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 nothave anyx argument and so it is confusing to presentarg_check() as being the relevant context for the failure of thex argument.

One way around this is to take acall orerror_call argumentand pass it toabort(). Here we name this argumenterror_callfor consistency witherror_arg which is prefixed because there isan existingarg argument. In other situations, takingarg andcall 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 checkingfunctions. If you mention an argument in an error message, provideyour callers a way to supply a different argument name and adifferent error call.abort() stores the error call in thecallcondition field which is then used to generate the "in" part oferror messages.

In more complex cases it's often burdensome to pass the relevantcall around, for instance if your checking and throwing code isstructured into many different functions. In this case, uselocal_error_call() to set the call locally or instructabort()to climb the call stack one level to find the relevant call. In thefollowing example, the complexity is not so important that sparingthe argument passing makes a big difference. However thisillustrates 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

Thecall argument can also be the string"caller". This isequivalent tocaller_env() orparent.frame() but has a loweroverhead because call stack introspection is only performed when anerror is triggered. Note that eagerly callingcaller_env() isfast enough in almost all cases.

If your function needs to be really fast, assign the error callflag directly instead of callinglocal_error_call():

.__error_call__. <- "caller"

Examples

# Set a context for error messagesfunction() {  local_error_call(quote(foo()))  local_error_call(sys.call())}# Disable the contextfunction() {  local_error_call(NULL)}# Use the caller's contextfunction() {  local_error_call(caller_env())}

Change global options

Description

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

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

• push_options() adds or changes options permanently.

• peek_option() andpeek_options() return option values. Theformer returns the option directly while the latter returns alist.

Usage

local_options(..., .frame = caller_env())with_options(.expr, ...)push_options(...)peek_options(...)peek_option(name)

Arguments

Value

Forlocal_options() andpush_options(), the old optionvalues.peek_option() returns the current value of an optionwhile the pluralpeek_options() returns a list of currentoption 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 arunning function with a special flag that instructsabort() touse 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 vialast_error().

• WhenconditionMessage() is called.

cli formats messages and bullets with indentation andwidth-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 surerun_on_load() is called from your.onLoad() hook.

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

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

Missing values

Description

Missing values are represented in R with the general symbolNA. They can be inserted in almost all data containers: allatomic vectors except raw vectors can contain missing values. Toachieve this, R automatically converts the generalNA symbol to atyped missing value appropriate for the target vector. The objectsprovided here are aliases for those typedNA objects.

Usage

na_lglna_intna_dblna_chrna_cpl

Format

An object of classlogical of length 1.

An object of classinteger of length 1.

An object of classnumeric of length 1.

An object of classcharacter of length 1.

An object of classcomplex of length 1.

Details

Typed missing values are necessary because R needs sentinel valuesof the same type (i.e. the same machine representation of the data)as the containers into which they are inserted. The official typedmissing values areNA_integer_,NA_real_,NA_character_ andNA_complex_. The missing value for logical vectors is simply thedefaultNA. The aliases provided in rlang are consistently namedand thus simpler to remember. Also,na_lgl is provided as analias toNA that makes intent clearer.

Sincena_lgl is the defaultNA, expressions such asc(NA, NA)yield logical vectors as no data is available to give a clue of thetarget type. In the same way, since lists and environments cancontain any types, expressions likelist(NA) store a logicalNA.

Life cycle

These shortcuts might be moved to the vctrs package at somepoint. 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 <- NAtypeof(na_dbl)

Generate or handle a missing argument

Description

These functions help using the missing argument as a regular Robject.

• missing_arg() generates a missing argument.

• is_missing() is likebase::missing() but also supportstesting for missing arguments contained in other objects likelists. It is also more consistent with default arguments whichare never treated as missing (see section below).

• maybe_missing() is useful to pass down an input that might bemissing to another function, potentially substituting by adefault 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 missingargument object.

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

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

is_missing() and default arguments

The base functionmissing() makes a distinction between defaultvalues supplied explicitly and default values generated through amissing argument:

fn <- function(x = 1) base::missing(x)fn()#> [1] TRUEfn(1)#> [1] FALSE

This only happens within a function. If the default value has beengenerated 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 treatingdefault arguments as missing, even in internal contexts:

fn <- function(x = 1) rlang::is_missing(x)fn()#> [1] FALSEfn(1)#> [1] FALSE

This is a little less flexible because you can't specialisebehaviour based on implicitly supplied default values. However,this makes the behaviour ofis_missing() and functions using itsimpler to understand.

Fragility of the missing argument object

The missing argument is an object that triggers an error if andonly if it is the result of evaluating a symbol. No error isproduced when a function call evaluates to the missing argumentobject. For instance, it is possible to bind the missing argumentto a variable with an expression likex[[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 betweenfunctions through a bare variable, it is likely to cause a missingargument error:

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

To work around this,is_missing() andmaybe_missing(x) use abit of magic to determine if the input is the missing argumentwithout triggering a missing error.

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

maybe_missing() is particularly useful for prototypingmeta-programming algorithms in R. The missing argument is a likelyinput when computing on the language because it is a standardobject in formals lists. While C functions are always allowed toreturn the missing argument and pass it to other C functions, thisis not the case on the R side. If you're implementing yourmeta-programming algorithm in R, usemaybe_missing() when aninput 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 callsargs <- 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]])

Get names of a vector

Description

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

The replacement variant⁠names2<-⁠ never addsNA names andinstead 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:3names(x)[1:2] <- "foo"names(x)# Use the `names2<-` variant to avoid thisx <- 1:3names2(x)[1:2] <- "foo"names(x)

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 withinform() and are given the class"rlib_message_name_repair". These messages can be muffled withbase::suppressMessages().

Name repair messages can also be silenced with the global optionrlib_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 notsignaled. This is particularly useful for silencing messages during testingwhen combined withlocal_options().

Create vectors matching a given length

Description

These functions construct vectors of a given length, with attributesspecified via dots. Except fornew_list() andnew_raw(), theempty vectors are filled with typedmissing values. This is incontrast to the base functionbase::vector() which createszero-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 inthe future. They are in the questioning lifecycle stage.

See Also

rep_along

Examples

new_list(10)new_logical(10)

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() lettersg <- 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 lowlevel R data structures at the C level. We export them at the R levelin order to make it easy to prototype C code. They don't performany type checking and can crash R very easily (try to take the CARof 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 likenode_poke_car() invisibly returnx modifiedin place. Getters return the requested node component.

See Also

duplicate() for creating copy-safe objects andbase::pairlist() for an easier way of creating a linked list ofnodes.

Create a quosure from components

Description

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

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

Usage

new_quosure(expr, env = caller_env())as_quosure(x, env = NULL)is_quosure(x)

Arguments

See Also

• enquo() andquo() for creating a quosure byargument 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[ andc() and ensuresthe 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 thequosuresclass and a vector of empty names if needed.as_quosures() callsas_quosure() on all elements before creating thequosuresobject.

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 areference 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 theobject, similar to WeakMaps in JavaScript.

Objects in R are consideredreachable if they can be accessed by followinga chain of references, starting from aroot node; root nodes arespecially-designated R objects, and include the global environment and baseenvironment. As long as the key is reachable, the value will not be garbagecollected. This is true even if the weak reference object becomesunreachable. The key effectively prevents the weak reference and its valuefrom being collected, according to the following chain of ownership:weakref <- key -> value.

When the key becomes unreachable, the key and value in the weak referenceobject are replaced byNULL, 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() andwref_value().

Examples

e <- env()# Create a weak reference to ew <- new_weakref(e, finalizer = function(e) message("finalized"))# Get the key object from the weak referenceidentical(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)

Get the namespace of a package

Description

Namespaces are the environment where all the functions of a packagelive. The parent environments of namespaces are theimportsenvironments, which contain all the functions imported from otherpackages.

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 normalenvironment because the parent isNULL instead of the emptyenvironment. This is exported for expert usage in development toolsonly.

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 machineeach time the package is loaded in memory. This is by contrast tonormal R package code which is run once at build time on thepackager's machine (e.g. CRAN).

  on_load() expressions requirerun_on_load() to be calledinside.onLoad().

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

on_load() is for your own package and runs expressions when thenamespace is notsealed yet. This means you can modify existingbinding or create new ones. This is not the case withon_package_load() which runs expressions after a foreign packagehas 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 withs3_register(), must occur in the user session rather than thepackage builder session.

2. To avoid hard-coding objects from other packages in yournamespace. If you assignfoo::bar or the result offoo::baz() in your package, they become constants. Anyupstream changes in thefoo package will not be reflected inthe objects you've assigned in your namespace. This often breaksassumptions made by the authors offoo and causes all sorts ofissues.

   Recreating the foreign objects each time your package is loadedmakes sure that any such changes will be taken into account. Intechnical terms, running an expression on load introducesindirection.

Comparison with.onLoad()

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

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

The expressions insideon_load() do not undergo static analysisby⁠R CMD check⁠. Therefore, it is advisable to only usesimple function calls insideon_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 loadon_load({  s3_register("foo::bar", "my_class")})# Assign an object on loadvar <- NULLon_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 directlyf <- function() on_package_load("foo", message("foo is loaded"))})

Infix attribute accessor and setter

Description

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

Usage

x %@% namex %@% name <- value

Arguments

Examples

# Unlike `@`, this operator extracts attributes for any kind of# objects:factor(1:3) %@% "levels"mtcars %@% classmtcars %@% class <- NULLmtcars# 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 bereplaced by a vctrs-powered operator (probably in thefuns package) at which point therlang version of⁠%|%⁠ will be deprecated.

This infix function is similar to%||% but is vectorisedand provides a default value for missing elements. It is fasterthan usingbase::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 forNULL

Description

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

Usage

x %||% y

Arguments

Examples

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

Collect dynamic dots in a pairlist

Description

This pairlist constructor usesdynamic dots. Useit to manually create argument lists for calls or parameter listsfor 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. Thisis the first step to interpret or evaluate a piece of R codewritten by a programmer.

• parse_expr() returns one expression. If the text contains morethan one expression (separated by semicolons or new lines), anerror is issued. On the other handparse_exprs() can handlemultiple expressions. It always returns a list of expressions(compare tobase::parse() which returns a base::expressionvector). All functions also support R connections.

• parse_expr() concatenatesx with⁠\\n⁠ separators prior toparsing in order to support the roundtripparse_expr(expr_deparse(x)) (deparsed expressions might bemultiline). On the other hand,parse_exprs() doesn't do anyconcatenation because it's designed to support named inputs. Thenames are matched to the expressions in the output, which isuseful when a single named string creates multiple expressions.

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

• parse_quo() andparse_quos() are variants that create aquosure. Supplyenv = current_env() if you're parsingcode to be evaluated in your current context. Supplyenv = global_env() when you're parsing external user input to beevaluated in user context.

  Unlike quosures created withenquo(),enquos(), or⁠{{⁠, aparsed quosure never contains injected quosures. It is thus safeto evaluate them witheval() instead ofeval_tidy(), thoughthe latter is more convenient as you don't need to extractexprandenv.

Usage

parse_expr(x)parse_exprs(x)parse_quo(x, env)parse_quos(x, env)

Arguments

Details

Unlikebase::parse(), these functions never retain source referenceinformation, as doing so is slow and rarely necessary.

Value

parse_expr() returns anexpression,parse_exprs() returns a list of expressions. Note that for theplural variants the length of the output may be greater than thelength of the input. This would happen is one of the stringscontain several expressions (such as"foo; bar"). The names ofx 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 \nparse_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 examininginjected expressionsinside a function. This is useful for learning about injection andfor debugging injection code.

Arguments

Examples

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

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

It is especially useful inside functions to reveal what an injectedexpression 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 usequo_squash() instead.

Usage

quo_expr(quo, warn = FALSE)

Arguments

Format quosures for printing or labelling

Description

Note: You should now useas_label() oras_name() insteadofquo_name(). See life cycle section below.

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

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

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

These deparsers are only suitable for creating default names orprinting output at the console. The behaviour of your functionsshould not depend on deparsed objects. If you are looking for a wayof transforming symbols to strings, useas_string() instead ofquo_name(). Unlike deparsing, the transformation between symbolsand 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() andas_name() should be used instead ofquo_name().as_label() transforms any R object to a stringbut should only be used to create a default name. Labelisation isnot a well defined operation and no assumption should be madeabout the label. On the other hand,as_name() only works with(possibly quosured) symbols, but is a well defined anddeterministic operation.

• We don't have a good replacement forquo_text() yet. Seehttps://github.com/r-lib/rlang/issues/636 to follow discussionsabout 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 bareexpressionfoo(bar(), baz).

This operation is safe if the squashed quosure is used forlabelling or printing (seeas_label(), but note thatas_label()squashes quosures automatically). However if the squashed quosureis evaluated, all expressions of the flattened quosures areresolved in a single environment. This is a source of bugs so it isgood practice to setwarn toTRUE to let the user know aboutthe lossy squashing.