cli_fmt 0.12.1

CLI output formatting utilities for command-line applications
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

# Feature: Output Processing

### Scope

- **Purpose**: Describe the CLI output processing capability and its design boundaries.
- **Responsibility**: Document the three-stage pipeline — stream selection, line filtering, and width truncation.
- **In Scope**: Head/tail filtering, ANSI-aware width truncation, stream merging, and result metadata.
- **Out of Scope**: Public API contract — see `api/001_output_api.md`.

### Design

CLI output processing for command-line applications. This feature encodes CLI-specific
policy decisions that are intentionally excluded from general-purpose string utilities.

Processing applies three sequential stages:

**Stream selection** — merges stdout and stderr according to a configurable stream filter.
The default ordering places stderr before stdout, following the CLI convention that errors
should be visible without scrolling past normal output.

**Line filtering** — applies head and tail limits to the combined output. Head retains
the first N lines; tail retains the last N lines. When both limits are set, the union
of both windows is preserved. The count of omitted lines is always tracked accurately,
including the case where head and tail windows overlap. Line filtering requires the
`string_split` and `std` features; when either is absent, the filtering stage passes
content through unchanged with zero lines reported as omitted.

**Width truncation** — truncates any line whose visible character count exceeds the
configured maximum. ANSI escape sequences are excluded from visible width measurement.
A configurable suffix marks truncated lines. Width of zero disables truncation entirely.

The result always includes metadata: count of lines removed by head/tail filtering, and
a flag indicating whether any line was truncated by the width limit.

### APIs

| File | Relationship |
|------|-------------|
| [`../api/001_output_api.md`](../api/001_output_api.md) | Public contract for the output processing function and types |

### Feature Tests

| File | Relationship |
|------|-------------|
| [`../../tests/docs/feature/001_output_processing.md`](../../tests/docs/feature/001_output_processing.md) | Test specification verifying the behavioral cases defined here |

### Invariants

| File | Relationship |
|------|-------------|
| [`../invariant/001_architectural_boundary.md`](../invariant/001_architectural_boundary.md) | Boundary principle governing which logic belongs here |

### Sources

| File | Relationship |
|------|-------------|
| `src/output.rs` | Three-stage pipeline implementation — stream selection, line filtering, width truncation |

### Tests

| File | Relationship |
|------|-------------|
| `tests/output.rs` | Pipeline correctness across filtering, truncation, and stream ordering |