enh: deprecate_param()

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: GiottoUtils
 Title: Giotto Suite Utilities
-Version: 0.1.8
+Version: 0.1.9
 Authors@R: c(
 	person("Ruben", "Dries", email = "rubendries@gmail.com",
 		 role = c("aut", "cre"), comment = c(ORCID = "0000-0001-7650-7754")),

NAMESPACE

@@ -19,6 +19,7 @@ export(color_tag)
 export(color_teal)
 export(color_yellow)
 export(degrees)
+export(deprecate_param)
 export(deprecate_soft)
 export(deprecate_stop)
 export(deprecate_warn)

NEWS.md

@@ -1,4 +1,9 @@
 
+# GiottoUtils 0.1.9
+
+## New
+- `deprecate_param()` utility function for streamlining code
+
 # GiottoUtils 0.1.8 (2024/05/22)
 
 ## New

R/lifecycle.R

@@ -47,3 +47,80 @@ lifecycle::deprecate_stop
 lifecycle_badge <- function(stage = "stable") {
     lifecycle::badge(stage)
 }
+
+
+#' @name deprecate_param
+#' @title Deprecate a parameter
+#' @description
+#' Accepts the directly passed deprecated and superceding params and
+#' Sends a deprecation message if the deprecated param was used.
+#' This function wraps `lifecycle::deprecate_warn()` to make a
+#' standard param deprecation message. It then outputs the final value
+#' to be used.
+#' @param x name. Deprecated param
+#' @param y name. Superceding param
+#' @param fun character. Name of function
+#' @param when character. Version number in which the deprecation happened.
+#' @param check character. Method to check if deprecated param was used
+#' @returns final value to be used
+#' @examples
+#' foo <- function(dep = deprecated(), sup = 10) {
+#'     sup <- deprecate_param(
+#'         dep, sup, fun = "foo", when = "0.0.1"
+#'     )
+#'     return(sup)
+#' }
+#'
+#' foo() # following defaults, no deprecation message
+#' foo(sup = 3) # no deprecation message triggered
+#' foo(dep = 3) # deprecation message triggered
+#'
+#' # convenient nested function when deprecating multiple params
+#' bar <- function(dep1 = deprecated(),
+#'                 dep2 = deprecated(),
+#'                 sup1 = 10,
+#'                 sup2 = 20) {
+#'
+#'     # internally defined function that streamlines downstream deprecations
+#'     .dep <- function(...) {
+#'         deprecate_param(..., fun = "bar", when = "0.0.2")
+#'     }
+#'
+#'     sup1 <- .dep(dep1, sup1)
+#'     sup2 <- .dep(dep2, sup2)
+#'
+#'     return(list(sup1, sup2))
+#' }
+#'
+#' bar(sup1 = 100)
+#' bar(dep1 = 100, dep2 = "hello")
+#'
+#' @export
+deprecate_param <- function(
+        x, y, fun, when, check = c("deprecated", "null")
+) {
+    # checkmate::assert_character(from)
+    check <- match.arg(check, choices = c("deprecated", "null"))
+    xchar <- as.character(substitute(x))
+
+    used <- switch(check,
+        "null" = !is.null(x),
+        "deprecated" = is_present(x)
+    )
+
+    if (!used) return(y)
+
+    ychar <- as.character(substitute(y))
+    deprecate_warn(
+        when = when,
+        what = sprintf("%s(%s)", fun, xchar),
+        with = sprintf("%s(%s)", fun, ychar),
+        env = parent.frame(2),
+        user_env = parent.frame(3),
+        always = TRUE
+    )
+    return(x)
+}
+
+
+