From 4004384ea509467742c0c4f35cd469fee0458714 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kirill=20M=C3=BCller?= <krlmlr+r@mailbox.org>
Date: Sun, 26 Sep 2021 21:28:11 +0200
Subject: [PATCH] Document use of objects in the calling environment, closes
 #949

---
 R/tibble.R    | 13 +++++++++++--
 man/lst.Rd    |  5 +++--
 man/tibble.Rd | 13 +++++++++++--
 3 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/R/tibble.R b/R/tibble.R
index d122f7129..8e9212180 100644
--- a/R/tibble.R
+++ b/R/tibble.R
@@ -31,8 +31,9 @@
 #'   Arguments are evaluated sequentially.
 #'   You can refer to previously created elements directly or using the [.data]
 #'   pronoun.
-#'   An existing `.data` pronoun, provided e.g. inside [dplyr::mutate()],
-#'   is not available.
+#'   To refer explicitly to objects in the calling environment, use [`!!`] or
+#'   [.env], e.g. `!!.data` or `.env$.data` for the special case of an object
+#'   named `.data`.
 #' @param .rows The number of rows, useful to create a 0-column tibble or
 #'   just as an additional check.
 #' @param .name_repair Treatment of problematic column names:
@@ -143,6 +144,14 @@
 #' # You can splice-unquote a list of quosures and expressions:
 #' tibble(!!! list(x = rlang::quo(1:10), y = quote(x * 2)))
 #'
+#' # Use .data, .env and !! to refer explicitly to columns or outside objects
+#' a <- 1
+#' tibble(a = 2, b = a)
+#' tibble(a = 2, b = .data$a)
+#' tibble(a = 2, b = .env$a)
+#' tibble(a = 2, b = !!a)
+#' try(tibble(a = 2, b = .env$bogus))
+#' try(tibble(a = 2, b = !!bogus))
 tibble <- function(...,
                    .rows = NULL,
                    .name_repair = c("check_unique", "unique", "universal", "minimal")) {
diff --git a/man/lst.Rd b/man/lst.Rd
index ba720cae1..bdfe672e8 100644
--- a/man/lst.Rd
+++ b/man/lst.Rd
@@ -15,8 +15,9 @@ unquote-splice via \code{\link{!!!}}. Use \verb{:=} to create columns that start
 Arguments are evaluated sequentially.
 You can refer to previously created elements directly or using the \link{.data}
 pronoun.
-An existing \code{.data} pronoun, provided e.g. inside \code{\link[dplyr:mutate]{dplyr::mutate()}},
-is not available.}
+To refer explicitly to objects in the calling environment, use \code{\link{!!}} or
+\link{.env}, e.g. \code{!!.data} or \code{.env$.data} for the special case of an object
+named \code{.data}.}
 }
 \value{
 A named list.
diff --git a/man/tibble.Rd b/man/tibble.Rd
index ed2fba682..967cd4f4c 100644
--- a/man/tibble.Rd
+++ b/man/tibble.Rd
@@ -25,8 +25,9 @@ unquote-splice via \code{\link{!!!}}. Use \verb{:=} to create columns that start
 Arguments are evaluated sequentially.
 You can refer to previously created elements directly or using the \link{.data}
 pronoun.
-An existing \code{.data} pronoun, provided e.g. inside \code{\link[dplyr:mutate]{dplyr::mutate()}},
-is not available.}
+To refer explicitly to objects in the calling environment, use \code{\link{!!}} or
+\link{.env}, e.g. \code{!!.data} or \code{.env$.data} for the special case of an object
+named \code{.data}.}
 
 \item{.rows}{The number of rows, useful to create a 0-column tibble or
 just as an additional check.}
@@ -164,6 +165,14 @@ tibble(x = 1, y = !!x)
 # You can splice-unquote a list of quosures and expressions:
 tibble(!!! list(x = rlang::quo(1:10), y = quote(x * 2)))
 
+# Use .data, .env and !! to refer explicitly to columns or outside objects
+a <- 1
+tibble(a = 2, b = a)
+tibble(a = 2, b = .data$a)
+tibble(a = 2, b = .env$a)
+tibble(a = 2, b = !!a)
+try(tibble(a = 2, b = .env$bogus))
+try(tibble(a = 2, b = !!bogus))
 
 # Use tibble_row() to construct a one-row tibble:
 tibble_row(a = 1, lm = lm(Height ~ Girth + Volume, data = trees))