cornerlibstone 0.1.0

Lib Cornerstone — a zero-dependency foundation for building command-line tools in Rust: argument parsing, nested subcommands, themeable help in multiple presets, structured errors and exit codes, config loading, interactive prompts, shell-completion and man/markdown generation, logging, JSON output, and root/destructive-operation guards.
Documentation
//! Help rendering with selectable presets.
//!
//! Three presets ship, each modelled on a real house style:
//!
//! * [`HelpStyle::Standard`] — the classic `Usage: / Commands: / Options:`
//!   layout (clap-like).
//! * [`HelpStyle::Banner`] — an indented banner with a tagline and example
//!   invocation lines, flags grouped under the command.
//! * [`HelpStyle::Sections`] — a name header followed by one block per command,
//!   each showing its invocation pattern and a wrapped description.
//!
//! Every preset renders both app-level help and per-command help, and supports
//! a compact tier (`-h`) and an expanded tier (`--help`) with examples.

use crate::spec::{Command, FlagKind};
use crate::style as s;

/// Which visual preset to use for help output. Beyond the three built-ins, an
/// app can supply a [`HelpRenderer`] for a fully custom look (see
/// [`crate::app::App::help_renderer`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[derive(Default)]
pub enum HelpStyle {
    #[default]
    Standard,
    Banner,
    Sections,
}


/// A pluggable help renderer. Implement this and register it with
/// [`crate::app::App::help_renderer`] to define a help look the built-in presets
/// don't cover. The library calls these to produce the final strings; it does
/// no post-processing, so the renderer has full control.
pub trait HelpRenderer: 'static {
    /// Render the top-level app help. `long` selects the expanded tier.
    fn app_help(&self, info: &AppInfo, long: bool) -> String;
    /// Render help for a single subcommand.
    fn command_help(&self, app_name: &str, cmd: &Command, long: bool) -> String;
}

/// Everything the renderer needs to know about the app itself.
pub struct AppInfo<'a> {
    pub name: &'a str,
    pub version: &'a str,
    pub about: &'a str,
    pub long_about: &'a str,
    pub commands: &'a [Command],
    /// Global flags available on every command.
    pub globals: &'a [crate::spec::Flag],
}

/// Render top-level help. `long` selects the expanded tier.
pub fn app_help(info: &AppInfo, style: HelpStyle, long: bool) -> String {
    match style {
        HelpStyle::Standard => app_standard(info, long),
        HelpStyle::Banner => app_banner(info, long),
        HelpStyle::Sections => app_sections(info, long),
    }
}

/// Render help for a single subcommand.
pub fn command_help(app_name: &str, cmd: &Command, style: HelpStyle, long: bool) -> String {
    match style {
        HelpStyle::Standard => cmd_standard(app_name, cmd, long),
        HelpStyle::Banner => cmd_banner(app_name, cmd, long),
        HelpStyle::Sections => cmd_sections(app_name, cmd, long),
    }
}

// ---------- shared helpers ----------

fn usage_line(app_name: &str, cmd: &Command) -> String {
    let mut u = format!("{} {}", app_name, cmd.name);
    if !cmd.flags.is_empty() {
        u.push_str(" [OPTIONS]");
    }
    for a in &cmd.args {
        if a.variadic {
            u.push_str(&format!(" [{}]...", a.name));
        } else if a.required {
            u.push_str(&format!(" <{}>", a.name));
        } else {
            u.push_str(&format!(" [{}]", a.name));
        }
    }
    u
}

fn wrap_to(text: &str, width: usize, indent: &str) -> String {
    let mut out = String::new();
    let mut line_len = 0;
    for (wi, word) in text.split_whitespace().enumerate() {
        if wi != 0 && line_len + 1 + word.len() > width {
            out.push('\n');
            out.push_str(indent);
            line_len = 0;
        } else if wi != 0 {
            out.push(' ');
            line_len += 1;
        }
        out.push_str(word);
        line_len += word.len();
    }
    out
}

// ---------- Standard preset ----------

fn app_standard(info: &AppInfo, long: bool) -> String {
    let mut out = String::new();
    let about = if long && !info.long_about.is_empty() {
        info.long_about
    } else {
        info.about
    };
    if !about.is_empty() {
        out.push_str(&format!("{}\n\n", about));
    }
    out.push_str(&format!("{} {} [COMMAND]\n\n", s::bold("Usage:"), info.name));

    if !info.commands.is_empty() {
        out.push_str(&format!("{}\n", s::bold("Commands:")));
        let w = info.commands.iter().map(|c| c.name.len()).max().unwrap_or(0);
        for c in info.commands {
            out.push_str(&format!("  {:<w$}  {}\n", s::cyan(&c.name), c.about, w = w));
        }
        out.push('\n');
    }

    out.push_str(&format!("{}\n", s::bold("Options:")));
    for f in info.globals {
        out.push_str(&format!("  {:<24}  {}\n", f.invocation(), f.help));
    }
    out
}

fn cmd_standard(app_name: &str, cmd: &Command, long: bool) -> String {
    let mut out = String::new();
    let about = if long && !cmd.long_about.is_empty() {
        &cmd.long_about
    } else {
        &cmd.about
    };
    if !about.is_empty() {
        out.push_str(&format!("{}\n\n", about));
    }
    if long && !cmd.examples.is_empty() {
        out.push_str(&format!("{} {}\n\n", s::bold("Examples:"), cmd.examples.join("  ")));
    }

    // Group: show usage as `app cmd <subcommand>` and list the children.
    if cmd.is_group() {
        out.push_str(&format!(
            "{} {} {} <subcommand>\n\n",
            s::bold("Usage:"),
            app_name,
            cmd.name
        ));
        out.push_str(&format!("{}\n", s::bold("Commands:")));
        let w = cmd.subcommands.iter().map(|c| c.name.len()).max().unwrap_or(0);
        for c in &cmd.subcommands {
            out.push_str(&format!("  {:<w$}  {}\n", s::cyan(&c.name), c.about, w = w));
        }
        return out;
    }

    out.push_str(&format!("{} {}\n", s::bold("Usage:"), usage_line(app_name, cmd)));

    if !cmd.args.is_empty() {
        out.push_str(&format!("\n{}\n", s::bold("Arguments:")));
        let w = cmd.args.iter().map(|a| a.name.len() + 2).max().unwrap_or(0);
        for a in &cmd.args {
            let token = format!("<{}>", a.name);
            out.push_str(&format!("  {:<w$}  {}\n", token, a.help, w = w));
        }
    }

    out.push_str(&format!("\n{}\n", s::bold("Options:")));
    if long {
        for f in &cmd.flags {
            out.push_str(&format!("  {}\n          {}\n\n", f.invocation(), f.help));
        }
        out.push_str("  -h, --help\n          Print help\n");
    } else {
        for f in &cmd.flags {
            out.push_str(&format!("  {:<24}  {}\n", f.invocation(), f.help));
        }
        out.push_str(&format!("  {:<24}  Print help\n", "-h, --help"));
    }
    out
}

// ---------- Banner preset ----------

fn app_banner(info: &AppInfo, long: bool) -> String {
    let mut out = String::new();
    out.push('\n');
    out.push_str(&format!("  {} — {}\n\n", s::heading(info.name), info.about));

    for c in info.commands {
        let inv = usage_line(info.name, c);
        out.push_str(&format!("  {:<32} {}\n", s::bold(&inv), c.about));
    }
    out.push('\n');

    // Group flags per command, banner-style.
    for c in info.commands {
        if c.flags.is_empty() {
            continue;
        }
        let group: Vec<String> = c
            .flags
            .iter()
            .map(|f| {
                let short = f.short.map(|s| format!("-{}", s)).unwrap_or_default();
                format!("{} {}", short, f.help)
            })
            .collect();
        out.push_str(&format!(
            "  {} ({}): {}\n",
            s::dim("Flags"),
            c.name,
            group.join("  ")
        ));
    }

    if long && !info.long_about.is_empty() {
        out.push_str(&format!("\n  {}\n", wrap_to(info.long_about, 70, "  ")));
    }
    out.push('\n');
    out
}

fn cmd_banner(app_name: &str, cmd: &Command, long: bool) -> String {
    let mut out = String::new();
    out.push('\n');
    out.push_str(&format!("  {} — {}\n\n", s::heading(&cmd.name), cmd.about));

    if cmd.is_group() {
        for c in &cmd.subcommands {
            out.push_str(&format!(
                "  {:<28} {}\n",
                s::bold(format!("{} {} {}", app_name, cmd.name, c.name)),
                c.about
            ));
        }
        out.push('\n');
        return out;
    }

    out.push_str(&format!("  {}\n", s::bold(usage_line(app_name, cmd))));

    if !cmd.flags.is_empty() {
        out.push('\n');
        for f in &cmd.flags {
            out.push_str(&format!("    {:<28} {}\n", f.invocation(), f.help));
        }
    }
    if long && !cmd.examples.is_empty() {
        out.push_str(&format!("\n  {}\n", s::dim("Examples:")));
        for ex in &cmd.examples {
            out.push_str(&format!("    {}\n", ex));
        }
    }
    out.push('\n');
    out
}

// ---------- Sections preset ----------

fn app_sections(info: &AppInfo, long: bool) -> String {
    let mut out = String::new();
    out.push_str(&format!("{}\n\n", s::heading(info.name)));

    for c in info.commands {
        // Header line: the invocation pattern.
        let mut pattern = format!("{}: {} {}", c.name, info.name, c.name);
        for a in &c.args {
            if a.required {
                pattern.push_str(&format!(" <{}>", a.name));
            } else {
                pattern.push_str(&format!(" [{}]", a.name));
            }
        }
        for f in &c.flags {
            let short = f.short.map(|c| format!("-{}", c)).unwrap_or(format!("--{}", f.long));
            if f.kind == FlagKind::Value {
                pattern.push_str(&format!(" [{} {}]", short, f.value_name.as_deref().unwrap_or("val")));
            } else {
                pattern.push_str(&format!(" [{}]", short));
            }
        }
        out.push_str(&format!("  {}\n", s::bold(&pattern)));
        if !c.about.is_empty() {
            out.push_str(&format!("           {}\n", wrap_to(&c.about, 60, "           ")));
        }
        out.push('\n');
    }

    if long && !info.long_about.is_empty() {
        out.push_str(&format!("{}\n", wrap_to(info.long_about, 72, "")));
    }
    out
}

fn cmd_sections(app_name: &str, cmd: &Command, long: bool) -> String {
    let mut out = String::new();
    out.push_str(&format!("{}\n\n", s::heading(format!("{} {}", app_name, cmd.name))));
    let about = if long && !cmd.long_about.is_empty() {
        &cmd.long_about
    } else {
        &cmd.about
    };
    if !about.is_empty() {
        out.push_str(&format!("{}\n\n", wrap_to(about, 72, "")));
    }

    if cmd.is_group() {
        for c in &cmd.subcommands {
            out.push_str(&format!(
                "  {}\n           {}\n\n",
                s::bold(format!("{} {} {}", app_name, cmd.name, c.name)),
                wrap_to(&c.about, 60, "           ")
            ));
        }
        return out;
    }

    out.push_str(&format!("  {}\n", s::bold(usage_line(app_name, cmd))));
    if !cmd.flags.is_empty() {
        out.push('\n');
        for f in &cmd.flags {
            out.push_str(&format!("    {:<28} {}\n", f.invocation(), f.help));
        }
    }
    if long && !cmd.examples.is_empty() {
        out.push('\n');
        for ex in &cmd.examples {
            out.push_str(&format!("  {} {}\n", s::dim("e.g."), ex));
        }
    }
    out
}