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
//! The declarative model an author fills in: commands, positional arguments,
//! and flags. This is pure data — the parser ([`crate::parse`]) consumes it and
//! the help renderer ([`crate::help`]) prints it. Authors never touch these
//! structs directly; they build them through the fluent methods on
//! [`crate::app::App`] and [`Command`].

/// A positional argument to a command, e.g. the `<name>` in `uff create <name>`.
#[derive(Debug, Clone)]
pub struct Arg {
    pub name: String,
    pub help: String,
    pub required: bool,
    /// If true, this argument soaks up all remaining positionals (variadic).
    pub variadic: bool,
}

impl Arg {
    pub fn new<S: Into<String>>(name: S) -> Self {
        Arg {
            name: name.into(),
            help: String::new(),
            required: true,
            variadic: false,
        }
    }
    pub fn help<S: Into<String>>(mut self, h: S) -> Self {
        self.help = h.into();
        self
    }
    pub fn optional(mut self) -> Self {
        self.required = false;
        self
    }
    pub fn variadic(mut self) -> Self {
        self.variadic = true;
        self
    }
}

/// What kind of value a flag takes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FlagKind {
    /// A boolean switch: present or absent (`--verbose`).
    Bool,
    /// Takes a single value (`--output file`, `-o file`).
    Value,
}

/// A flag / option, e.g. `-o, --output <FILE>`.
#[derive(Debug, Clone)]
pub struct Flag {
    pub long: String,
    pub short: Option<char>,
    pub value_name: Option<String>,
    pub help: String,
    pub kind: FlagKind,
    /// Default value for a value-flag when the user omits it.
    pub default: Option<String>,
}

impl Flag {
    /// A boolean switch flag.
    pub fn switch<S: Into<String>>(long: S) -> Self {
        Flag {
            long: long.into(),
            short: None,
            value_name: None,
            help: String::new(),
            kind: FlagKind::Bool,
            default: None,
        }
    }
    /// A value-taking option.
    pub fn value<S: Into<String>>(long: S) -> Self {
        let long = long.into();
        let vn = long.to_uppercase();
        Flag {
            long,
            short: None,
            value_name: Some(vn),
            help: String::new(),
            kind: FlagKind::Value,
            default: None,
        }
    }
    pub fn short(mut self, c: char) -> Self {
        self.short = Some(c);
        self
    }
    pub fn help<S: Into<String>>(mut self, h: S) -> Self {
        self.help = h.into();
        self
    }
    pub fn value_name<S: Into<String>>(mut self, n: S) -> Self {
        self.value_name = Some(n.into());
        self
    }
    pub fn default<S: Into<String>>(mut self, d: S) -> Self {
        self.default = Some(d.into());
        self
    }

    /// Render the invocation token for help, e.g. `-o, --output <FILE>`.
    pub(crate) fn invocation(&self) -> String {
        let mut s = String::new();
        if let Some(c) = self.short {
            s.push('-');
            s.push(c);
            s.push_str(", ");
        } else {
            s.push_str("    ");
        }
        s.push_str("--");
        s.push_str(&self.long);
        if self.kind == FlagKind::Value {
            let vn = self.value_name.as_deref().unwrap_or("VALUE");
            s.push_str(&format!(" <{}>", vn));
        }
        s
    }
}

/// A subcommand. The `run` closure is stored on the app side; this struct holds
/// only the descriptive spec used for parsing and help.
#[derive(Clone)]
pub struct Command {
    pub name: String,
    pub about: String,
    /// A longer description shown in the command's own `--help`.
    pub long_about: String,
    pub args: Vec<Arg>,
    pub flags: Vec<Flag>,
    /// Example invocations shown in long help.
    pub examples: Vec<String>,
    /// Marks the command as performing destructive on-disk changes, so the app
    /// can enforce the confirmation/`--sudo` guards.
    pub destructive: bool,
    /// Child command specs, when this command is a group. Populated by the app's
    /// group builder so help and completion can render the nested tree. Empty
    /// for leaf commands.
    pub subcommands: Vec<Command>,
}

impl Command {
    pub fn new<S: Into<String>>(name: S) -> Self {
        Command {
            name: name.into(),
            about: String::new(),
            long_about: String::new(),
            args: Vec::new(),
            flags: Vec::new(),
            examples: Vec::new(),
            destructive: false,
            subcommands: Vec::new(),
        }
    }
    /// Whether this command is a group (has child subcommands).
    pub fn is_group(&self) -> bool {
        !self.subcommands.is_empty()
    }
}