fix: change col_vals_regex() arg name to align with Python Pointblank

NEWS.md

@@ -1,5 +1,7 @@
 # pointblank (development version)
 
+- The `regex` argument of `col_vals_regex()` (and its `expect_*`/`test_*` variants) is renamed to `pattern` to align with Python pointblank. The old `regex` argument remains accepted but emits a soft-deprecation warning. YAML files using a `regex:` key are still read correctly; newly written YAML uses `pattern:`. (#685)
+
 - `col_vals_gte()` and `col_vals_lte()` are renamed to `col_vals_ge()` and `col_vals_le()` to align with Python pointblank naming. The old names remain as soft-deprecated aliases and will continue to work for the foreseeable future. Existing YAML files using `col_vals_gte`/`col_vals_lte` step keys are still accepted. (#684)
 
 - The `stop` and `notify` threshold levels in `action_levels()` are renamed to `error` and `critical` (aligning with Python pointblank), with deprecation warnings for old names; `action_fns()` is now exported. (#611)

R/all_passed.R

@@ -78,7 +78,7 @@
 #' agent <-
 #'   create_agent(tbl = tbl) |>
 #'   col_vals_gt(columns = a, value = 3) |>
-#'   col_vals_lte(columns = a, value = 10) |>
+#'   col_vals_le(columns = a, value = 10) |>
 #'   col_vals_increasing(columns = a) |>
 #'   interrogate()
 #' ```

R/col_vals_between.R

@@ -33,7 +33,7 @@
 #' and `right`, states whether each bound is inclusive or not. The default is
 #' `c(TRUE, TRUE)`, where both endpoints are inclusive (i.e., `[left, right]`).
 #' For partially-unbounded versions of this function, we can use the
-#' [col_vals_lt()], [col_vals_lte()], [col_vals_gt()], or [col_vals_gte()]
+#' [col_vals_lt()], [col_vals_le()], [col_vals_gt()], or [col_vals_ge()]
 #' validation functions. The validation function can be used directly on a data
 #' table or with an *agent* object (technically, a `ptblank_agent` object)
 #' whereas the expectation and test functions can only be used with a data

R/col_vals_not_between.R

@@ -34,7 +34,7 @@
 #' states whether each bound is inclusive or not. The default is `c(TRUE,
 #' TRUE)`, where both endpoints are inclusive (i.e., `[left, right]`). For
 #' partially-unbounded versions of this function, we can use the
-#' [col_vals_lt()], [col_vals_lte()], [col_vals_gt()], or [col_vals_gte()]
+#' [col_vals_lt()], [col_vals_le()], [col_vals_gt()], or [col_vals_ge()]
 #' validation functions. The validation function can be used directly on a data
 #' table or with an *agent* object (technically, a `ptblank_agent` object)
 #' whereas the expectation and test functions can only be used with a data

R/col_vals_regex.R

@@ -25,23 +25,30 @@
 #'
 #' The `col_vals_regex()` validation function, the `expect_col_vals_regex()`
 #' expectation function, and the `test_col_vals_regex()` test function all check
-#' whether column values in a table correspond to a `regex` matching expression.
-#' The validation function can be used directly on a data table or with an
-#' *agent* object (technically, a `ptblank_agent` object) whereas the
+#' whether column values in a table correspond to a `pattern` matching
+#' expression. The validation function can be used directly on a data table or
+#' with an *agent* object (technically, a `ptblank_agent` object) whereas the
 #' expectation and test functions can only be used with a data table. Each
 #' validation step or expectation will operate over the number of test units
 #' that is equal to the number of rows in the table (after any `preconditions`
 #' have been applied).
 #'
 #' @inheritParams col_vals_gt
 #'
-#' @param regex *Regex pattern*
+#' @param pattern *Regex pattern*
 #'
 #'   `scalar<character>` // **required**
 #'
 #'   A regular expression pattern to test for a match to the target column. Any
 #'   regex matches to values in the target `columns` will pass validation.
 #'
+#' @param regex `r lifecycle::badge("deprecated")`
+#'
+#'   `scalar<character>` // **deprecated**
+#'
+#'   Deprecated in favor of `pattern`. Providing a value here will work but
+#'   will emit a warning asking you to switch to `pattern`.
+#'
 #' @return For the validation function, the return value is either a
 #'   `ptblank_agent` object or a table object (depending on whether an agent
 #'   object or a table was passed to `x`). The expectation function invisibly
@@ -187,11 +194,11 @@
 #'
 #' R statement:
 #'
-#' ```
+#' ```r
 #' agent |>
 #'   col_vals_regex(
 #'     columns = a,
-#'     regex = "[0-9]-[a-z]{3}-[0-9]{3}",
+#'     pattern = "[0-9]-[a-z]{3}-[0-9]{3}",
 #'     na_pass = TRUE,
 #'     preconditions = \(x) x |> dplyr::filter(a < 10),
 #'     segments = b ~ c("group_1", "group_2"),
@@ -207,7 +214,7 @@
 #' steps:
 #' - col_vals_regex:
 #'     columns: c(a)
-#'     regex: '[0-9]-[a-z]{3}-[0-9]{3}'
+#'     pattern: '[0-9]-[a-z]{3}-[0-9]{3}'
 #'     na_pass: true
 #'     preconditions: ~. %>% dplyr::filter(a < 10)
 #'     segments: b ~ c("group_1", "group_2")
@@ -219,12 +226,15 @@
 #' ```
 #'
 #' In practice, both of these will often be shorter as only the `columns` and
-#' `regex` arguments require values. Arguments with default values won't be
+#' `pattern` arguments require values. Arguments with default values won't be
 #' written to YAML when using [yaml_write()] (though it is acceptable to include
 #' them with their default when generating the YAML by other means). It is also
 #' possible to preview the transformation of an agent to YAML without any
 #' writing to disk by using the [yaml_agent_string()] function.
 #'
+#' Note that YAML files previously written with a `regex:` key are still
+#' accepted — the value will be used as the `pattern`.
+#'
 #' @section Examples:
 #'
 #' The `small_table` dataset in the package has a character-based `b` column
@@ -250,7 +260,7 @@
 #' ```r
 #' agent <-
 #'   create_agent(tbl = small_table) |>
-#'   col_vals_regex(columns = b, regex = pattern) |>
+#'   col_vals_regex(columns = b, pattern = pattern) |>
 #'   interrogate()
 #' ```
 #'
@@ -272,7 +282,7 @@
 #'
 #' ```{r}
 #' small_table |>
-#'   col_vals_regex(columns = b, regex = pattern) |>
+#'   col_vals_regex(columns = b, pattern = pattern) |>
 #'   dplyr::slice(1:5)
 #' ```
 #'
@@ -282,7 +292,7 @@
 #' time. This is primarily used in **testthat** tests.
 #'
 #' ```r
-#' expect_col_vals_regex(small_table, columns = b, regex = pattern)
+#' expect_col_vals_regex(small_table, columns = b, pattern = pattern)
 #' ```
 #'
 #' ## D: Using the test function
@@ -291,7 +301,7 @@
 #' us.
 #'
 #' ```{r}
-#' small_table |> test_col_vals_regex(columns = b, regex = pattern)
+#' small_table |> test_col_vals_regex(columns = b, pattern = pattern)
 #' ```
 #'
 #' @family validation functions
@@ -307,17 +317,34 @@ NULL
 col_vals_regex <- function(
     x,
     columns,
-    regex,
+    pattern,
     na_pass = FALSE,
     preconditions = NULL,
     segments = NULL,
     actions = NULL,
     step_id = NULL,
     label = NULL,
     brief = NULL,
-    active = TRUE
+    active = TRUE,
+    regex = NULL
 ) {
 
+  # Handle deprecated `regex` argument
+  if (!is.null(regex)) {
+    rlang::warn(
+      c(
+        "The `regex` argument of `col_vals_regex()` is deprecated.",
+        "i" = "Please use `pattern` instead."
+      ),
+      class = "pointblank_soft_deprecated",
+      .frequency = "once",
+      .frequency_id = "pointblank-col_vals_regex-regex-deprecation"
+    )
+    if (missing(pattern)) {
+      pattern <- regex
+    }
+  }
+
   # Capture the `columns` expression
   columns <- rlang::enquo(columns)
   # Get `columns` as a label
@@ -340,7 +367,7 @@ col_vals_regex <- function(
       create_agent(x, label = "::QUIET::") |>
       col_vals_regex(
         columns = tidyselect::all_of(columns),
-        regex = regex,
+        pattern = pattern,
         na_pass = na_pass,
         preconditions = preconditions,
         segments = segments,
@@ -359,7 +386,7 @@ col_vals_regex <- function(
   brief <- resolve_brief(
     brief = brief, agent = agent,
     columns = columns, segments_list = segments_list,
-    preconditions = preconditions, values = regex,
+    preconditions = preconditions, values = pattern,
     assertion_type = "col_vals_regex"
   )
 
@@ -389,7 +416,7 @@ col_vals_regex <- function(
           i_o = i_o,
           columns_expr = columns_expr,
           column = columns[i],
-          values = regex,
+          values = pattern,
           na_pass = na_pass,
           preconditions = preconditions,
           seg_expr = segments,
@@ -413,19 +440,36 @@ col_vals_regex <- function(
 expect_col_vals_regex <- function(
     object,
     columns,
-    regex,
+    pattern,
     na_pass = FALSE,
     preconditions = NULL,
-    threshold = 1
+    threshold = 1,
+    regex = NULL
 ) {
 
+  # Handle deprecated `regex` argument
+  if (!is.null(regex)) {
+    rlang::warn(
+      c(
+        "The `regex` argument of `expect_col_vals_regex()` is deprecated.",
+        "i" = "Please use `pattern` instead."
+      ),
+      class = "pointblank_soft_deprecated",
+      .frequency = "once",
+      .frequency_id = "pointblank-expect_col_vals_regex-regex-deprecation"
+    )
+    if (missing(pattern)) {
+      pattern <- regex
+    }
+  }
+
   fn_name <- "expect_col_vals_regex"
 
   vs <-
     create_agent(tbl = object, label = "::QUIET::") |>
     col_vals_regex(
       columns = {{ columns }},
-      regex = {{ regex }},
+      pattern = pattern,
       na_pass = na_pass,
       preconditions = {{ preconditions }},
       actions = action_levels(critical = threshold)
@@ -495,17 +539,34 @@ expect_col_vals_regex <- function(
 test_col_vals_regex <- function(
     object,
     columns,
-    regex,
+    pattern,
     na_pass = FALSE,
     preconditions = NULL,
-    threshold = 1
+    threshold = 1,
+    regex = NULL
 ) {
 
+  # Handle deprecated `regex` argument
+  if (!is.null(regex)) {
+    rlang::warn(
+      c(
+        "The `regex` argument of `test_col_vals_regex()` is deprecated.",
+        "i" = "Please use `pattern` instead."
+      ),
+      class = "pointblank_soft_deprecated",
+      .frequency = "once",
+      .frequency_id = "pointblank-test_col_vals_regex-regex-deprecation"
+    )
+    if (missing(pattern)) {
+      pattern <- regex
+    }
+  }
+
   vs <-
     create_agent(tbl = object, label = "::QUIET::") |>
     col_vals_regex(
       columns = {{ columns }},
-      regex = {{ regex }},
+      pattern = pattern,
       na_pass = na_pass,
       preconditions = {{ preconditions }},
       actions = action_levels(critical = threshold)

R/col_vals_str_len.R

@@ -224,7 +224,7 @@ expect_col_vals_str_len <- function(
       max = max,
       na_pass = na_pass,
       preconditions = {{ preconditions }},
-      actions = action_levels(notify_at = threshold)
+      actions = action_levels(critical = threshold)
     ) |>
     interrogate() |>
     (\(x) x$validation_set)()
@@ -303,7 +303,7 @@ test_col_vals_str_len <- function(
       max = max,
       na_pass = na_pass,
       preconditions = {{ preconditions }},
-      actions = action_levels(notify_at = threshold)
+      actions = action_levels(critical = threshold)
     ) |>
     interrogate() |>
     (\(x) x$validation_set)()

R/conjointly.R

@@ -54,7 +54,7 @@
 #'   A collection one-sided formulas that consist of validation functions that
 #'   validate row units (the `col_vals_*()` series), column existence
 #'   ([col_exists()]), or column type (the `col_is_*()` series). An example of
-#'   this is `~ col_vals_gte(., a, 5.5), ~ col_vals_not_null(., b`).
+#'   this is `~ col_vals_ge(., a, 5.5), ~ col_vals_not_null(., b`).
 #'
 #' @param .list *Alternative to `...`*
 #'

R/create_agent.R

@@ -401,7 +401,7 @@
 #'   ) |>
 #'   rows_distinct() |>
 #'   col_vals_gt(columns = d, value = 100) |>
-#'   col_vals_lte(columns = c, value = 5) |>
+#'   col_vals_le(columns = c, value = 5) |>
 #'   col_vals_between(
 #'     columns = c,
 #'     left = vars(a), right = vars(d),

R/object_ops.R

@@ -136,11 +136,11 @@
 #'   col_exists(columns = c(date, date_time)) |>
 #'   col_vals_regex(
 #'     columns = b,
-#'     regex = "[0-9]-[a-z]{3}-[0-9]{3}"
+#'     pattern = "[0-9]-[a-z]{3}-[0-9]{3}"
 #'   ) |>
 #'   rows_distinct() |>
 #'   col_vals_gt(columns = d, value = 100) |>
-#'   col_vals_lte(columns = c, value = 5) |>
+#'   col_vals_le(columns = c, value = 5) |>
 #'   interrogate()
 #' ```
 #'
@@ -614,11 +614,11 @@ x_read_disk <- function(
 #'   col_exists(columns = c(date, date_time)) |>
 #'   col_vals_regex(
 #'     columns = b,
-#'     regex = "[0-9]-[a-z]{3}-[0-9]{3}"
+#'     pattern = "[0-9]-[a-z]{3}-[0-9]{3}"
 #'   ) |>
 #'   rows_distinct() |>
 #'   col_vals_gt(columns = d, value = 100) |>
-#'   col_vals_lte(columns = c, value = 5) |>
+#'   col_vals_le(columns = c, value = 5) |>
 #'   interrogate()
 #' ```
 #'
@@ -907,7 +907,7 @@ export_report <- function(
 #'   col_exists(columns = c(date, date_time)) |>
 #'   col_vals_regex(
 #'     columns = b,
-#'     regex = "[0-9]-[a-z]{3}-[0-9]{3}"
+#'     pattern = "[0-9]-[a-z]{3}-[0-9]{3}"
 #'   ) |>
 #'   rows_distinct() |>
 #'   interrogate()

R/remove_deactivate.R

@@ -65,7 +65,7 @@
 #'   ) |>
 #'   col_vals_regex(
 #'     columns = b,
-#'     regex = "[0-9]-[a-z]{3}-[0-9]{3}",
+#'     pattern = "[0-9]-[a-z]{3}-[0-9]{3}",
 #'     active = FALSE
 #'   ) |>
 #'   interrogate()
@@ -149,7 +149,7 @@ activate_steps <- function(
 #'   col_exists(columns = date) |>
 #'   col_vals_regex(
 #'     columns = b,
-#'     regex = "[0-9]-[a-z]{3}-[0-9]"
+#'     pattern = "[0-9]-[a-z]{3}-[0-9]"
 #'   ) |>
 #'   interrogate()
 #'
@@ -230,7 +230,7 @@ deactivate_steps <- function(
 #'   col_exists(columns = date) |>
 #'   col_vals_regex(
 #'     columns = b,
-#'     regex = "[0-9]-[a-z]{3}-[0-9]"
+#'     pattern = "[0-9]-[a-z]{3}-[0-9]"
 #'   ) |>
 #'   interrogate()
 #'