Add Classed error conditions for programmatic error handling

.ci/linters/rd/condition_class_docs_check.R

@@ -0,0 +1,51 @@
+# Ensure that data.table condition classes in code match documentation
+condition_classes_documentation_linter = function(rd_file) {
+  if (!grepl("\\name{datatable-condition-classes}", readChar(rd_file, 100L), fixed = TRUE)) return(invisible())
+
+  # Find condition classes in R code 
+  walk_r_ast_for_classes = function(expr) {
+    if (is.call(expr) && identical(expr[[1L]], quote(stopf)) && is.character(class_arg <- expr[["class"]]) && startsWith(class_arg, "dt_")) {
+      class_arg
+    } else if (is.recursive(expr)) {
+      unlist(lapply(expr, walk_r_ast_for_classes))
+    }
+  }
+
+  # Find condition classes in documentation  
+  walk_rd_ast_for_classes = function(rd_element) {
+    if (!is.list(rd_element)) return(character())
+
+    result = character()
+    if (isTRUE(attr(rd_element, "Rd_tag") == "\\code") && length(rd_element) >= 1L) {
+      content = rd_element[[1L]]
+      if (is.character(content) && startsWith(content, "dt_")) {
+        result = content
+      }
+    }
+    c(result, unlist(lapply(rd_element, walk_rd_ast_for_classes)))
+  }
+
+  code_classes = list.files("R", pattern = "\\.R$", full.names = TRUE) |>
+    lapply(\(f) lapply(parse(f), walk_r_ast_for_classes)) |>
+    unlist() |>
+    unique()
+
+  doc_classes = rd_file |>
+    tools::parse_Rd() |>
+    walk_rd_ast_for_classes() |>
+    unique()
+
+  miss_in_doc = setdiff(code_classes, doc_classes)
+  miss_in_code = setdiff(doc_classes, code_classes)
+
+  if (length(miss_in_doc) > 0L || length(miss_in_code) > 0L) {
+    if (length(miss_in_doc) > 0L) {
+      cat(sprintf("Condition classes in code but missing from docs: %s\n", toString(miss_in_doc)))
+    }
+    if (length(miss_in_code) > 0L) {
+      cat(sprintf("Condition classes in docs but not in code: %s\n", toString(miss_in_code)))
+    }
+    stop("Please sync man/datatable-condition-classes.Rd with code condition classes")
+  }
+}
+

R/bmerge.R

@@ -90,7 +90,7 @@ bmerge = function(i, x, icols, xcols, roll, rollends, nomatch, mult, ops, verbos
           next
         }
       }
-      stopf("Incompatible join types: %s (%s) and %s (%s). Factor columns must join to factor or character columns.", xname, x_merge_type, iname, i_merge_type)
+      stopf("Incompatible join types: %s (%s) and %s (%s). Factor columns must join to factor or character columns.", xname, x_merge_type, iname, i_merge_type, class="dt_join_type_mismatch_error")
     }
     if (x_merge_type == i_merge_type) {
       if (verbose) catf("%s has same type (%s) as %s. No coercion needed.\n", iname, x_merge_type, xname)
@@ -106,15 +106,15 @@ bmerge = function(i, x, icols, xcols, roll, rollends, nomatch, mult, ops, verbos
         coerce_col(x, xcol, x_merge_type, i_merge_type, xname, iname, from_detail=gettext(" (all-NA)"), verbose=verbose)
         next
       }
-      stopf("Incompatible join types: %s (%s) and %s (%s)", xname, x_merge_type, iname, i_merge_type)
+      stopf("Incompatible join types: %s (%s) and %s (%s)", xname, x_merge_type, iname, i_merge_type, class="dt_join_type_mismatch_error")
     }
     if (x_merge_type=="integer64" || i_merge_type=="integer64") {
       nm = c(iname, xname)
       if (x_merge_type=="integer64") { w=i; wc=icol; wclass=i_merge_type; } else { w=x; wc=xcol; wclass=x_merge_type; nm=rev(nm) }  # w is which to coerce
       if (wclass=="integer" || (wclass=="double" && fitsInInt64(w[[wc]]))) {
         from_detail = if (wclass == "double") gettext(" (which has integer64 representation, e.g. no fractions)") else ""
         coerce_col(w, wc, wclass, "integer64", nm[1L], nm[2L], from_detail, verbose=verbose)
-      } else stopf("Incompatible join types: %s is type integer64 but %s is type double and cannot be coerced to integer64 (e.g. has fractions)", nm[2L], nm[1L])
+      } else stopf("Incompatible join types: %s is type integer64 but %s is type double and cannot be coerced to integer64 (e.g. has fractions)", nm[2L], nm[1L], class="dt_join_type_mismatch_error")
     } else {
       # just integer and double left
       ic_idx = which(icol == icols) # check if on is joined on multiple conditions, #6602

R/groupingsets.R

@@ -4,7 +4,7 @@ rollup = function(x, ...) {
 rollup.data.table = function(x, j, by, .SDcols, id = FALSE, label = NULL, ...) {
   # input data type basic validation
   if (!is.data.table(x))
-    stopf("Argument 'x' must be a data.table object")
+    stopf("Argument 'x' must be a data.table object", class="dt_invalid_input_error")
   if (!is.character(by))
     stopf("Argument 'by' must be a character vector of column names used in grouping.")
   if (!is.logical(id))
@@ -22,7 +22,7 @@ cube = function(x, ...) {
 cube.data.table = function(x, j, by, .SDcols, id = FALSE, label = NULL, ...) {
   # input data type basic validation
   if (!is.data.table(x))
-    stopf("Argument 'x' must be a data.table object")
+    stopf("Argument 'x' must be a data.table object", class="dt_invalid_input_error")
   if (!is.character(by))
     stopf("Argument 'by' must be a character vector of column names used in grouping.")
   if (!is.logical(id))

R/merge.R

@@ -34,7 +34,7 @@ merge.data.table = function(x, y, by = NULL, by.x = NULL, by.y = NULL, all = FAL
     warningf("Supplied both `by` and `by.x`/`by.y`. `by` argument will be ignored.")
   if (!is.null(by.x)) {
     if (length(by.x) == 0L || !is.character(by.x) || !is.character(by.y))
-      stopf("A non-empty vector of column names is required for `by.x` and `by.y`.")
+      stopf("A non-empty vector of column names is required for `by.x` and `by.y`.", class="dt_invalid_input_error")
     if (!all(idx <- by.x %chin% nm_x)) {
       stopf("The following columns listed in `%s` are missing from %s: %s", "by.x", "x", brackify(by.x[!idx]))
     }

R/setkey.R

@@ -43,7 +43,7 @@ setkeyv = function(x, cols, verbose=getOption("datatable.verbose"), physical=TRU
   if (!all(nzchar(cols))) stopf("cols contains some blanks.")
   cols = gsub("`", "", cols, fixed = TRUE)
   miss = !(cols %chin% colnames(x))
-  if (any(miss)) stopf("some columns are not in the data.table: %s", brackify(cols[miss]))
+  if (any(miss)) stopf("some columns are not in the data.table: %s", brackify(cols[miss]), class = "dt_missing_column_error")
 
   if (physical && identical(head(key(x), length(cols)), cols)){ ## for !physical we need to compute groups as well #4387
     ## key is present but x has a longer key. No sorting needed, only attribute is changed to shorter key.
@@ -54,7 +54,7 @@ setkeyv = function(x, cols, verbose=getOption("datatable.verbose"), physical=TRU
   if (".xi" %chin% names(x)) stopf("x contains a column called '.xi'. Conflicts with internal use by data.table.")
   for (i in cols) {
     .xi = x[[i]]  # [[ is copy on write, otherwise checking type would be copying each column
-    if (!typeof(.xi) %chin% ORDERING_TYPES) stopf("Column '%s' is type '%s' which is not supported as a key column type, currently.", i, typeof(.xi))
+    if (!typeof(.xi) %chin% ORDERING_TYPES) stopf("Column '%s' is type '%s' which is not supported as a key column type, currently.", i, typeof(.xi), class="dt_unsortable_type_error")
   }
   if (!is.character(cols) || length(cols)<1L) internal_error("'cols' should be character at this point") # nocov
 
@@ -266,11 +266,11 @@ setorderv = function(x, cols = colnames(x), order=1L, na.last=FALSE)
   # remove backticks from cols
   cols = gsub("`", "", cols, fixed = TRUE)
   miss = !(cols %chin% colnames(x))
-  if (any(miss)) stopf("some columns are not in the data.table: %s", brackify(cols[miss]))
+  if (any(miss)) stopf("some columns are not in the data.table: %s", brackify(cols[miss]), class = "dt_missing_column_error")
   if (".xi" %chin% colnames(x)) stopf("x contains a column called '.xi'. Conflicts with internal use by data.table.")
   for (i in cols) {
     .xi = x[[i]]  # [[ is copy on write, otherwise checking type would be copying each column
-    if (!typeof(.xi) %chin% ORDERING_TYPES) stopf("Column '%s' is type '%s' which is not supported for ordering currently.", i, typeof(.xi))
+    if (!typeof(.xi) %chin% ORDERING_TYPES) stopf("Column '%s' is type '%s' which is not supported for ordering currently.", i, typeof(.xi), class="dt_unsortable_type_error")
   }
   if (!is.character(cols) || length(cols)<1L) internal_error("'cols' should be character at this point") # nocov
 

R/setops.R

@@ -14,11 +14,11 @@ setdiff_ = function(x, y, by.x=seq_along(x), by.y=seq_along(y), use.names=FALSE)
     icnam = names(y)[lc]
     xcnam = names(x)[rc]
     if ( is.character(x[[rc]]) && !(is.character(y[[lc]]) || is.factor(y[[lc]])) ) {
-      stopf("When x's column ('%s') is character, the corresponding column in y ('%s') should be factor or character, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]))
+      stopf("When x's column ('%s') is character, the corresponding column in y ('%s') should be factor or character, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]), class="dt_join_type_mismatch_error")
     } else if ( is.factor(x[[rc]]) && !(is.character(y[[lc]]) || is.factor(y[[lc]])) ) {
-      stopf("When x's column ('%s') is factor, the corresponding column in y ('%s') should be character or factor, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]))
+      stopf("When x's column ('%s') is factor, the corresponding column in y ('%s') should be character or factor, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]), class="dt_join_type_mismatch_error")
     } else if ( (is.integer(x[[rc]]) || is.double(x[[rc]])) && (is.logical(y[[lc]]) || is.character(y[[lc]])) ) {
-      stopf("When x's column ('%s') is integer or numeric, the corresponding column in y ('%s') can not be character or logical types, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]))
+      stopf("When x's column ('%s') is integer or numeric, the corresponding column in y ('%s') can not be character or logical types, but found incompatible type '%s'.", xcnam, icnam, typeof(y[[lc]]), class="dt_join_type_mismatch_error")
     }
   }
   ux = unique(shallow(x, by.x))
@@ -52,7 +52,7 @@ funique = function(x) {
   }
   if (!identical(sx<-sapply(x, super), sy<-sapply(y, super))) {
     w = which.first(sx!=sy)
-    stopf("Item %d of x is '%s' but the corresponding item of y is '%s'.", w, class1(x[[w]]), class1(y[[w]]))
+    stopf("Item %d of x is '%s' but the corresponding item of y is '%s'.", w, class1(x[[w]]), class1(y[[w]]), class="dt_join_type_mismatch_error")
   }
   if (.seqn && ".seqn" %chin% names(x)) stopf("None of the datasets should contain a column named '.seqn'")
 }

man/datatable-condition-classes.Rd

@@ -0,0 +1,38 @@
+\name{data.table-error-handling}
+\alias{data.table-error-handling}
+\title{Condition Handling with Classed Conditions}
+\description{
+\code{data.table} provides specific condition classes for common operations, making it easier to handle comditions programmatically. This is particularly useful when writing robust code or packages that use \code{data.table}. Relying on the exact text of condition messages is fragile (it is not uncommon to change the wording slightly, or for the user's session not to be in English); prefer using the signal class where possible.
+}
+\details{
+\subsection{Available error Classes}{
+\code{data.table} provides four specific error classes:
+
+\itemize{
+  \item \code{dt_missing_column_error}: When referencing columns that don't exist
+  \item \code{dt_invalid_input_error}: When providing invalid input types or empty required arguments
+  \item \code{dt_unsortable_type_error}: When trying to sort/key unsupported types
+  \item \code{dt_join_type_mismatch_error}: When column types are incompatible in joins/set operations
+}
+}
+
+\subsection{Backward Compatibility}{
+All condition classes inherit from base R's condition system, so existing \code{tryCatch(..., error = ...)} code continues to work unchanged. The new classes simply provide more specific handling options when needed.
+}
+}
+\examples{
+
+# Handle missing column errors specifically
+DT <- data.table(a = 1:3, b = 4:6)
+tryCatch({
+  setkey(DT, nonexistent_col)
+}, dt_missing_column_error = function(e) {
+  cat("Missing column detected:", conditionMessage(e), "\n")
+}, error = function(e) {
+  cat("Other error:", conditionMessage(e), "\n")
+})
+}
+\seealso{
+\code{\link{tryCatch}}, \code{\link{test}}, \url{https://adv-r.hadley.nz/conditions.html}
+For advanced exception handling patterns, see data.table's internal helper `tryCatch2` here - \url{https://github.com/jangorecki/logR/blob/master/R/logR.R}
+}