unilang_help 0.2.0

Reusable help-page domain model, verbosity levels, and renderers for unilang-style CLIs. 
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
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# unilang_help

Reusable help-page domain model, verbosity levels, and renderers for unilang-style CLIs.

## Why a separate crate

Help rendering has no reason to depend on a command framework's type system. This crate defines a small, pre-rendered-string data model — the producing side (for example `unilang`'s help adapter) converts its own command definitions into that model once, and every renderer here consumes it unchanged. Any CLI that can describe a command as strings can reuse the renderers.

## Components

| Component | Purpose |
|-----------|---------|
| `HelpCommandData` / `HelpParamData` | Renderer-independent help data for one command and its parameters |
| `HelpVerbosity` | Five detail levels, Minimal (0) to Comprehensive (4); default Standard (2); reads `UNILANG_HELP_VERBOSITY` |
| `HelpDisplayOptions` | Global visibility toggles (version, status, aliases, tags); reads `UNILANG_HELP_HIDE_VERSION` |
| `PlainRenderer` | Plain-text command pages at all five verbosity levels, plus a parameter detail page |
| `CliFmtRenderer` | Column-aligned, colour-aware command and parameter pages via `cli_fmt`; mandatory whenever the crate is enabled |

The `PlainRenderer` command-page formats are a line-faithful port of the original `unilang` `HelpGenerator` output — consumers migrating from that implementation get byte-identical text for the same data.

## Example

```rust
use unilang_help::{ HelpCommandData, HelpParamData, HelpVerbosity, PlainRenderer };

let mut param = HelpParamData::default();
param.name = "scope".into();
param.kind = "Enum".into();
param.kind_compact = "enum".into();
param.description = "Discovery strategy selector.".into();
param.optional = true;
param.choices = vec![ "local".into(), "global".into() ];

let mut cmd = HelpCommandData::default();
cmd.name = ".rollup".into();
cmd.description = "Aggregate readme files.".into();
cmd.params.push( param );

let renderer = PlainRenderer::default().with_verbosity( HelpVerbosity::Basic );
let page = renderer.render( &cmd );
assert!( page.contains( ".rollup - Aggregate readme files." ) );
assert!( page.contains( "  scope::enum" ) );
```

Parameter detail pages are rendered from the same data:

```rust
use unilang_help::{ HelpCommandData, HelpParamData, PlainRenderer };

let mut param = HelpParamData::default();
param.name = "scope".into();
param.kind = "Enum".into();
param.kind_compact = "enum".into();
param.choices = vec![ "local".into(), "global".into() ];

let mut cmd = HelpCommandData::default();
cmd.name = ".rollup".into();

let page = PlainRenderer::default().render_param( &cmd, &param );
assert!( page.contains( "Parameter: scope" ) );
assert!( page.contains( "Choices: local, global" ) );
```

## Features

| Feature | Default | Purpose |
|---------|---------|---------|
| `enabled` | yes | Core model, verbosity, `PlainRenderer`, and `CliFmtRenderer` (backed by `cli_fmt`'s detail-page template) — a single master switch, no partial configuration |
| `full` | — | Alias for `enabled`, kept for cross-crate consistency |

`cli_fmt` is a mandatory dependency of this crate: there is no plain-text-only
configuration that excludes `CliFmtRenderer`. `PlainRenderer` remains available
alongside it as a lighter-weight rendering choice, not as a way to opt out of
the `cli_fmt` dependency itself.

## Environment variables

| Variable | Effect |
|----------|--------|
| `UNILANG_HELP_VERBOSITY=0..4` | Selects the verbosity level (`HelpVerbosity::from_env`) |
| `UNILANG_HELP_HIDE_VERSION=1` | Hides version lines globally (`HelpDisplayOptions::with_env_overrides`) |