NEWS

rlang 1.1.4.9000

rlang 1.1.4 (2024-06-04)

rlang 1.1.3 (2024-01-10)

rlang 1.1.2 (2023-11-04)

rlang 1.1.1 (2023-04-28)

rlang 1.1.0 (2023-03-14)

Life cycle changes

Main new features

Miscellaneous fixes and features

rlang 1.0.6 (2022-09-24)

rlang 1.0.5 (2022-08-31)

rlang 1.0.4 (2022-07-12)

rlang 1.0.3 (2022-06-27)

rlang 1.0.2 (2022-03-04)

rlang 1.0.1 (2022-02-03)

rlang 1.0.0 (2022-01-26)

Major changes

This release focuses on the rlang errors framework and features extensive changes to the display of error messages.

Breaking changes

Fixes and features

tidyeval

rlang errors

Backtraces

Argument intake

R APIs

rlang 0.4.12 (2021-10-18)

rlang 0.4.11 (2021-04-30)

rlang 0.4.10 (2020-12-30)

rlang 0.4.9 (2020-11-25)

Breaking changes

New features

Bugfixes and improvements

rlang 0.4.8 (2020-10-08)

rlang 0.4.7 (2020-07-09)

rlang 0.4.6 (2020-05-02)

rlang 0.4.5 (2020-03-01)

rlang 0.4.4 (2020-01-28)

rlang 0.4.3 (2020-01-24)

rlang 0.4.2 (2019-11-23)

rlang 0.4.1 (2019-10-24)

rlang 0.4.0 (2019-06-25)

Tidy evaluation

Interpolate function inputs with the curly-curly operator

The main change of this release is the new tidy evaluation operator {{. This operator abstracts the quote-and-unquote idiom into 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't stress enough that you can just pass dots straight to other tidy eval functions. There is no need for quote-and-unquote unless you need to modify 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 .env pronoun

Another improvement to tidy evaluation should make it easier to use the .env pronoun. Starting from this release, subsetting an object from the .env pronoun now evaluates the corresponding symbol. This makes .env more robust, in particular in magrittr pipelines. The following example would previously fail:

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

This way, using the .env pronoun is now equivalent to unquoting 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

Performance

Bugfixes and small improvements

Lifecycle

We commit to support 5 versions of R. As R 3.6 is about to be released, rlang now requires R 3.2 or greater. We're also continuing our efforts to streamline and narrow the rlang API.

rlang 0.3.2 (2019-03-21)

rlang 0.3.1 (2019-01-08)

This patch release polishes the new backtrace feature introduced in rlang 0.3.0 and solves bugs for the upcoming release of purrr 0.3.0. It also features as_label() and as_name() which are meant to replace quo_name() in the future. Finally, a bunch of deparsing issues have been fixed.

Backtrace fixes

as_label() and as_name()

The new as_label() and as_name() functions should be used instead of quo_name() to transform objects and quoted expressions to a string. We have noticed that tidy eval users often use quo_name() to extract names from quosured symbols. This is not a good use for that function because the way quo_name() creates a string is not a well defined operation.

For this reason, we are replacing quo_name() with two new functions that have more clearly defined purposes, and hopefully better names reflecting those purposes. Use as_label() to transform any object to a short human-readable description, and as_name() to extract names from (possibly quosured) symbols.

Create labels with as_label() to:

We expect as_label() to gain additional parameters in the future, for example to control the maximum width of a label. The way an object is labelled is thus subject to change.

On the other hand, as_name() transforms symbols back to a string in a well defined manner. Unlike as_label(), as_name() guarantees the roundtrip symbol -> string -> symbol.

In general, if you don't know for sure what kind of object you're dealing with (a call, a symbol, an unquoted constant), use as_label() and make no assumption about the resulting string. If you know you have a symbol and need the name of the object it refers to, use as_name(). For instance, use as_label() with objects captured with enquo() and as_name() with symbols captured with ensym().

Note that quo_name() will only be soft-deprecated at the next major version of rlang (0.4.0). At this point, it will start issuing once-per-session warnings in scripts, but not in packages. It will then be deprecated in yet another major version, at which point it will issue once-per-session warnings in packages as well. You thus have plenty of time to change your code.

Minor fixes and features

rlang 0.3.0 (2018-10-22)

Breaking changes

The rlang API is still maturing. In this section, you'll find hard breaking changes. See the life cycle section below for an exhaustive list of API changes.

Summary

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

Conditions and errors

Tidy dots

Tidy eval

Environments

Calls

Other improvements and fixes

Lifecycle

Soft-deprecated functions and arguments

rlang 0.3.0 introduces a new warning mechanism for soft-deprecated functions and arguments. A warning is issued, but only under one of these circumstances:

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

Deprecation warnings shouldn't make R CMD check fail for packages using testthat. However, expect_silent() can transform the warning to a hard failure.

tidyeval

Miscellaneous

Deprecated functions and arguments

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

Defunct functions and arguments

Defunct functions and arguments throw an error when used.

Functions and arguments in the questioning stage

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

rlang 0.2.2 (2018-08-16)

This is a maintenance release that fixes several garbage collection protection issues.

rlang 0.2.1 (2018-05-30)

This is a maintenance release that fixes several tidy evaluation issues.

rlang 0.2.0 (2018-02-20)

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

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

This release also polishes the rlang API. Many functions have been renamed as we get a better feel for the consistency and clarity of the API. Note that rlang as a whole is still maturing and some functions are even experimental. In order to make things clearer for users of rlang, we have started to develop a set of conventions to document the current stability of each function. You will now find "lifecycle" sections in documentation topics. In addition we have gathered all lifecycle information in the ?rlang::lifecycle help page. Please only use functions marked as stable in your projects unless you are prepared to deal with occasional backward incompatible updates.

Tidy evaluation

Conditions

Environments

Various features

Bugfixes

API changes

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

Breaking changes

Upcoming breaking changes

rlang 0.1.6 (2017-12-21)

rlang 0.1.4 (2017-11-05)

rlang 0.1.2 (2017-08-09)

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

rlang 0.1.1 (2017-05-18)

This release includes two important fixes for tidy evaluation:

New functions:

UI improvements:

Bugfixes:

rlang 0.1.0

Initial release.