diagnose_expressions {precondition}

Diagnose expressions and substitute debug markers

Description

Assertions in the precondition package support debug markers to provide user-friendly assertion failure diagnosis. The low-level diagnostic machinery is implemented by diagnose_expressions(). Advanced users can make use of this function in their own code or when implementing custom assertion helpers (see diagnose_assertion_failure()).

Use single curly braces {x} to mark expressions of interest and make them appear as separate entries in the diagnostic output. Use double curly braces {{x}} to perform checks on behalf of a parent function and display diagnostics in the context of the parent.

Usage

diagnose_expressions(..., .env)

Arguments

...

expressions to diagnose

.env

(advanced) the environment where the diagnosis should be performed

Details

diagnose_expressions() supports two kinds of debug markers. Both rely on wrapping expressions in one or more curly braces {}.

• wrapping an expression in curly braces (e.g. {x} > 0) means that the this expression is of particular interest and should be diagnosed separately. The braces will be removed from the diagnostic output and the wrapped expression will be added as a separate entry in the diagnostic table (note: diagnose_expressions({x} > 0) is equivalent to debug_expressions (x > 0, x)).

• wrapping a function argument in two curly braces (e.g. 'arg > 0) means that the argument is being been forwarded from a parent function. This concept of forwarding is borrowed from tidyverse's rlang::embrace-operator. A forwarded argument will be replaced by the original caller expression in the diagnostic output.

diagnose_expressions() returns a data frame with one row per diagnosed expression(either supplied as an argument or marked via {}) and three columns. The column expr is a list of diagnosed expressions, with debug markers processed and substituted. The column eval_result is a list of evaluated results for each diagnosed expressions. The column is_error is a logical vector where value of TRUE indicates that an error occurred when evaluating the respective expression. In this case the corresponding value of eval_result will capture the error condition.

Note that expressions or their parts might be evaluated more then once during diagnosis. Side effects in diagnosed expressions can lead to unexpected behavior.

Value

a data frame with diagnostic information

Examples

x <- 10
diagnose_expressions({x} > 0, {x} > 15)

helper <- function(arg) {
   cat(sprintf("`arg` is forwarded `%s`\n", forwarded_arg_label(arg)))
   diagnose_expressions({{{arg}}} > 0)
}
fun <- function(x) {
  helper(x)
}
fun(10)