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 streamed 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 warningNA# Return an alternative value})# You can also specify metadata that will be stored in the condition:abort("The error message.","mypkg_bad_error", data=1:10)# This data can then be consulted by user handlers:tryCatch(  mypkg_function(),  mypkg_bad_error=function(err){# Compute an alternative return value with the data:    recover_error(err$data)})# If you call low-level APIs it may be a good idea to create a# chained error with the low-level error wrapped in a more# user-friendly error. Use `try_fetch()` to fetch errors of a given# class and rethrow them with the `parent` argument of `abort()`:file<-"http://foo.bar/baz"try(  try_fetch(    download(file),    error=function(err){      msg<- sprintf("Can't download `%s`", file)      abort(msg, parent= err)}))# You can also hard-code the call when it's not easy to# forward it from the caller f<-function(){  abort("my message", call= call("my_function"))}g<-function(){  f()}# Shows that the error occurred in `my_function()`try(g())}

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

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

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

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)

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)

Description

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

Usage

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

Arguments

Examples

f<- as_function(~ .x+1)f(10)g<- as_function(~-1* .)g(4)h<- as_function(~ .x- .y)h(6,3)# Functions created from a formula have a special class:is_lambda(f)is_lambda(as_function(function()"foo"))

Description

as_label() transforms R objects into a short, human-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)

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

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

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

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

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

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)

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)

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)

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

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

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

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

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

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)

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

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

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

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)

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"

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.

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

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)

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.

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

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

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

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)

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)

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

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

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.

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

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.

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)

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

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

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)

Description

This returnsTRUE ifx hasancestor among its parents.

Usage

env_inherits(env, ancestor)

Arguments

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

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

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)

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

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.

Description

This prints:

• Thelabel and the parent label.

• Whether the environment islocked.

• The bindings in the environment (up to 20 bindings). They areprinted succinctly 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

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)

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

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)

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)

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

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)

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

Description

f_rhs extracts the right-hand side,f_lhs extracts the left-handside, andf_env extracts the environment in which the formula was defined.All functions throw an error 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)f<- as.formula("y ~ x", env= new.env())f_env(f)

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

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.

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

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)

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

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

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)

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

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