feat(errors): improved error handling via error classes, encpapsulation returns the condition objects (#141)

Author: sebffischer

.gitignore

@@ -43,3 +43,5 @@ revdep
 docs/
 cran-comments.md
 CRAN-SUBMISSION
+
+.vscode/

DESCRIPTION

@@ -56,6 +56,7 @@ Collate:
     'chunk.R'
     'compose.R'
     'compute_mode.R'
+    'conditions.R'
     'count_missing.R'
     'crate.R'
     'cross_join.R'

NAMESPACE

@@ -11,6 +11,8 @@ S3method(discard,default)
 S3method(distinct_values,default)
 S3method(distinct_values,factor)
 S3method(distinct_values,logical)
+S3method(format,Mlr3Error)
+S3method(format,Mlr3Warning)
 S3method(hash_input,"function")
 S3method(hash_input,data.table)
 S3method(hash_input,default)
@@ -81,6 +83,13 @@ export(discard)
 export(distinct_values)
 export(encapsulate)
 export(enframe)
+export(error_config)
+export(error_input)
+export(error_learner)
+export(error_learner_predict)
+export(error_learner_train)
+export(error_mlr3)
+export(error_timeout)
 export(every)
 export(extract_vars)
 export(format_bib)
@@ -165,6 +174,9 @@ export(topo_sort)
 export(transpose_list)
 export(unnest)
 export(walk)
+export(warning_config)
+export(warning_input)
+export(warning_mlr3)
 export(warningf)
 export(which_max)
 export(which_min)

NEWS.md

@@ -1,5 +1,11 @@
 # mlr3misc (development version)
 
+## New features:
+
+* Added various new functions for improved error handling.
+* `encapsulate()` now returns the specific condition objects along the logs, allowing for
+  improved error handling on the caller side.
+
 # mlr3misc 0.18.0
 
 * feat: Added `"mirai"` as encapsulation method to `encapsulate()`.

R/conditions.R

@@ -0,0 +1,121 @@
+#' @title Error Classes
+#' @name mlr_conditions
+#' @description
+#' Condition classes for mlr3.
+#'
+#' @section Formatting:
+#' It is also possible to use formatting options as defined in [`cli::cli_bullets`].
+#'
+#' @section Errors:
+#' * `error_mlr3()` for the base `Mlr3Error` class.
+#' * `error_config()` for the `Mlr3ErrorConfig` class, which signals that a user has misconfigured
+#'   something (e.g. invalid learner configuration).
+#' * `error_input()` for the `Mlr3ErrorInput` if an invalid input was provided.
+#'   method.
+#' * `error_timeout()` for the `Mlr3ErrorTimeout`, signalling a timeout (encapsulation).
+#' * `error_learner()` for the `Mlr3ErrorLearner`, signalling a learner error.
+#' * `error_learner_train()` for the `Mlr3ErrorLearner`, signalling a learner training error.
+#' * `error_learner_predict()` for the `Mlr3ErrorLearner`, signalling a learner prediction error.
+#'
+#' @section Warnings:
+#' * `warning_mlr3()` for the base `Mlr3Warning` class.
+#' * `warning_config()` for the `Mlr3WarningConfig` class, which signals that a user might have
+#'   misconfigured something.
+#' * `warning_input()` for the `Mlr3WarningInput` if an invalid input might have been provided.
+#'
+#' @param msg (`character(1)`)\cr
+#'   Error message.
+#' @param ... (any)\cr
+#'   Passed to [`sprintf()`].
+#' @param class (`character`)\cr
+#'   Additional class(es).
+#' @param signal (`logical(1)`)\cr
+#'   If `TRUE`, the condition object is returned.
+#' @export
+error_config = function(msg, ..., class = NULL, signal = TRUE) {
+  error_mlr3(msg, ..., class = "Mlr3ErrorConfig", signal = signal)
+}
+
+#' @rdname mlr_conditions
+#' @export
+error_input = function(msg, ..., class = NULL, signal = TRUE) {
+  error_mlr3(msg, ..., class = "Mlr3ErrorInput", signal = signal)
+}
+
+#' @rdname mlr_conditions
+#' @export
+error_timeout = function(signal = TRUE) {
+  error_mlr3("reached elapsed time limit", class = "Mlr3ErrorTimeout", signal = signal)
+}
+
+#' @rdname mlr_conditions
+#' @export
+error_mlr3 = function(msg, ..., class = NULL, signal = TRUE) {
+  cond = errorCondition(sprintf(msg, ...), class = c(class, "Mlr3Error"))
+  cond$message = format(cond)
+  if (signal) {
+    return(stop(cond))
+  }
+  cond
+}
+
+#' @rdname mlr_conditions
+#' @export
+warning_mlr3 = function(msg, ..., class = NULL, signal = TRUE) {
+  cond = warningCondition(sprintf(msg, ...), class = c(class, "Mlr3Warning"))
+  cond$message = format(cond)
+  if (signal) {
+    return(warning(cond))
+  }
+  cond
+}
+
+#' @rdname mlr_conditions
+#' @export
+warning_config = function(msg, ..., class = NULL, signal = TRUE) {
+  warning_mlr3(msg, ..., class = c(class, "Mlr3WarningConfig"), signal = signal)
+}
+
+#' @rdname mlr_conditions
+#' @export
+warning_input = function(msg, ..., class = NULL, signal = TRUE) {
+  warning_mlr3(msg, ..., class = c(class, "Mlr3WarningInput"), signal = signal)
+}
+
+
+#' @export
+format.Mlr3Error = function(x, ...) {
+  message = if (!is.null(names(x$message))) {
+    # error message is already a cli list
+    message = c(x$message, paste0("Class: ", class(x)[1L]))
+    names(message) = c(names(x$message), ">")
+    cli::format_bullets_raw(message)
+  } else {
+    cli::format_bullets_raw(c(
+      "x" = x$message,
+      ">" = paste0("Class: ", class(x)[1L])
+    ))
+  }
+  paste0("\n", paste0(message, collapse = "\n"), "\n")
+}
+
+#' @export
+format.Mlr3Warning = format.Mlr3Error
+
+#' @rdname mlr_conditions
+#' @export
+error_learner = function(msg, ..., class = NULL, signal = TRUE) {
+  error_mlr3(msg, ..., class = c(class, "Mlr3ErrorLearner"), signal = signal)
+}
+
+#' @rdname mlr_conditions
+#' @export
+error_learner_train = function(msg, ..., class = NULL, signal = TRUE) {
+  error_learner(msg, ..., class = c(class, "Mlr3ErrorLearnerTrain"), signal = signal)
+}
+
+#' @rdname mlr_conditions
+#' @export
+error_learner_predict = function(msg, ..., class = NULL, signal = TRUE) {
+  error_learner(msg, ..., class = c(class, "Mlr3ErrorLearnerPredict"), signal = signal)
+}