feat: add predefined R obj type hints

NAMESPACE

@@ -3,6 +3,7 @@
 export(abbrs)
 export(data_md_snips)
 export(data_roxy_lbls)
+export(data_types)
 export(description_lbl)
 export(ls_file_snips)
 export(md_snip)
@@ -12,6 +13,7 @@ export(roxy_lbl)
 export(roxy_lbls)
 export(snip_path)
 export(title_lbl)
+export(type)
 importFrom(magrittr,"%$%")
 importFrom(magrittr,"%<>%")
 importFrom(magrittr,"%>%")

Rmd/pkgsnip.Rmd

@@ -500,6 +500,67 @@ title_lbl <- function(id = roxy_lbls(type = "title")$id,
 }
 ```
 
+### `data_types`
+
+```{r}
+#' Type hints
+#'
+#' A [tibble][tibble::tbl_df] with all \R object type hints together with their `id`. The latter can be fed to [pkgsnip::type()].
+#'
+#' @format `r return_lbl("tibble_cols", cols = colnames(data_types))`
+#' @family roxylbl
+#' @export
+#'
+#' @examples
+#' pkgsnip::data_types
+"data_types"
+```
+
+### `type`
+
+```{r}
+#' Get predefined type hint
+#'
+#' Returns a predefined \R object type hint intended to be used to document a function parameter's type.
+#'
+#' @param id Type identifier. One of `r data_types$id |> pal::as_md_vals() |> cli::ansi_collapse(last = " or ")`
+#' @param length Length of the \R object to be documented.
+#' @param add_cr Whether or not to suffix the returned string with an [Rd line break
+#'   (`\cr`)](https://rstudio.github.io/r-manuals/r-exts/Writing-R-documentation-files.html#sectioning).
+#'
+#' @return `r pkgsnip::return_lbl("glue_chr")`
+#' @family roxylbl
+#' @export
+#'
+#' @examples
+#' pkgsnip::type(id = "lgl",
+#'               length = 3L)
+#'
+#' pkgsnip::type(id = "pg_connection")
+type <- function(id = data_types$id,
+                 length = 1L,
+                 add_cr = TRUE) {
+  
+  id <- rlang::arg_match(id)
+  checkmate::assert_int(length)
+  checkmate::assert_flag(add_cr)
+  
+  result <- data_types |> dplyr::filter(id == !!id)
+  
+  if (length > 1L && !result$has_length) {
+    cli::cli_abort("The {.val {id}} type hint does not support a {.arg length} other than {.val {1L}}.")
+  }
+  
+  result <- glue::glue(result$value,
+                       length = length)
+  if (add_cr) {
+    result %<>% paste0("\\cr")
+  }
+  
+  result
+}
+```
+
 ## Common abbreviations
 
 ### `abbrs`

Rmd/sysdata.nopurl.Rmd

@@ -124,6 +124,21 @@ if (nrow(duplicated_data_roxy_lbls) > 0L) {
 }
 ```
 
+## `data_types`
+
+```{r}
+data_types <-
+  pal::toml_validate(input = "data-raw/types.toml") |>
+  pal::toml_read() |>
+  purrr::imap(\(x, i) tibble::tibble(id = i,
+                                     value = x$value)) |>
+  purrr::list_rbind() |>
+  dplyr::mutate(has_length = stringr::str_detect(string = value,
+                                                 pattern = stringr::fixed("{length}"))) |>
+  assertr::assert(predicate = assertr::is_uniq,
+                  "id")
+```
+
 # Write data
 
 Save all the small data objects as a single internal file `R/sysdata.rda`. Note that when documenting them, they must be explicitly `@export`ed to be available
@@ -133,6 +148,7 @@ to package users.
 usethis::use_data(data_abbrs,
                   data_md_snips,
                   data_roxy_lbls,
+                  data_types,
                   roxy_tags_lbl,
                   internal = TRUE,
                   overwrite = TRUE,

data-raw/types.toml

@@ -0,0 +1,19 @@
+# R object types
+
+[chr]
+value = "[`character({length})`][character]"
+
+[date]
+value = "[`Date`][base::Date]"
+
+[int]
+value = "[`integer({length})`][integer]"
+
+[lgl]
+value = "[`logical({length})`][logical]"
+
+[num]
+value = "[`numeric({length})`][numeric]"
+
+[pg_connection]
+value = "[`PqConnection`][RPostgres::dbGetInfo_PqConnection]"