Metaprogramming rlang

This skill covers modern rlang patterns for data-masking, tidy evaluation, and building programmatic tidyverse functions.

Core Concepts

Data-masking allows R expressions to refer to data frame columns as if they were variables in the environment. rlang provides the metaprogramming framework that powers tidyverse data-masking.

Key rlang Tools

Embracing {{}} - Forward function arguments to data-masking functions
Injection !! - Inject single expressions or values
Splicing !!! - Inject multiple arguments from a list
Dynamic dots - Programmable ... with injection support
Pronouns .data/.env - Explicit disambiguation between data and environment variables

When to Use Each Operator

Operator	Use Case	Example
`{{ }}`	Forward function arguments	`summarise(mean = mean({{ var }}))`
`!!`	Inject single expression/value	`summarise(mean = mean(!!sym(var)))`
`!!!`	Inject multiple arguments	`group_by(!!!syms(vars))`
`.data[[]]`	Access columns by name	`mean(.data[[var]])`

Function Argument Patterns

Forwarding with `{{}}`

Use {{}} to forward function arguments to data-masking functions. See embrace-examples.md.

Forwarding `...`

No special syntax needed for dots forwarding. See dots-forwarding.md.

Names Patterns with `.data`

Use .data pronoun for programmatic column access. See data-pronoun-examples.md.

Injection Operators

Advanced Injection with `!!`

Create symbols from strings, inject values to avoid name collisions. See injection-examples.md.

Splicing with `!!!`

Inject multiple symbols from character vectors, splice lists of arguments. See splicing-examples.md.

Dynamic Dots Patterns

Using `list2()` for Dynamic Dots Support

Enables splicing, name injection, and trailing commas. See dynamic-dots-examples.md.

Name Injection with Glue Syntax

Use glue syntax for dynamic column naming. See name-injection-examples.md.

Pronouns for Disambiguation

`.data` and `.env` Best Practices

Explicit disambiguation prevents masking issues. See pronouns-examples.md.

Programming Patterns

Bridge Patterns

Converting between data-masking and tidy selection behaviors:

across() as selection-to-data-mask bridge
across(all_of()) as names-to-data-mask bridge

See bridge-patterns.md.

Transformation Patterns

Transform single arguments by wrapping, transform dots with across(). See transformation-patterns.md.

Error-Prone Patterns to Avoid

Deprecated/Dangerous Patterns

String parsing with eval(parse(text = ...)) - Security risk
get() in data mask - Name collision prone

See avoid-patterns.md.

Common Mistakes

Don't use {{ }} on non-arguments
Don't mix injection styles unnecessarily

Package Development with rlang

Import Strategy

# In DESCRIPTION:
Imports: rlang

# In NAMESPACE, import specific functions:
importFrom(rlang, enquo, enquos, expr, !!!, :=)

Documentation Tags

#' @param var <[`data-masked`][dplyr::dplyr_data_masking]> Column to summarize
#' @param ... <[`dynamic-dots`][rlang::dyn-dots]> Additional grouping variables
#' @param cols <[`tidy-select`][dplyr::dplyr_tidy_select]> Columns to select

Testing rlang Functions

See testing-examples.md for testing data-masking and injection behavior.

source: Sarah Johnson's gist https://gist.github.com/sj-io/3828d64d0969f2a0f05297e59e6c15ad

metaprogramming-rlang