1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
#' Tidy eval helpers
#'
#' @description
#' This page lists the tidy eval tools reexported in this package from
#' rlang. To learn about using tidy eval in scripts and packages at a
#' high level, see the [dplyr programming
#' vignette](https://dplyr.tidyverse.org/articles/programming.html)
#' and the [ggplot2 in packages
#' vignette](https://ggplot2.tidyverse.org/articles/ggplot2-in-packages.html).
#' The [Metaprogramming
#' section](https://adv-r.hadley.nz/metaprogramming.html) of [Advanced
#' R](https://adv-r.hadley.nz) may also be useful for a deeper dive.
#'
#' * The tidy eval operators `{{`, `!!`, and `!!!` are syntactic
#' constructs which are specially interpreted by tidy eval functions.
#' You will mostly need `{{`, as `!!` and `!!!` are more advanced
#' operators which you should not have to use in simple cases.
#'
#' The curly-curly operator `{{` allows you to tunnel data-variables
#' passed from function arguments inside other tidy eval functions.
#' `{{` is designed for individual arguments. To pass multiple
#' arguments contained in dots, use `...` in the normal way.
#'
#' ```
#' my_function <- function(data, var, ...) {
#' data %>%
#' group_by(...) %>%
#' summarise(mean = mean({{ var }}))
#' }
#' ```
#'
#' * [enquo()] and [enquos()] delay the execution of one or several
#' function arguments. The former returns a single expression, the
#' latter returns a list of expressions. Once defused, expressions
#' will no longer evaluate on their own. They must be injected back
#' into an evaluation context with `!!` (for a single expression) and
#' `!!!` (for a list of expressions).
#'
#' ```
#' my_function <- function(data, var, ...) {
#' # Defuse
#' var <- enquo(var)
#' dots <- enquos(...)
#'
#' # Inject
#' data %>%
#' group_by(!!!dots) %>%
#' summarise(mean = mean(!!var))
#' }
#' ```
#'
#' In this simple case, the code is equivalent to the usage of `{{`
#' and `...` above. Defusing with `enquo()` or `enquos()` is only
#' needed in more complex cases, for instance if you need to inspect
#' or modify the expressions in some way.
#'
#' * The `.data` pronoun is an object that represents the current
#' slice of data. If you have a variable name in a string, use the
#' `.data` pronoun to subset that variable with `[[`.
#'
#' ```
#' my_var <- "disp"
#' mtcars %>% summarise(mean = mean(.data[[my_var]]))
#' ```
#'
#' * Another tidy eval operator is `:=`. It makes it possible to use
#' glue and curly-curly syntax on the LHS of `=`. For technical
#' reasons, the R language doesn't support complex expressions on
#' the left of `=`, so we use `:=` as a workaround.
#'
#' ```
#' my_function <- function(data, var, suffix = "foo") {
#' # Use `{{` to tunnel function arguments and the usual glue
#' # operator `{` to interpolate plain strings.
#' data %>%
#' summarise("{{ var }}_mean_{suffix}" := mean({{ var }}))
#' }
#' ```
#'
#' * Many tidy eval functions like `dplyr::mutate()` or
#' `dplyr::summarise()` give an automatic name to unnamed inputs. If
#' you need to create the same sort of automatic names by yourself,
#' use `as_label()`. For instance, the glue-tunnelling syntax above
#' can be reproduced manually with:
#'
#' ```
#' my_function <- function(data, var, suffix = "foo") {
#' var <- enquo(var)
#' prefix <- as_label(var)
#' data %>%
#' summarise("{prefix}_mean_{suffix}" := mean(!!var))
#' }
#' ```
#'
#' Expressions defused with `enquo()` (or tunnelled with `{{`) need
#' not be simple column names, they can be arbitrarily complex.
#' `as_label()` handles those cases gracefully. If your code assumes
#' a simple column name, use `as_name()` instead. This is safer
#' because it throws an error if the input is not a name as expected.
#'
#' @md
#' @name tidyeval
#' @keywords internal
#' @aliases expr enquo enquos sym syms .data as_label
#' @export expr enquo enquos sym syms .data as_label
NULL
# For backward-compatibility, keep exporting the old ones
#' @name tidyeval
#' @keywords internal
#' @aliases quo_name quo quos enexpr enexprs ensym ensyms
#' @export quo_name quo quos enexpr enexprs ensym ensyms
NULL
|
