# 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