Tidy evaluation nonstandard describes how R code inside tidyverse functions can bypass standard evaluation rules, enabling flexible quasiquotation and data mask behavior. This pattern lets you write concise, readable pipelines while still supporting dynamic inputs and hybrid functions.
Adopting tidy evaluation nonstandard techniques can improve DSL design, reporting workflows, and package APIs, but it requires awareness of scoping and evaluation contexts to avoid subtle bugs.
| Concept | Standard Evaluation | Nonstandard Evaluation | Tidy Evaluation Bridge |
|---|---|---|---|
| Definition | Arguments are always evaluated in the caller environment | Arguments may be captured as expressions and evaluated later | Embraces captured expressions and evaluates them in a controlled data mask |
| Use Case | Explicit, predictable behavior when inputs are constants | Metaprogramming, macros, and custom DSLs | Tidy functions like filter(), mutate(), and summarise() |
| Captures | Values, not expressions | Expressions (quosures) with environment | Quosures paired with data mask for tidy evaluation |
| Typical Syntax | f(x, y) | macro(expr, ...) | enquo(), !!, across(), {{ }}, sym(), parse_expr() |
| Evaluation Context | Caller environment or function frame | Captured environment or injected frame | Data mask plus caller environment for tidy evaluation nonstandard evaluation |
Capturing Expressions with Enquo and Embrace
In many tidyverse tools, tidy evaluation nonstandard evaluation starts with capturing user input. enquo() captures an unevaluated argument as a quosure, preserving its environment for later evaluation within the function frame.
When designing internal helpers, you typically enquo the main input, store it, and later splice or unquote with !! to control when and where the expression is evaluated.
Data Mask and Hybrid Evaluation
dplyr and tidyr use a data mask environment where column names are treated as symbols. Hybrid evaluation combines lazy evaluation of expressions with immediate scalar operations to optimize performance while preserving tidy evaluation nonstandard evaluation semantics.
Programming with Quosures and UQ
Quosures are the building blocks for tidy evaluation nonstandard evaluation. Each quosure carries both an expression and the environment where it was created, enabling safe scoping when you unquote parts of the expression into new contexts.
UQ (historically used as !!! unquote-splicing for lists and !! for single quosures) allows you to inject computed expressions while preserving correct evaluation context inside dplyr verbs.
Custom DSLs and Programmed Workflows
Package authors use tidy evaluation nonstandard evaluation to design domain-specific languages that feel native to R. By combining tidyselect helpers, tidyeval helpers, and consistent quasiquotation patterns, you expose intuitive APIs that hide complex metaprogramming details from end users.
Best Practices and Takeaways
- Capture user inputs with enquo() or the {{ }} embrace when designing functions that wrap tidyverse verbs.
- Use unquote (!!) and unquote-splicing (!!! ) to inject computed expressions at the right evaluation stage.
- Prefer curly-curly {{ }} in most tidy wrapper functions for concise handling of single arguments.
- Test your functions with both column names and strings, and ensure masking rules align with expected behavior.
- Document evaluation semantics clearly so users know which environments are searched for symbols.
FAQ
Reader questions
How do I capture a user-supplied column name and use it across multiple dplyr verbs?
Use enquo() to capture the column argument, then unquote it with !! inside across(), mutate(), or filter() so that the same expression is consistently evaluated in the data mask.
What is the difference between UQ and curly-curly when writing functions?
Curly-curly {{ }} is a shorthand that automatically captures the argument with enquo(), injects it into the data mask, and unquotes it in a standard evaluation context. UQ or !! gives you explicit control over where and how the captured quosure is spliced.
Why does my function fail with variable names that are also objects in the global environment?
Tidy evaluation nonstandard evaluation resolves symbols first in the data mask (column names), then in the caller environment. Ensure you quote user input, avoid accidental masking by global objects, and use sym() or as_name() deliberately when converting between strings and symbols.
Can tidy evaluation nonstandard evaluation be used with base R and non-tidy packages?
Yes, you can use tidyeval helpers like enquo(), quo_name(), and sym() in any R function to capture and manipulate expressions, then evaluate them in chosen environments with eval_tidy().