210 depracate datanames in teal.data::get_code (#343)

Part of 
- insightsengineering/teal.code#210

Companion to
- insightsengineering/teal#1388
- insightsengineering/teal.code#214

# Description

Deprecates the usage of `datanames` parameter in
`teal.data::get_code(datanames)` in favour of
`teal.code::get_code(names)`.

VBUMP package version locally to something greater than `0.6.1` during
testing.

``` r
library(teal.data)
#> Loading required package: teal.code
tdata1 <- within(teal_data(), {a <- 1; b <- 2})
get_code(tdata1)
#> [1] "a <- 1\nb <- 2"
get_code(tdata1, datanames = "a")
#> Warning: The `datanames` argument of `get_code()` is deprecated as of teal.data 0.6.1.
#> ℹ Please use the `names` argument of `teal.code::get_code()` instead.
#> ℹ The deprecated feature was likely used in the teal.data package.
#>   Please report the issue at
#>   <https://github.com/insightsengineering/teal.data/issues>.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.
#> [1] "a <- 1"
```

<sup>Created on 2024-10-17 with [reprex
v2.1.1](https://reprex.tidyverse.org)</sup>

---------

Signed-off-by: Marcin <[email protected]>
Co-authored-by: 27856297+dependabot-preview[bot]@users.noreply.github.com <27856297+dependabot-preview[bot]@users.noreply.github.com>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pawel Rucki <[email protected]>

DESCRIPTION

@@ -78,6 +78,5 @@ Collate:
     'teal_data.R'
     'testhat-helpers.R'
     'topological_sort.R'
-    'utils-get_code_dependency.R'
     'verify.R'
     'zzz.R'

NEWS.md

@@ -1,5 +1,9 @@
 # teal.data 0.6.0.9013
 
+### Breaking changes
+
+- soft deprecate `datanames` argument of `get_code()`. Use `names` instead.
+
 ### Enhancements
 
 - `datanames()`

R/teal_data-get_code.R

@@ -3,10 +3,10 @@
 #' Retrieve code from `teal_data` object.
 #'
 #' Retrieve code stored in `@code`, which (in principle) can be used to recreate all objects found in `@env`.
-#' Use `datanames` to limit the code to one or more of the datasets enumerated in `@datanames`.
+#' Use `names` to limit the code to one or more of the datasets enumerated in `@datanames`.
 #'
 #' @section Extracting dataset-specific code:
-#' When `datanames` is specified, the code returned will be limited  to the lines needed to _create_
+#' When `names` is specified, the code returned will be limited  to the lines needed to _create_
 #' the requested datasets. The code stored in the `@code` slot is analyzed statically to determine
 #' which lines the datasets of interest depend upon. The analysis works well when objects are created
 #' with standard infix assignment operators (see `?assignOps`) but it can fail in some situations.
@@ -23,10 +23,10 @@
 #'     x <- 0
 #'     y <- foo(x)
 #'   })
-#' get_code(data, datanames = "y")
+#' get_code(data, names = "y")
 #' ```
-#' `x` has no dependencies, so `get_code(data, datanames = "x")` will return only the second call.\cr
-#' `y` depends on `x` and `foo`, so `get_code(data, datanames = "y")` will contain all three calls.
+#' `x` has no dependencies, so `get_code(data, names = "x")` will return only the second call.\cr
+#' `y` depends on `x` and `foo`, so `get_code(data, names = "y")` will contain all three calls.
 #'
 #' _Case 2: Some objects are created by a function's side effects._
 #' ```r
@@ -39,10 +39,10 @@
 #'     foo()
 #'     y <- x
 #'   })
-#' get_code(data, datanames = "y")
+#' get_code(data, names = "y")
 #' ```
 #' Here, `y` depends on `x` but `x` is modified by `foo` as a side effect (not by reassignment)
-#' and so `get_code(data, datanames = "y")` will not return the `foo()` call.\cr
+#' and so `get_code(data, names = "y")` will not return the `foo()` call.\cr
 #' To overcome this limitation, code dependencies can be specified manually.
 #' Lines where side effects occur can be flagged by adding "`# @linksto <object name>`" at the end.\cr
 #' Note that `within` evaluates code passed to `expr` as is and comments are ignored.
@@ -58,7 +58,7 @@
 #'     foo() # @linksto x
 #'     y <- x
 #'   ")
-#' get_code(data, datanames = "y")
+#' get_code(data, names = "y")
 #' ```
 #' Now the `foo()` call will be properly included in the code required to recreate `y`.
 #'
@@ -72,7 +72,9 @@
 #'
 #'
 #' @param object (`teal_data`)
-#' @param datanames `r lifecycle::badge("experimental")` (`character`) vector of dataset names to return the code for.
+#' @param datanames `r lifecycle::badge("deprecated")` (`character`) vector of dataset names to return the code for.
+#' For more details see the "Extracting dataset-specific code" section. Use `names` instead.
+#' @param names (`character`) Successor of `datanames`. Vector of dataset names to return the code for.
 #' For more details see the "Extracting dataset-specific code" section.
 #' @param deparse (`logical`) flag specifying whether to return code as `character` (`deparse = TRUE`) or as
 #' `expression` (`deparse = FALSE`).
@@ -81,7 +83,7 @@
 #' `code` but are passed in `datanames`. To remove the warning, set `check_names = FALSE`.
 #'
 #' @return
-#' Either a character string or an expression. If `datanames` is used to request a specific dataset,
+#' Either a character string or an expression. If `names` is used to request a specific dataset,
 #' only code that _creates_ that dataset (not code that uses it) is returned. Otherwise, all contents of `@code`.
 #'
 #' @examples
@@ -92,8 +94,8 @@
 #'   c <- list(x = 2)
 #' })
 #' get_code(tdata1)
-#' get_code(tdata1, datanames = "a")
-#' get_code(tdata1, datanames = "b")
+#' get_code(tdata1, names = "a")
+#' get_code(tdata1, names = "b")
 #'
 #' tdata2 <- teal_data(x1 = iris, code = "x1 <- iris")
 #' get_code(tdata2)
@@ -103,28 +105,26 @@
 #' @aliases get_code,teal_data-method
 #'
 #' @export
-setMethod("get_code", signature = "teal_data", definition = function(object, deparse = TRUE, datanames = NULL, ...) {
-  checkmate::assert_character(datanames, min.len = 1L, null.ok = TRUE)
-  checkmate::assert_flag(deparse)
+setMethod("get_code",
+  signature = "teal_data",
+  definition = function(object, deparse = TRUE, names = NULL, datanames = lifecycle::deprecated(), ...) {
+    if (lifecycle::is_present(datanames)) {
+      lifecycle::deprecate_warn(
+        when = "0.6.1",
+        what = "teal.data::get_code(datanames)",
+        with = "teal.code::get_code(names)",
+        always = TRUE
+      )
+      names <- datanames
+    }
 
-  # Normalize in case special it is backticked
-  if (!is.null(datanames)) {
-    datanames <- gsub("^`(.*)`$", "\\1", datanames)
-  }
+    if (!is.null(names) && lifecycle::is_present(datanames)) {
+      stop("Please use either 'names' (recommended) or 'datanames' parameter.")
+    }
 
-  code <- if (!is.null(datanames)) {
-    get_code_dependency(object@code, datanames, ...)
-  } else {
-    object@code
-  }
+    checkmate::assert_character(names, min.len = 1L, null.ok = TRUE)
+    checkmate::assert_flag(deparse)
 
-  if (deparse) {
-    if (length(code) == 0) {
-      code
-    } else {
-      paste(code, collapse = "\n")
-    }
-  } else {
-    parse(text = paste(c("{", code, "}"), collapse = "\n"), keep.source = TRUE)
+    methods::callNextMethod(object = object, deparse = deparse, names = names, ...)
   }
-})
+)