standout 7.7.0

Styled CLI template rendering with automatic terminal detection
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
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# Standout

A CLI framework for Rust that enforces separation between logic and presentation.

**Test your data. Render your view.**

```rust
use standout::cli::{CommandContext, Output};
use standout::handler;
use serde::Serialize;

#[derive(Serialize)]
struct ListResult { items: Vec<String>, total: usize }

#[handler]
fn list(#[ctx] _ctx: &CommandContext) -> Result<Output<ListResult>, anyhow::Error> {
    let items = storage::list()?;
    Ok(Output::Render(ListResult { total: items.len(), items }))
}

// Test the handler directly—no stdout capture needed
#[test]
fn test_list() {
    let Output::Render(result) = list(&ctx).unwrap() else {
        panic!("expected rendered data");
    };
    assert_eq!(result.total, 3);
}
```

In a full application, `storage` and application behavior belong in a
CLI-free library. The handler belongs in the binary package and adapts library
results into CLI-owned serializable view models. See the
[production-shaped example](https://standout.magik.works/guides/production-shaped-example.html).

## What is Standout?

Standout combines two standalone libraries into a cohesive framework:

- **[standout-dispatch](https://crates.io/crates/standout-dispatch)** — Execution pattern where handlers return data, renderers produce output
- **[standout-render](https://crates.io/crates/standout-render)** — Terminal rendering with templates, themes, and adaptive styles

The framework provides the glue: clap integration, `--output` flag handling, auto-dispatch from derive macros, and the `AppBuilder` configuration API.

## Why Standout?

CLI code that mixes logic with `println!` is impossible to unit test. With Standout:

- **Handlers return structs**, not strings—test them like any other function
- **Multiple output modes** from the same handler: rich terminal, JSON, YAML, CSV
- **MiniJinja templates** with hot reload during development
- **CSS/YAML themes** with automatic light/dark mode support
- **Incremental adoption**—migrate one command at a time

## Quick Start

```toml
[dependencies]
standout = "7"
standout-dispatch = "7" # required by #[handler] and #[derive(Dispatch)]
clap = { version = "4", features = ["derive"] }
serde = { version = "1", features = ["derive"] }
anyhow = "1"
```

```rust
use standout::cli::{App, Dispatch, CommandContext, HandlerResult, Output};
use standout::{embed_templates, embed_styles};
use clap::{ArgMatches, CommandFactory, Parser, Subcommand};

#[derive(Parser)]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand, Dispatch)]
#[dispatch(handlers = handlers)]
pub enum Commands {
    List,
}

mod handlers {
    use super::*;

    pub fn list(_m: &ArgMatches, _ctx: &CommandContext) -> HandlerResult<Vec<String>> {
        Ok(Output::Render(vec!["item-1".into(), "item-2".into()]))
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = App::builder()
        .commands(Commands::dispatch_config())?
        .templates(embed_templates!("src/templates"))
        .styles(embed_styles!("src/styles"))
        .build()?;

    app.run(Cli::command(), std::env::args());
    Ok(())
}
```

```bash
myapp list                  # Rich terminal output
myapp list --output json    # JSON for scripting
```

## Documentation

- **Book**: [standout.magik.works](https://standout.magik.works/)

### Framework Topics

- [App Configuration](https://standout.magik.works/topics/app-configuration.html) — AppBuilder API
- [Output Modes](https://standout.magik.works/topics/output-modes.html) — --output flag and format handling

### Crate Documentation

- [standout-render](https://standout.magik.works/crates/render/guides/intro-to-rendering.html) — Templates, themes, tabular layouts
- [standout-dispatch](https://standout.magik.works/crates/dispatch/guides/intro-to-dispatch.html) — Handlers, hooks, command routing

### API Reference

- [API Documentation](https://docs.rs/standout) — Full API reference

## Standalone Crates

Each component can be used independently:

- **[standout-render](https://crates.io/crates/standout-render)** — Use the rendering system without the framework
- **[standout-dispatch](https://crates.io/crates/standout-dispatch)** — Use the execution pattern with your own renderer

## License

MIT