---
title: "checkCLI usage"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{usage}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(checkmate)
library(checkCLI)
```

---

## Quick Start

### Basic Usage

Compare standard checkmate assertions with checkCLI:

**Standard checkmate:**
```{r, error=TRUE}
assert_int(3.14)
```

**With checkCLI:**
```{r, error=TRUE}
assert_int_cli(3.14)
```

### 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

```{r, error=TRUE}
# This will produce a formatted error message
assert_numeric_cli(c("a", "b"))
```

### Using `add` Parameter for Error Collection

Collect multiple validation errors without stopping execution:

```{r, error=TRUE}
# Create an assertion collection
add <- AssertCollection$new()

# Run multiple assertions
assert_numeric_cli(c("a", "b"), add = add)
assert_int_cli(3.14, add = add)
assert_file_exists_cli("nonexistent.txt", add = add)

# Report all errors at once
if (!add$isEmpty()) {
  add$report()
}
```

### Combining Multiple Assertions

```{r, error=TRUE}
# Assert that at least one condition is true ("or")
assert_cli(
  check_numeric_cli(x),
  check_integer_cli(x),
  combine = "or"
)

# Assert that all conditions are true ("and")
assert_cli(
  check_numeric_cli(x),
  check_vector_cli(x),
  combine = "and"
)
```

### Custom Variable Names

```{r, error=TRUE}
# Specify a custom variable name in error messages
my_data <- "invalid"
assert_numeric_cli(my_data, .var.name = "my_data")
```

---

## 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