mdsumner/sc
Common Forms for Complex Hierarchical and Relational Data Structures

Package index
Search the mdsumner/sc package
Vignettes
Functions
382
Source code
106
Man pages
31
Home
/
GitHub
/
mdsumner/sc
/
revdep/library/silicate/new/rlang/NEWS.md

revdep/library/silicate/new/rlang/NEWS.md
In mdsumner/sc: Common Forms for Complex Hierarchical and Relational Data Structures

rlang 0.4.6

rlang 0.4.5

rlang 0.4.4

rlang 0.4.3

A single pair of braces triggers normal glue interpolation:

```r df <- data.frame(x = 1:3)

suffix <- "foo" df %>% dplyr::mutate("var_{suffix}" := x * 2) #> x var_foo #> 1 1 2 #> 2 2 4 #> 3 3 6 ```

Using a pair of double braces is for labelling a function argument. Technically, this is shortcut for "{as_label(enquo(arg))}". The syntax is similar to the curly-curly syntax for interpolating function arguments:

```r my_wrapper <- function(data, var, suffix = "foo") { data %>% dplyr::mutate("{{ var }}_{suffix}" := {{ var }} * 2) } df %>% my_wrapper(x) #> x x_foo #> 1 1 2 #> 2 2 4 #> 3 3 6

df %>% my_wrapper(sqrt(x)) #> x sqrt(x)_foo #> 1 1 2.000000 #> 2 2 2.828427 #> 3 3 3.464102 ```

rlang 0.4.2

Concretely, this is a way of breaking up lazy generation of error messages with conditionMessage() into three independent parts. This provides a lot of flexibility for hierarchies of error classes, for instance you could inherit the body of an error message from a parent class while overriding the header and footer.

rlang 0.4.1

rlang 0.4.0

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

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

letters %>% set_names(toupper) ```

Performance

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

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

rlang 0.3.1

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

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

This handler also works as a calling handler:

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

However it's often more practical to use with_abort() in that case:

r with_abort(foo(bar))

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

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.

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

This caused a number of issues in reverse dependencies as quo_text() tends to be used for converting symbols to strings. quo_text() and quo_name() should not be used for this purpose because they are general purpose deparsers. These functions should generally only be used for printing outputs or creating default labels. If you need to convert symbols to strings, please use as_string() rather than quo_text().

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

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

Summary

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

abort() also gains a parent argument. This is meant for situations where you're calling a low level API (to download a file, parse a JSON file, etc) and would like to intercept errors with base::tryCatch() or rlang::with_handlers() and rethrow them with a high-level message. Call abort() with the intercepted error as the parent argument. When the user prints rlang::last_error(), the backtrace will be shown in two sections corresponding to the high-level and low-level contexts.

In order to get segmented backtraces, the low-level error has to be thrown with abort(). When that's not the case, you can call the low-level function within with_abort() to automatically promote all errors to rlang errors.

Conditions and errors

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

Tidy dots

!!! disallows:

Quoting functions used to automatically wrap language objects in lists to make them spliceable. This behaviour is now soft-deprecated and it is no longer valid to write !!!enquo(x). Please unquote scalar objects with !! instead.

Tidy eval

Environments

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

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

This change concerns env_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() and env_bind_fns().

Deprecated functions and arguments

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

``` # Bad rlang::expr(mean(rlang::UQ(var) * 100))

# Ok rlang::expr(mean(UQ(var) * 100))

# Good rlang::expr(mean(!!var * 100)) ```

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

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

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

rlang 0.2.1

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

rlang 0.2.0

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

Technically the !! operator has the same precedence as unary - 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 equivalent to!!(a^b) and !!(a$b).

In addition, enexprs() is like enquos() but like exprs() it returns bare expressions. And ensyms() expects strings or symbols.

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

Technically, this is because enquo() now also captures arguments in parents of the current environment rather than just in the current environment. The flip side of this increased flexibility is that if you made a typo in the name of the variable you want to capture, and if an object of that name exists anywhere in the parent contexts, you will capture that object rather than getting an error.

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

This is consistent with the way native R operators parses to function calls. These new functional forms are to be preferred to UQ() and UQS(). We are now questioning the latter and might deprecate them in a future release.

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.

In rlang 0.1 calls were called "language" objects in order to follow the R type nomenclature as returned by base::typeof(). We wanted to avoid adding to the confusion between S modes and R types. With hindsight we find it is better to use more meaningful type names.

Following this new terminology, the new functions as_data_mask() and new_data_mask() replace as_overscope() and new_overscope(). as_data_mask() has also a more consistent interface. These functions are only meant for developers of tidy evaluation interfaces.

Breaking changes

Upcoming breaking changes

In addition, lang_head() and lang_tail() are soft-deprecated without replacement because these are low level accessors that are rarely needed.

rlang 0.1.6

rlang 0.1.4

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:

New functions:

UI improvements:

Bugfixes:

rlang 0.1.0

Initial release.



mdsumner/sc documentation built on Jan. 16, 2024, 2:03 a.m.

R Package Documentation

rdrr.io home R language documentation Run R code online

Browse R Packages

CRAN packages Bioconductor packages R-Forge packages GitHub packages

We want your feedback!

Note that we can't provide technical support on individual packages. You should contact the package authors for that.
GitHub issue tracker
ian@mutexlabs.com
Personal blog

 
Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.

Close