The main change of this release is the new tidy evaluation operator{{. This operator abstracts the quote-and-unquote idiominto a single interpolation step:

my_wrapper <- function(data, var, by) {  data %>%    group_by({{ by }}) %>%    summarise(average = mean({{ var }}, na.rm = TRUE))}

{{ var }} is a shortcut for!!enquo(var)that should be easier on the eyes, and easier to learn and teach.

Note that for multiple inputs, the existing documentation doesn’tstress enough that you can just pass dots straight to other tidy evalfunctions. There is no need for quote-and-unquote unless you need tomodify the inputs or their names in some way:

my_wrapper <- function(data, var, ...) {  data %>%    group_by(...) %>%    summarise(average = mean({{ var }}, na.rm = TRUE))}

More robust.envpronoun

Another improvement to tidy evaluation should make it easier to usethe.env pronoun. Starting from this release, subsetting anobject from the.env pronoun now evaluates thecorresponding symbol. This makes.env more robust, inparticular in magrittr pipelines. The following example would previouslyfail:

foo <- 10mtcars %>% mutate(cyl = cyl * .env$foo)

This way, using the.env pronoun is now equivalent tounquoting a constant objects, but with an easier syntax:

mtcars %>% mutate(cyl = cyl * !!foo)

Note that following this change, and despite its name,.env is no longer referring to a bare environment. Instead,it is a special shortcut with its own rules. Similarly, the.data pronoun is not really a data frame.

New functions and features

• Newpairlist2() function with splicing support. Itpreserves missing arguments, which makes it useful for lists of formalparameters for functions.

• is_bool() is a scalar type predicate that checkswhether its input is a singleTRUE orFALSE.Likeis_string(), it returnsFALSE when theinput is missing. This is useful for type-checking function arguments(#695).

• is_string() gains astring argument.is_string(x, "foo") is a shortcut foris_character(x) && length(x) == 1 && identical(x, "foo").

• Lists of quosures now have pillar methods for display intibbles.

• set_names() now names unnamed input vectors beforeapplying a function. The following expressions are now equivalent:

  letters %>% set_names() %>% set_names(toupper)letters %>% set_names(toupper)

• You can now pass a character vector as message argument forabort(),warn(),inform(), andsignal(). The vector is collapsed to a single string with a"\n" newline separating each element of the input vector(#744).

• maybe_missing() gains adefaultargument.

• New functions for weak references:new_weakref(),weakref_key(),weakref_value(), andis_weakref() (@wch, #787).

Performance

• The performance ofexec() has been improved. It isnow on the same order of performance asdo.call(), thoughslightly slower.

• call2() now uses the newpairlist2()function internally. This considerably improves its performance. Thisalso means it now preserves empty arguments:

  call2("fn", 1, , foo = )#> fn(1, , foo = )

Bugfixes and smallimprovements

• with_handlers() now installs calling handlers firston the stack, no matter their location in the argument list. This waythey always take precedence over exiting handlers, which ensures theirside effects (such as logging) take place (#718).

• In rlang backtraces, theglobal:: prefix is now onlyadded when the function directly inherits from the global environment.Functions inheriting indirectly no longer have a namespace qualifier(#733).

• options(error = rlang::entrace) now has bettersupport for errors thrown from C (#779). It also saves structured errorsin theerror field ofrlang::last_error().

• ns_env() andns_env_name()(experimental functions) now support functions and environmentsconsisently. They also require an argument from now on.

• is_interactive() is aware of theTESTTHAT environment variable and returnsFALSE when it is"true" (@jennybc, #738).

• fn_fmls() and variants no longer coerce their inputto a closure. Instead, they throw an error.

• Fixed an issue in knitr that caused backtraces to print even whenerror = TRUE.

• The return object fromas_function() now inheritsfrom"function" (@richierocks, #735).

Lifecycle

We commit to support 5 versions of R. As R 3.6 is about to bereleased, rlang now requires R 3.2 or greater. We’re also continuing ourefforts to streamline and narrow the rlang API.

• modify() andprepend() (twoexperimental functions marked as in the questioning stage since rlang0.3.0) are now deprecated. Vector functions are now out of scope forrlang. They might be revived in the vctrs or funs packages.

• exiting() is soft-deprecated becausewith_handlers() treats handlers as exiting bydefault.

• The vector constructors likelgl() ornew_logical() are now in the questioning stage. They arelikely to be moved to the vctrs package at some point. Same for themissing values shortcuts likena_lgl.

• as_logical(),as_integer(), etc havebeen soft-deprecated in favour ofvctrs::vec_cast().

• type_of(),switch_type(),coerce_type(), and friends are soft-deprecated.

• The encoding and locale API was summarily archived. This APIdidn’t bring any value and wasn’t used on CRAN.

• lang_type_of(),switch_lang(), andcoerce_lang() were archived. These functions were not usedon CRAN or internally.

• Subsetting quosures with[ or[[ issoft-deprecated.

• All functions that were soft-deprecated, deprecated, or defunctin previous releases have been bumped to the next lifecyclestage.

rlang 0.3.2

• Fixed protection issue reported by rchk.

• The experimental optionrlang__backtrace_on_error isno longer experimental and has been renamed torlang_backtrace_on_error.

• New “none” option forrlang_backtrace_on_error.

• Unary operators applied to quosures now give better errormessages.

• Fixed issue with backtraces of warnings promoted to error, andentraced viawithCallingHandlers(). The issue didn’t affectentracing via top leveloptions(error = rlang::entrace)handling.

rlang 0.3.1

This patch release polishes the new backtrace feature introduced inrlang 0.3.0 and solves bugs for the upcoming release of purrr 0.3.0. Italso featuresas_label() andas_name() whichare meant to replacequo_name() in the future. Finally, abunch of deparsing issues have been fixed.

Backtrace fixes

• Newentrace() condition handler. Add this to yourRProfile to enable rlang backtraces for all errors, including warningspromoted to errors:

  if (requireNamespace("rlang",quietly =TRUE)) {options(error = rlang::entrace)}

  This handler also works as a calling handler:

  with_handlers(error =calling(entrace),foo(bar))

  However it’s often more practical to usewith_abort() inthat case:

  with_abort(foo(bar))

• with_abort() gains aclasses argumentto promote any kind of condition to an rlang error.

• Newlast_trace() shortcut to print the backtracestored in thelast_error().

• Backtrace objects now print in full by default.

• Calls in backtraces are now numbered according to their positionin the call tree. The numbering is non-contiguous for simplifiedbacktraces because of omitted call frames.

• catch_cnd() gains aclasses argument tospecify which classes of condition to catch. It returnsNULL if the expected condition could not be caught(#696).

as_label() andas_name()

The newas_label() andas_name() functionsshould be used instead ofquo_name() to transform objectsand quoted expressions to a string. We have noticed that tidy eval usersoften usequo_name() to extract names from quosuredsymbols. This is not a good use for that function because the wayquo_name() creates a string is not a well definedoperation.

For this reason, we are replacingquo_name() with twonew functions that have more clearly defined purposes, and hopefullybetter names reflecting those purposes. Useas_label() totransform any object to a short human-readable description, andas_name() to extract names from (possibly quosured)symbols.

Create labels withas_label() 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.

We expectas_label() to gain additional parameters inthe future, for example to control the maximum width of a label. The wayan object is labelled is thus subject to change.

On the other hand,as_name() transforms symbols back toa string in a well defined manner. Unlikeas_label(),as_name() 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 resultingstring. If you know you have a symbol and need the name of the object itrefers to, useas_name(). For instance, useas_label() with objects captured withenquo()andas_name() with symbols captured withensym().

Note thatquo_name() will only be soft-deprecated at thenext major version of rlang (0.4.0). At this point, it will startissuing once-per-session warnings in scripts, but not in packages. Itwill then be deprecated in yet another major version, at which point itwill issue once-per-session warnings in packages as well. You thus haveplenty of time to change your code.

Minor fixes and features

• Newis_interactive() function. It serves the samepurpose asbase::interactive() but also checks if knitr isin progress and provides an escape hatch. Usewith_interactive() andscoped_interactive() tooverride the return value ofis_interactive(). This isuseful in unit tests or to manually turn on interactive features inRMarkdown outputs

• calling() now boxes its argument.

• Newdone() function to box a value. Done boxes aresentinels to indicate early termination of a loop or computation. Forinstance, it will be used in the purrr package to allow users toshortcircuit a reduction or accumulation.

• new_box() now accepts additional attributes passedtostructure().

• Fixed a quotation bug with binary operators of zero or oneargument such as`/`(1) (#652). They are now deparsed andprinted properly as well.

• Newcall_ns() function to retrieve the namespace ofa call. ReturnsNULL if the call is notnamespaced.

• Top-level S3 objects are now deparsed properly.

• Empty{ blocks are now deparsed on the sameline.

• Fixed a deparsing issue with symbols containing non-ASCIIcharacters (#691).

• expr_print() now handles[ and[[ operators correctly, and deparses non-syntactic symbolswith backticks.

• call_modify() now respects ordering of unnamedinputs. Before this fix, it would move all unnamed inputs after namedones.

• as_closure() wrappers now call primitives withpositional arguments to avoid edge case issues of argumentmatching.

• as_closure() wrappers now dispatch properly onmethods defined in the global environment(tidyverse/purrr#459).

• as_closure() now supports both base-style(e1 ande2) and purrr-style (.xand.y) arguments with binary primitives.

• exec() takes.fn as first argumentinstead off, for consistency with other rlangfunctions.

• Fixed infinite loop with quosures created inside a datamask.

• Base errors set asparent of rlang errors are nowprinted correctly.

rlang 0.3.0

Breaking changes

The rlang API is still maturing. In this section, you’ll find hardbreaking changes. See the life cycle section below for an exhaustivelist of API changes.

• quo_text() now deparses non-syntactic symbols withbackticks:

  quo_text(sym("foo+"))#> [1] "`foo+`"

  This caused a number of issues in reverse dependencies asquo_text() tends to be used for converting symbols tostrings.quo_text() andquo_name() should notbe used for this purpose because they are general purpose deparsers.These functions should generally only be used for printing outputs orcreating default labels. If you need to convert symbols to strings,please useas_string() rather thanquo_text().

  We have extended the documentation of?quo_text and?quo_name to make these points clearer.

• exprs() no longer flattens quosures.exprs(!!!quos(x, y)) is now equivalent toquos(x, y).

• The sentinel for removing arguments incall_modify()has been changed fromNULL tozap(). Thisbreaking change is motivated by the ambiguity ofNULL withvalid argument values.

  call_modify(call,arg =NULL)# Add `arg = NULL` to the callcall_modify(call,arg =zap())# Remove the `arg` argument from the call

• The%@% operator now quotes its input and supportsS4 objects. This makes it directly equivalent to@ exceptthat it extracts attributes for non-S4 objects (#207).

• Taking theenv_parent() of the empty environment isnow an error.

Summary

The changes for this version are organised around three main themes:error reporting, tidy eval, and tidy dots.

• abort() now records backtraces automatically in theerror object. Errors thrown withabort() invite users tocallrlang::last_error() to see a backtrace and helpidentifying where and why the error occurred. The backtraces created byrlang (you can create one manually withtrace_back()) areprinted in a simplified form by default that removes implementationdetails from the backtrace. To see the full backtrace, callsummary(rlang::last_error()).

  abort() also gains aparent argument. Thisis meant for situations where you’re calling a low level API (todownload a file, parse a JSON file, etc) and would like to intercepterrors withbase::tryCatch() orrlang::with_handlers() and rethrow them with a high-levelmessage. Callabort() with the intercepted error as theparent argument. When the user printsrlang::last_error(), the backtrace will be shown in twosections corresponding to the high-level and low-level contexts.

  In order to get segmented backtraces, the low-level error has to bethrown withabort(). When that’s not the case, you can callthe low-level function withinwith_abort() to automaticallypromote all errors to rlang errors.

• The tidy eval changes are mostly for developers of data maskingAPIs. The main user-facing change is that.data[[ is now anunquote operator so thatvar in.data[[var]]is never masked by data frame columns and always picked from theenvironment. This makes the pronoun safe for programming infunctions.

• The!!! operator now supports all classed objectslike factors. It callsas.list() on S3 objects andas(x, "list") on S4 objects.

• dots_list() gains several arguments to control howdots are collected. You can control the selection of arguments with thesame name with.homonyms (keep first, last, all, or abort).You can also elect to preserve empty arguments with.preserve_empty.

Conditions and errors

• Newtrace_back() captures a backtrace. Compared tothe base R traceback, it contains additional structure about therelationship between frames. It comes with tools for automaticallyrestricting to frames after a certain environment on the stack, and tosimplify when printing. These backtraces are now recorded in errorsthrown byabort() (see below).

• abort() gains aparent argument tospecify a parent error. This is meant for situations where a low-levelerror is expected (e.g. download or parsing failed) and you’d like tothrow an error with higher level information. Specifying the low-levelerror as parent makes it possible to partition the backtraces based onancestry.

• Errors thrown withabort() now embed a backtrace inthe condition object. It is no longer necessary to record a trace with acalling handler for such errors.

• with_abort() runs expressions in a context where allerrors are promoted to rlang errors and gain a backtrace.

• Unhandled errors thrown byabort() are nowautomatically saved and can be retrieved withrlang::last_error(). The error prints with a simplifiedbacktrace. Callsummary(last_error()) to see the fullbacktrace.

• New experimental optionrlang__backtrace_on_error todisplay backtraces alongside error messages. See?rlang::abort for supported options.

• The newsignal() function completes theabort(),warn() andinform()family. It creates and signals a bare condition.

• Newinterrupt() function to simulate an userinterrupt from R code.

• cnd_signal() now dispatches messages, warnings,errors and interrupts to the relevant signalling functions(message(),warning(),stop() andthe C functionRf_onintr()). This makes it a good choice toresignal a captured condition.

• Newcnd_type() helper to determine the type of acondition ("condition","message","warning","error" or"interrupt").

• abort(),warn() andinform() now accepts metadata with.... Thedata are stored in the condition and can be examined by userhandlers.

  Consequently all arguments have been renamed and prefixed with a dot(to limit naming conflicts between arguments and metadatanames).

• with_handlers() treats bare functions as exitinghandlers (equivalent to handlers supplied totryCatch()).It also supports the formula shortcut for lambda functions (as inpurrr).

• with_handlers() now produces a cleaner stacktrace.

Tidy dots

• The input types of!!! have been standardised.!!! is generally defined on vectors: it takes a vector(typically, a list) and unquotes each element as a separate argument.The standardisation makes!!! behave the same in functionstaking dots withlist2() and in quoting functions.!!! accepts these types:

  • Lists, pairlists, and atomic vectors. If they have a class, theyare converted withbase::as.list() to allow S3 dispatch.Following this change, objects like factors can now be spliced withoutdata loss.

  • S4 objects. These are converted withas(obj, "list")before splicing.

  • Quoted blocks of expressions, i.e. { }calls

  !!! disallows:

  • Any other objects like functions or environments, but also languageobjects like formula, symbols, or quosures.

  Quoting functions used to automatically wrap language objects inlists to make them spliceable. This behaviour is now soft-deprecated andit is no longer valid to write!!!enquo(x). Please unquotescalar objects with!! instead.

• dots_list(),enexprs() andenquos() gain a.homonyms argument to controlhow to treat arguments with the same name. The default is to keep them.Set it to"first" or"last" to keep only thefirst or last occurrences. Set it to"error" to raise aninformative error about the arguments with duplicated names.

• enexprs() andenquos() now support.ignore_empty = "all" with named arguments as well(#414).

• dots_list() gains a.preserve_emptyargument. WhenTRUE, empty arguments are stored as missingarguments (see?missing_arg).

• dots_list(),enexprs() andenquos() gain a.check_assign argument. WhenTRUE, a warning is issued when a<- call isdetected in.... No warning is issued if the assignment iswrapped in brackets like{ a <- 1 }. The warning letsusers know about a possible typo in their code (assigning instead ofmatching a function parameter) and requires them to be explicit thatthey really want to assign to a variable by wrapping inparentheses.

• lapply(list(quote(foo)), list2) no longer evaluatesfoo (#580).

Tidy eval

• You can now unquote quosured symbols as LHS of:=.The symbol is automatically unwrapped from the quosure.

• Quosure methods have been defined for common operations like==. These methods fail with an informative error messagesuggesting to unquote the quosure (#478,#tidyverse/dplyr#3476).

• as_data_pronoun() now accepts data masks. If themask has multiple environments, all of these are looked up whensubsetting the pronoun. Function objects stored in the mask arebypassed.

• It is now possible to unquote strings in function position. Thisis consistent with how the R parser coerces strings to symbols. Thesetwo expressions are now equivalent:expr("foo"()) andexpr((!!"foo")()).

• Quosures converted to functions withas_function()now support nested quosures.

• expr_deparse() (used to print quosures at theconsole) now escapes special characters. For instance, newlines nowprint as"\n" (#484). This ensures that the roundtripparse_expr(expr_deparse(x)) is not lossy.

• new_data_mask() now throws an error whenbottom is not a child oftop (#551).

• Formulas are now evaluated in the correct environment withineval_tidy(). This fixes issues in dplyr and othertidy-evaluation interfaces.

• New functionsnew_quosures() andas_quosures() to create or coerce to a list of quosures.This is a small S3 class that ensures two invariants on subsetting andconcatenation: that each element is a quosure and that the list isalways named even if only with a vector of empty strings.

Environments

• env() now treats a single unnamed argument as theparent of the new environment. Consequently,child_env() isnow superfluous and is now in questioning life cycle.

• Newcurrent_env() andcurrent_fn()functions to retrieve the current environment or the function beingevaluated. They are equivalent tobase::environment() andbase::sys.function() called without argument.

• env_get() andenv_get_list() gain adefault argument to provide a default value fornon-existing bindings.

• env_poke() now returns the old value invisiblyrather than the input environment.

• The new functionenv_name() returns the name of anenvironment. It always adds the “namespace:” prefix to namespace names.It returns “global” instead of “.GlobalEnv” or “R_GlobalEnv”, “empty”instead of “R_EmptyEnv”. The companionenv_label() is likeenv_name() but returns the memory address for anonymousenvironments.

• env_parents() now returns a named list. The namesare taken withenv_name().

• env_parents() andenv_tail() now stopat the global environment by default. This can be changed with thelast argument. The empty environment is always a stoppingcondition so you can take the parents or the tail of an environment onthe search path without changing the default.

• New predicatesenv_binding_are_active() andenv_binding_are_lazy() detect the kind of bindings in anenvironment.

• env_binding_lock() andenv_binding_unlock() allows to lock and unlock multiplebindings. The predicateenv_binding_are_locked() tests ifbindings are locked.

• env_lock() andenv_is_locked() lock anenvironment or test if an environment is locked.

• env_print() pretty-prints environments. It shows thecontents (up to 20 elements) and the properties of theenvironment.

• is_scoped() has been soft-deprecated and renamed tois_attached(). It now supports environments in addition tosearch names.

• env_bind_lazy() andenv_bind_active()now support quosures.

• env_bind_exprs() andenv_bind_fns() aresoft-deprecated and renamed toenv_bind_lazy() andenv_bind_active() for clarity and consistency.

• env_bind(),env_bind_exprs(), andenv_bind_fns() now return the list of old binding values(or missing arguments when there is no old value). This makes it easy torestore the original environment state:

  old <- env_bind(env, foo = "foo", bar = "bar")env_bind(env, !!!old)

• env_bind() now supports binding missing argumentsand removing bindings with zap sentinels.env_bind(env, foo = ) binds a missing argument andenv_bind(env, foo = zap()) removes thefoobinding.

• Theinherit argument ofenv_get() andenv_get_list() has changed position. It now comes afterdefault.

• scoped_bindings() andwith_bindings()can now be called without bindings.

• env_clone() now recreates active bindingscorrectly.

• env_get() now evaluates promises and active bindingssince these are internal objects which should not be exposed at the Rlevel (#554)

• env_print() callsget_env() on itsargument, making it easier to see the environment of closures andquosures (#567).

• env_get() now supports retrieving missing argumentswheninherit isFALSE.

Calls

• is_call() now accepts multiple namespaces. Forinstanceis_call(x, "list", ns = c("", "base")) will matchifx islist() or if it’sbase::list():

• call_modify() has better support for... and now treats it like a named argument.call_modify(call, ... = ) adds... to the callandcall_modify(call, ... = NULL) removes it.

• call_modify() now preserves empty arguments. It isno longer necessary to usemissing_arg() to add a missingargument to a call. This is possible thanks to the new.preserve_empty option ofdots_list().

• call_modify() now supports removing unexistingarguments (#393) and passing multiple arguments with the same name(#398). The new.homonyms argument controls how to treatthese arguments.

• call_standardise() now handles primitive functionslike~ properly (#473).

• call_print_type() indicates how a call is deparsedand printed at the console by R: prefix, infix, and specialform.

• Thecall_ functions such ascall_modify() now correctly check that their input is theright type (#187).

Other improvements and fixes

• New functionzap() returns a sentinel that instructsfunctions likeenv_bind() orcall_modify()that objects are to be removed.

• New functionrep_named() repeats value along acharacter vector of names.

• New functionexec() is a simpler replacement toinvoke() (#536).invoke() has beensoft-deprecated.

• Lambda functions created from formulas withas_function() are now classed. Useis_lambda()to check a function was created with the formula shorthand.

• is_integerish() now supports large double values(#578).

• are_na() now requires atomic vectors(#558).

• The operator%@% has now a replacement version toupdate attributes of an object (#207).

• fn_body() always returns a{ block,even if the function has a single expression. For instancefn_body(function(x) do()) returnsquote({ do() }).

• is_string() now returnsFALSE forNA_character_.

• The vector predicates have been rewritten in C forperformance.

• Thefinite argument ofis_integerish()is nowNULL by default. Missing values are now consideredas non-finite for consistency withbase::is.finite().

• is_bare_integerish() andis_scalar_integerish() gain afinite argumentfor consistency withis_integerish().

• flatten_if() andsquash_if() now handleprimitive functions likebase::is.list() aspredicates.

• is_symbol() now accepts a character vector of namesto mach the symbol against.

• parse_exprs() andparse_quos() nowsupport character vectors. Note that the output may be longer than theinput as each string may yield multiple expressions (such as"foo; bar").

• parse_quos() now adds thequosuresclass to its output.

Lifecycle

Soft-deprecatedfunctions and arguments

rlang 0.3.0 introduces a new warning mechanism for soft-deprecatedfunctions and arguments. A warning is issued, but only under one ofthese circumstances:

• rlang has been attached with alibrary() call.
• The deprecated function has been called from the globalenvironment.

In addition, deprecation warnings appear only once per session inorder to not be disruptive.

Deprecation warnings shouldn’t make R CMD check fail for packagesusing testthat. However,expect_silent() can transform thewarning to a hard failure.

tidyeval

• .data[[foo]] is now an unquote operator. Thisguarantees thatfoo is evaluated in the context rather thanthe data mask and makes it easier to treat.data[["bar"]]the same way as a symbol. For instance, this will help ensuring thatgroup_by(df, .data[["name"]]) andgroup_by(df, name) produce the same column name.

• Automatic naming of expressions now uses a new deparser (stillunexported) instead ofquo_text(). Following this change,automatic naming is now compatible with all object types (viapillar::type_sum() if available), prevents multi-linenames, and ensuresname and.data[["name"]]are given the same default name.

• Supplying a name with!!! calls is soft-deprecated.This name is ignored because only the names of the spliced vector areapplied.

• Quosure lists returned byquos() andenquos() now have “list-of” behaviour: the types of newelements are checked when adding objects to the list. Consequently,assigning non-quosure objects to quosure lists is now soft-deprecated.Please coerce to a bare list withas.list()beforehand.

• as_quosure() now requires an explicit environmentfor symbols and calls. This should typically be the environment in whichthe expression was created.

• names() andlength() methods for datapronouns are deprecated. It is no longer valid to writenames(.data) orlength(.data).

• Usingas.character() on quosures is soft-deprecated(#523).

Miscellaneous

• Usingget_env() without supplying an environment isnow soft-deprecated. Please usecurrent_env() to retrievethe current environment.

• The frame and stack API is soft-deprecated. Some of thefunctionality has been replaced bytrace_back().

• Thenew_vector_along() family is soft-deprecatedbecause these functions are longer to type than the equivalentrep_along() orrep_named() calls without addedclarity.

• Passing environment wrappers like formulas or functions toenv_ functions is now soft-deprecated. This internalgenericity was causing confusion (see issue #427). You should nowextract the environment separately before calling these functions.

  This change concernsenv_depth(),env_poke_parent(),env_parent<-,env_tail(),set_env(),env_clone(),env_inherits(),env_bind(),scoped_bindings(),with_bindings(),env_poke(),env_has(),env_get(),env_names(),env_bind_exprs() andenv_bind_fns().

• cnd_signal() now always installs a muffling restartfor non-critical conditions. Consequently the.mufflableargument has been soft-deprecated and no longer has any effect.

Deprecated functions andarguments

Deprecated functions and arguments issue a warning inconditionally,but only once per session.

• CallingUQ() andUQS() with the rlangnamespace qualifier is deprecated as of rlang 0.3.0. Just use theunqualified forms instead:

  # Badrlang::expr(mean(rlang::UQ(var) * 100))# Okrlang::expr(mean(UQ(var) * 100))# Goodrlang::expr(mean(!!var * 100))

  Although soft-deprecated since rlang 0.2.0,UQ() andUQS() can still be used for now.

• Thecall argument ofabort() andcondition constructors is now deprecated in favour of storing fullbacktraces.

• The.standardise argument ofcall_modify() is deprecated. Please usecall_standardise() beforehand.

• Thesentinel argument ofenv_tail() hasbeen deprecated and renamed tolast.

Defunct functions andarguments

Defunct functions and arguments throw an error when used.

• as_dictionary() is now defunct.

• The experimental functionrst_muffle() is nowdefunct. Please usecnd_muffle() instead. Unlike itspredecessor,cnd_muffle() is not generic. It is marked as acalling handler and thus can be passed directly towith_handlers() to muffle specific conditions (such asspecific subclasses of warnings).

• cnd_inform(),cnd_warn() andcnd_abort() are retired and defunct. The oldcnd_message(),cnd_warning(),cnd_error() andnew_cnd() constructorsdeprecated in rlang 0.2.0 are now defunct.

• Modifying a condition withcnd_signal() is defunct.In addition, creating a condition withcnd_signal() issoft-deprecated, please use the new function [signal()]instead.

• inplace() has been renamed tocalling()to follow base R terminology more closely.

Functions andarguments in the questioning stage

We are no longer convinced these functions are the right approach butwe do not have a precise alternative yet.

• The functions from the restart API are now in the questioninglifecycle stage. It is not clear yet whether we want to recommendrestarts as a style of programming in R.

• prepend() andmodify() are in thequestioning stage, as well asas_logical(),as_character(), etc. We are still figuring out what vectortools belong in rlang.

• flatten(),squash() and their atomicvariants are now in the questioning lifecycle stage. They have slightlydifferent semantics than the flattening functions in purrr and we arecurrently rethinking our approach to flattening with the new typingfacilities of the vctrs package.

rlang 0.2.2

This is a maintenance release that fixes several garbage collectionprotection issues.

rlang 0.2.1

This is a maintenance release that fixes several tidy evaluationissues.

• Functions with tidy dots support now allow splicing atomicvectors.

• Quosures no longer capture the currentsrcref.

• Formulas are now evaluated in the correct environment byeval_tidy(). This fixes issues in dplyr and othertidy-evaluation interfaces.

rlang 0.2.0

This release of rlang is mostly an effort at polishing the tidyevaluation framework. All tidy eval functions and operators have beenrewritten in C in order to improve performance. Capture of expression,quasiquotation, and evaluation of quosures are now vastly faster. On theUI side, many of the inconveniences that affected the first release ofrlang have been solved:

• The!! operator now has the precedence of unary+ and- which allows a much more naturalsyntax:!!a > b only unquotesa rather thanthe wholea > b expression.

• enquo() works in magrittr pipes:mtcars %>% select(!!enquo(var)).

• enquos() is a variant ofquos() thathas a more natural interface for capturing multiple arguments and....

See the first section below for a complete list of changes to thetidy evaluation framework.

This release also polishes the rlang API. Many functions have beenrenamed as we get a better feel for the consistency and clarity of theAPI. Note that rlang as a whole is still maturing and some functions areeven experimental. In order to make things clearer for users of rlang,we have started to develop a set of conventions to document the currentstability of each function. You will now find “lifecycle” sections indocumentation topics. In addition we have gathered all lifecycleinformation in the?rlang::lifecycle help page. Please onlyuse functions marked as stable in your projects unless you are preparedto deal with occasional backward incompatible updates.

Tidy evaluation

• The backend forquos(),exprs(),list2(),dots_list(), etc is now written in C.This greatly improve the performance of dots capture, especially withthe splicing operator!!! which now scales much better(you’ll see a 1000x performance gain in some cases). The unquotingalgorithm has also been improved which makesenexpr() andenquo() more efficient as well.

• The tidy eval!! operator now binds tightly. You nolonger have to wrap it in parentheses, i.e. !!x > y willonly unquotex.

  Technically the!! operator has the same precedence asunary- and+. This means that!!a:b and!!a + b are equivalent to(!!a):b and(!!a) + b. On the other hand!!a^b and!!a$b are equivalentto!!(a^b) and!!(a$b).

• The print method for quosures has been greatly improved. Quosuresno longer appear as formulas but as expressions prefixed with^; quosures are colourised according to their environment;unquoted objects are displayed between angular brackets instead of code(i.e. an unquoted integer vector is shown as<int: 1, 2> rather than1:2); unquotedS3 objects are displayed usingpillar::type_sum() ifavailable.

• Newenquos() function to capture arguments. Ittreats... the same way asquos() but can alsocapture named arguments just likeenquo(), i.e. one levelup. By comparisonquos(arg) only captures the namearg rather than the expression supplied to thearg argument.

  In addition,enexprs() is likeenquos() butlikeexprs() it returns bare expressions. Andensyms() expects strings or symbols.

• It is now possible to useenquo() within a magrittrpipe:

  select_one <- function(df, var) {  df %>% dplyr::select(!!enquo(var))}

  Technically, this is becauseenquo() now also capturesarguments in parents of the current environment rather than just in thecurrent environment. The flip side of this increased flexibility is thatif you made a typo in the name of the variable you want to capture, andif an object of that name exists anywhere in the parent contexts, youwill capture that object rather than getting an error.

• quo_expr() has been renamed toquo_squash() in order to better reflect that it is a lossyoperation that flattens all nested quosures.

• !!! now accepts any kind of objects for consistency.Scalar types are treated as vectors of length 1. Previously onlysymbolic objects like symbols and calls were treated as such.

• ensym() is a new variant ofenexpr()that expects a symbol or a string and always returns a symbol. If acomplex expression is supplied it fails with an error.

• exprs() andquos() gain a.unquote_names arguments to switch off interpretation of:= as a name operator. This should be useful forprogramming on the language targetting APIs such as data.table.

• exprs() gains a.named option toauto-label its arguments (#267).

• Functions taking dots by value rather than by expression(e.g. regular functions, not quoting functions) have a more restrictedset of unquoting operations. They only support:= and!!!, and only at top-level. I.e.dots_list(!!! x) is valid but notdots_list(nested_call(!!! x)) (#217).

• Functions taking dots withlist2() ordots_list() now support splicing ofNULLvalues.!!! NULL is equivalent to!!! list()(#242).

• Capture operators now support evaluated arguments. Capturing aforced or evaluated argument is exactly the same as unquoting thatargument: the actual object (even if a vector) is inlined in theexpression. Capturing a forced argument occurs when you useenquo(),enexpr(), etc too late. It alsohappens when your quoting function is supplied tolapply()or when you try to quote the first argument of an S3 method (which isnecessarily evaluated in order to detect which class to dispatch to).(#295, #300).

• Parentheses around!! are automatically removed.This makes the generated expression call cleaner:(!! sym("name"))(arg). Note that removing the parentheseswill never affect the actual precedence within the expression as theparentheses are only useful when parsing code as text. The parentheseswill also be added by R when printing code if needed (#296).

• Quasiquotation now supports!! and!!!as functional forms:

  expr(`!!`(var))quo(call(`!!!`(var)))

  This is consistent with the way native R operators parses to functioncalls. These new functional forms are to be preferred toUQ() andUQS(). We are now questioning thelatter and might deprecate them in a future release.

• The quasiquotation parser now gives meaningful errors in cornercases to help you figure out what is wrong.

• New getters and setters for quosures:quo_get_expr(),quo_get_env(),quo_set_expr(), andquo_set_env(). Compared toget_expr() etc, these accessors only work on quosures andare slightly more efficient.

• quo_is_symbol() andquo_is_call() nowtake the same set of arguments asis_symbol() andis_call().

• enquo() andenexpr() now deal withdefault values correctly (#201).

• Splicing a list no longer mutates it (#280).

Conditions

• The new functionscnd_warn() andcnd_inform() transform conditions to warnings or messagesbefore signalling them.

• cnd_signal() now returns invisibly.

• cnd_signal() andcnd_abort() now acceptcharacter vectors to create typed conditions with several S3subclasses.

• is_condition() is now properly exported.

• Condition signallers such ascnd_signal() andabort() now accept a call depth ascallarguments. This allows plucking a call from further up the call stack(#30).

• New helpercatch_cnd(). This is a small wrapperaroundtryCatch() that captures and returns any signalledcondition. It returnsNULL if none was signalled.

• cnd_abort() now adds the correct S3 classes forerror conditions. This fixes error catching, for instance bytestthat::expect_error().

Environments

• env_get_list() retrieves muliple bindings from anenvironment into a named list.

• with_bindings() andscoped_bindings()establish temporary bindings in an environment.

• is_namespace() is a snake case wrapper aroundisNamespace().

Various features

• New functionsinherits_any(),inherits_all(), andinherits_only(). Theyallow testing for inheritance from multiple classes. The_any variant is equivalent tobase::inherits()but is more explicit about its behaviour.inherits_all()checks that all classes are present in order andinherits_only() checks that the class vectors areidentical.

• Newfn_fmls<- andfn_fmls_names<-setters.

• New function experimental functionchr_unserialise_unicode() for turning characters serialisedto unicode point form (e.g. <U+xxxx>) to UTF-8. Inaddition,as_utf8_character() now translates those as well.(@krlmlr)

• expr_label() now supports quoted function definitioncalls (#275).

• call_modify() andcall_standardise()gain an argument to specify an environment. The call definition islooked up in that environment when the call to modify or standardise isnot wrapped in a quosure.

• is_symbol() gains aname argument tocheck that that the symbol name matches a string (#287).

• Newrlang_box class. Its purpose is similar to theAsIs class frombase::I(), i.e. it protects avalue temporarily. However it does so by wrapping the value in a scalarlist. Usenew_box() to create a boxed value,is_box() to test for a boxed value, andunbox() to unbox it.new_box() andis_box() accept optional subclass.

• The vector constructors such asnew_integer(),new_double_along() etc gain anames argument.In the case of the_along family it defaults to the namesof the input vector.

Bugfixes

• When nested quosures are evaluated witheval_tidy(),the.env pronoun now correctly refers to the currentquosure under evaluation (#174). Previously it would always refer to theenvironment of the outermost quosure.

• as_pairlist() (part of the experimental API) nowsupportsNULL and objects of type pairlist (#397).

• Fixed a performance bug inset_names() that caused afull copy of the vector names (@jimhester, #366).

API changes

The rlang API is maturing and still in flux. However we have made aneffort to better communicate what parts are stable. We will notintroduce breaking changes for stable functions unless the payoff forthe change is worth the trouble. See?rlang::lifecycle forthe lifecycle status of exported functions.

• The particle “lang” has been renamed to “call”:

  • lang() has been renamed tocall2().
  • new_language() has ben renamed tonew_call().
  • is_lang() has been renamed tois_call().We haven’t replaced theis_unary_lang() andis_binary_lang() because they are redundant with then argument ofis_call().
  • All call accessors such aslang_fn(),lang_name(),lang_args() etc aresoft-deprecated and renamed withcall_ prefix.

  In rlang 0.1 calls were called “language” objects in order to followthe R type nomenclature as returned bybase::typeof(). Wewanted to avoid adding to the confusion between S modes and R types.With hindsight we find it is better to use more meaningful typenames.

• We now use the term “data mask” instead of “overscope”. We thinkdata mask is a more natural name in the context of R. We say that thatobjects from user data mask objects in the current environment. Thismakes reference to object masking in the search path which is due to thesame mechanism (in technical terms, lexical scoping with hierarchicallynested environments).

  Following this new terminology, the new functionsas_data_mask() andnew_data_mask() replaceas_overscope() andnew_overscope().as_data_mask() has also a more consistent interface. Thesefunctions are only meant for developers of tidy evaluationinterfaces.

• We no longer require a data mask (previously called overscope) tobe cleaned up after evaluation.overscope_clean() is thussoft-deprecated without replacement.

Breaking changes

• !! now binds tightly in order to match intuitiveparsing of tidy eval code, e.g. !! x > y is nowequivalent to(!! x) > y. A corollary of this new syntaxis that you now have to be explicit when you want to unquote the wholeexpression on the right of!!. For instance you have toexplicitly write!! (x > y) to unquotex > y rather than justx.

• UQ(),UQS() and:= nowissue an error when called directly. The previous definitions causedsurprising results when the operators were invoked in wrong places(i.e. not in quasiquoted arguments).

• The prefix form`!!`() is now an alias to!! rather thanUQE(). This makes it more inline with regular R syntax where operators are parsed as regular calls,e.g. a + b is parsed as`+`(a, b) and bothforms are completely equivalent. Also the prefix form`!!!`() is now equivalent to!!!.

• UQE() is now deprecated in order to simplify thesyntax of quasiquotation. Please use!! get_expr(x)instead.

• expr_interp() now returns a formula instead of aquosure when supplied a formula.

• is_quosureish() andas_quosureish() aredeprecated. These functions assumed that quosures are formulas but thatis only an implementation detail.

• new_cnd() is nowcnd() for consistencywith other constructors. Also,cnd_error(),cnd_warning() andcnd_message() are nowerror_cnd(),warning_cnd() andmessage_cnd() to follow our naming scheme according towhich the type of output is a suffix rather than a prefix.

• is_node() now returnsTRUE for calls aswell andis_pairlist() does not returnTRUEforNULL objects. Useis_node_list() todetermine whether an object either of typepairlist orNULL. Note that all these functions are stillexperimental.

• set_names() no longer automatically splices lists ofcharacter vectors as we are moving away from automatic splicingsemantics.

Upcoming breaking changes

• Calling the functional forms of unquote operators with the rlangnamespace qualifier is soft-deprecated.UQ() andUQS() are not function calls so it does not make sense tonamespace them. Supporting namespace qualifiers complicates theimplementation of unquotation and is misleading as to the nature ofunquoting (which are syntactic operators at quotation-time rather thanfunction calls at evaluation-time).

• We are now questioningUQ() andUQS()as functional forms of!!. If!! and!!! were native R operators, they would parse to thefunctional calls`!!`() and`!!!`(). This isnow the preferred way to unquote with a function call rather than withthe operators. We haven’t decided yet whether we will deprecateUQ() andUQS() in the future. In any case werecommend using the new functional forms.

• parse_quosure() andparse_quosures()are soft-deprecated in favour ofparse_quo() andparse_quos(). These new names are consistent with the rulethat abbreviated suffixes indicate the return type of a function. Inaddition the new functions require their callers to explicitly supply anenvironment for the quosures.

• Usingf_rhs() andf_env() on quosuresis soft-deprecated. The fact that quosures are formulas is animplementation detail that might change in the future. Please usequo_get_expr() andquo_get_env()instead.

• quo_expr() is soft-deprecated in favour ofquo_squash().quo_expr() was a misnomerbecause it implied that it was a mere expression acccessor for quosureswhereas it was really a lossy operation that squashed all nestedquosures.

• With the renaming of thelang particle tocall, all these functions are soft-deprecated:lang(),is_lang(),lang_fn(),lang_name(),lang_args().

  In addition,lang_head() andlang_tail()are soft-deprecated without replacement because these are low levelaccessors that are rarely needed.

• as_overscope() is soft-deprecated in favour ofas_data_mask().

• The node setters were renamed frommut_node_ prefixtonode_poke_. This change follows a new naming conventionin rlang where mutation is referred to as “poking”.

• splice() is now in questioning stage as it is notneeded given the!!! operator works in functions takingdots withdots_list().

• lgl_len(),int_len() etc have beensoft-deprecated and renamed withnew_ prefix,e.g. new_logical() andnew_integer(). This isfor consistency with other non-variadic object constructors.

• ll() is now an alias tolist2(). Thisis consistent with the newcall2() constructor for calls.list2() andcall2() are versions oflist() andcall() that support splicing oflists with!!!.ll() remains around as ashorthand for users who like its conciseness.

• Automatic splicing of lists in vector constructors(e.g. lgl(),chr(), etc) is nowsoft-deprecated. Please be explicit with the splicing operator!!!.

rlang 0.1.6

• This is a maintenance release in anticipation of a forthcomingchange to R’s C API (useMARK_NOT_MUTABLE() instead ofSET_NAMED()).

• New functionis_reference() to check whether twoobjects are one and the same.

rlang 0.1.4

• eval_tidy() no longer maps over lists but returns themliterally. This behaviour is an overlook from past refactorings and wasnever documented.

rlang 0.1.2

This hotfix release makes rlang compatible with the R 3.1 branch.

rlang 0.1.1

This release includes two important fixes for tidy evaluation:

• Bare formulas are now evaluated in the correct environment intidyeval functions.

• enquo() now works properly within compiledfunctions. Before this release, constants optimised by the bytecodecompiler couldn’t be enquoted.

New functions:

• Thenew_environment() constructor creates a child ofthe empty environment and takes an optional named list of data topopulate it. Compared toenv() andchild_env(), it is meant to create environments as datastructures rather than as part of a scope hierarchy.

• Thenew_call() constructor creates calls out of acallable object (a function or an expression) and a pairlist ofarguments. It is useful to avoid costly internal coercions between listsand pairlists of arguments.

UI improvements:

• env_child()’s first argument is now.parent instead ofparent.

• mut_ setters likemut_attrs() andenvironment helpers likeenv_bind() andenv_unbind() now return their (modified) input invisibly.This follows the tidyverse convention that functions called primarilyfor their side effects should return their input invisibly.

• is_pairlist() now returnsTRUE forNULL. We addedis_node() to test for actualpairlist nodes. In other words,is_pairlist() tests for thedata structure whileis_node() tests for the type.

Bugfixes:

• env() andenv_child() can now getarguments whose names start with.. Prior to this fix,these arguments were partial-matching onenv_bind()’s.env argument.

• The internalreplace_na() symbol was renamed toavoid a collision with an exported function in tidyverse. This solves anissue occurring in old versions of R prior to 3.3.2 (#133).

rlang 0.1.0

Initial release.