checkCLI usage

Quick Start

Basic Usage

Compare standard checkmate assertions with checkCLI:

Standard checkmate:

assert_int(3.14)
#> Error: Assertion on '3.14' failed: Must be of type 'single integerish value', not 'double'.

With checkCLI:

assert_int_cli(3.14)
#> Error:
#> ✖ Assertion on 3.14 failed.
#> ℹ Must be of type 'single integerish value', not 'double'

Function Categories

The package provides CLI-enhanced versions of checkmate functions organized into categories:

Scalars / Atomic Types

  • check_atomic_cli() / assert_atomic_cli()
  • check_atomic_vector_cli() / assert_atomic_vector_cli()
  • check_scalar_cli() / assert_scalar_cli()
  • check_scalar_na_cli() / assert_scalar_na_cli()
  • check_integer_cli() / assert_integer_cli()
  • check_integerish_cli() / assert_integerish_cli()
  • check_double_cli() / assert_double_cli()
  • check_complex_cli() / assert_complex_cli()
  • check_count_cli() / assert_count_cli()
  • check_string_cli() / assert_string_cli()
  • check_flag_cli() / assert_flag_cli()
  • check_int_cli() / assert_int_cli()
  • check_numeric_cli() / assert_numeric_cli()
  • check_number_cli() / assert_number_cli()
  • check_logical_cli() / assert_logical_cli()
  • check_character_cli() / assert_character_cli()
  • check_null_cli() / assert_null_cli()
  • check_true_cli() / assert_true_cli()
  • check_false_cli() / assert_false_cli()

Containers / Data Structures

  • check_array_cli() / assert_array_cli()
  • check_matrix_cli() / assert_matrix_cli()
  • check_vector_cli() / assert_vector_cli()
  • check_list_cli() / assert_list_cli()
  • check_data_frame_cli() / assert_data_frame_cli()
  • check_factor_cli() / assert_factor_cli()
  • check_environment_cli() / assert_environment_cli()
  • check_function_cli() / assert_function_cli()
  • check_formula_cli() / assert_formula_cli()
  • check_r6_cli() / assert_r6_cli()
  • check_raw_cli() / assert_raw_cli()

Names and Sets

  • check_names_cli() / assert_names_cli()
  • check_subset_cli() / assert_subset_cli()
  • check_permutation_cli() / assert_permutation_cli()
  • check_choice_cli() / assert_choice_cli()
  • check_set_equal_cli() / assert_set_equal_cli()
  • check_disjunct_cli() / assert_disjunct_cli()
  • check_class_cli() / assert_class_cli()
  • check_multi_class_cli() / assert_multi_class_cli()

Files, Directories, and Paths

  • check_file_cli() / assert_file_cli()
  • check_file_exists_cli() / assert_file_exists_cli()
  • check_directory_cli() / assert_directory_cli()
  • check_directory_exists_cli() / assert_directory_exists_cli()
  • check_path_for_output_cli() / assert_path_for_output_cli()

Date/Time and Special Classes

  • check_date_cli() / assert_date_cli()
  • check_posixct_cli() / assert_posixct_cli()
  • check_os_cli() / assert_os_cli()

Combination Assertions

  • assert_cli() - Combine multiple assertions with “or” or “and” logic

Usage Examples

Basic Assertion with Immediate Error

# This will produce a formatted error message
assert_numeric_cli(c("a", "b"))
#> Error:
#> ✖ Assertion on c("a", "b") failed.
#> ℹ Must be of type 'numeric', not 'character'

Using add Parameter for Error Collection

Collect multiple validation errors without stopping execution:

# Create an assertion collection
add <- AssertCollection$new()
#> Error: object 'AssertCollection' not found

# Run multiple assertions
assert_numeric_cli(c("a", "b"), add = add)
#> Error: object 'add' not found
assert_int_cli(3.14, add = add)
#> Error: object 'add' not found
assert_file_exists_cli("nonexistent.txt", add = add)
#> Error: object 'add' not found

# Report all errors at once
if (!add$isEmpty()) {
  add$report()
}
#> Error: object 'add' not found

Combining Multiple Assertions

# Assert that at least one condition is true ("or")
assert_cli(
  check_numeric_cli(x),
  check_integer_cli(x),
  combine = "or"
)
#> Error in eval(dots[[i]], envir = env): object 'x' not found

# Assert that all conditions are true ("and")
assert_cli(
  check_numeric_cli(x),
  check_vector_cli(x),
  combine = "and"
)
#> Error in eval(dots[[i]], envir = env): object 'x' not found

Custom Variable Names

# Specify a custom variable name in error messages
my_data <- "invalid"
assert_numeric_cli(my_data, .var.name = "my_data")
#> Error:
#> ✖ Assertion on my_data failed.
#> ℹ Must be of type 'numeric', not 'character'

Design Philosophy

checkCLI follows these principles:

  1. Transparency: All error messages are clear and actionable
  2. Consistency: Uses the same patterns across all validation functions
  3. Flexibility: Supports both fail-fast and error collection workflows
  4. Integration: Works seamlessly as a drop-in replacement for checkmate assertions
  5. Aesthetics: Leverages modern CLI formatting for professional output

Comparison: checkmate vs checkCLI

Aspect checkmate checkCLI
Error Messages Plain text Formatted with colors and bullets
Visual Clarity Minimal Enhanced with symbols (✖, ℹ)
Error Collection Supported Supported with better formatting
Integration Direct Wrapper functions with _cli suffix
Dependencies Core validation logic Extended with cli, glue, purrr
Learning Curve Standard R Minimal (identical API)

Error Message Examples

Type Validation Error

✖ Assertion on x failed.
ℹ Variable 'x' is not of type 'integer'

Multiple Validation Errors (Collected)

✖ Assertion on data failed.
ℹ (i): not numeric
ℹ (j): not integer

File Validation Error

✖ Assertion on filepath failed.
ℹ File '/path/to/missing.txt' does not exist

Best Practices

  1. Use _cli suffix versions for user-facing functions and packages
  2. Collect errors in production code using the add parameter for batch validation
  3. Provide custom variable names with .var.name for clarity in error messages
  4. Use assert_cli() with combine parameter for flexible multi-condition validation
  5. Check your R environment colors - the package respects system color capabilities