Struct Spec 

#[non_exhaustive]
pub struct Spec {

    pub name: String,
    pub bin: String,
    pub cmd: SpecCommand,
    pub config: SpecConfig,
    pub version: Option<String>,
    pub long_version: Option<String>,
    pub usage: String,
    pub complete: IndexMap<String, SpecComplete>,
    pub views: IndexMap<String, SpecView>,
    pub flagsets: IndexMap<String, SpecFlagSet>,
    pub sources: Vec<PathBuf>,
    pub source_code_link_template: Option<String>,
    pub repository: Option<String>,
    pub author: Option<String>,
    pub about: Option<String>,
    pub about_long: Option<String>,
    pub about_md: Option<String>,
    pub license: Option<String>,
    pub logo: Option<String>,
    pub logo_style: Option<String>,
    pub before_help: Option<String>,
    pub after_help: Option<String>,
    pub before_help_long: Option<String>,
    pub after_help_long: Option<String>,
    pub help_template: Option<String>,
    pub disable_help: Option<bool>,
    pub min_usage_version: Option<String>,
    pub examples: Vec<SpecExample>,
    pub outputs: Vec<SpecOutput>,
    pub select: Option<String>,
    pub exit_codes: Vec<SpecExitCode>,
    pub default_subcommand: Option<String>,
    pub default_subcommand_flags: bool,
    pub default_subcommand_flags_set: bool,
    pub default_subcommand_on_empty: bool,
    pub default_subcommand_on_empty_set: bool,
    pub default_subcommand_help: bool,
    pub default_subcommand_help_set: bool,
    pub multicall: bool,
    pub unknown_flags: Option<UnknownFlags>,
    /* private fields */
}

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

name: String

bin: String

cmd: SpecCommand

config: SpecConfig

version: Option<String>

long_version: Option<String>

usage: String

complete: IndexMap<String, SpecComplete>

views: IndexMap<String, SpecView>

Named executable surfaces promoted from commands in this canonical spec.

flagsets: IndexMap<String, SpecFlagSet>

Reusable flag declarations, by name.

Not serialized, and not re-emitted: a use is resolved while the file is read, so by the time anything reads this spec the flags are on the commands that use them and these entries only record where they came from.

sources: Vec<PathBuf>

Every file this spec was read from: its own path, each include, and external output schema files, recursively.

What a build script has to watch. A generator that watches only the file it was pointed at rebuilds nothing when an included KDL or JSON schema changes.

Not serialized: it is where the spec came from rather than part of what it says, and usage g json describes the latter.

source_code_link_template: Option<String>

repository: Option<String>

Where the CLI’s source lives, e.g. https://github.com/jdx/mise.

Distinct from Self::source_code_link_template, which is a per-command deep link with a {{path}} placeholder and is only usable for building “view source” links in generated docs. Scraping a repository out of it works for one forge and one URL layout and fails everywhere else.

author: Option<String>

about: Option<String>

about_long: Option<String>

about_md: Option<String>

license: Option<String>

logo: Option<String>

Art printed on the program’s own help page, as the author wrote it.

Where it lands is decided by how wide the terminal is, not by the spec: beside the page when there is room for it there, above the page when there is not, and not at all on a terminal too narrow for even that. See crate::docs::logo.

The root page only. A logo is what a program is, and reprinting it on forty subcommand pages would make it furniture.

logo_style: Option<String>

How Self::logo is coloured, from the help_template style vocabulary.

One specification for the whole logo, +-combined as everywhere else — style="cyan+bold". Art that wants more colours than that carries its own escapes, which a plain page strips like any other authored escape.

before_help: Option<String>

after_help: Option<String>

before_help_long: Option<String>

after_help_long: Option<String>

help_template: Option<String>

How every page in this CLI is laid out, as named sections.

One template for the whole tree, holding the pre-rendered sections an author may reorder, omit, wrap or colour. Nothing else is substituted: the closed section and style vocabularies let an interpreter, a compiled parser and generated Go agree without exposing the metadata behind a section.

A placeholder naming no section is refused when the spec is read, so a page is never rendered from a template one of whose sections cannot be filled.

disable_help: Option<bool>

min_usage_version: Option<String>

examples: Vec<SpecExample>

outputs: Vec<SpecOutput>

CLI-wide outputs, inherited by every command that does not say otherwise.

select: Option<String>

The CLI-wide flag whose value picks among Self::outputs.

exit_codes: Vec<SpecExitCode>

CLI-wide exit codes, refined per command rather than replaced.

default_subcommand: Option<String>

Default subcommand to use when first non-flag argument is not a known subcommand. This enables “naked” command syntax like mise foo instead of mise run foo.

default_subcommand_flags: bool

Opt in to routing flags of the default command before its first positional.

default_subcommand_flags_set: bool

default_subcommand_on_empty: bool

Opt in to selecting the default subcommand for empty successful input.

default_subcommand_on_empty_set: bool

default_subcommand_help: bool

Opt in to appending the default command’s help page after the root page.

default_subcommand_help_set: bool

multicall: bool

Whether argv[0]’s basename selects a subcommand (busybox-style applets).

clap’s multicall. The dispatcher names (Self::name and Self::bin) are skipped; any other basename is parsed as the first word, so a symlink ls -> busybox runs the ls applet. Path components and a trailing .exe are stripped.

unknown_flags: Option<UnknownFlags>

What to do with a flag-like token that names no declared flag, for the whole CLI. A command may override it; see SpecCommand::unknown_flags.

Implementations

impl Spec

pub fn restamp(&mut self)

Recompute everything a command’s position in this tree decides, after building one by hand: each command’s path, its usage line, and the memoized subcommand lookup.

A SpecCommand inserted into subcommands carries the path it had wherever it came from — a spec of its own, most likely, where it was the root and its path was empty. Its help page would say so. So would its parent’s, which gains a <SUBCOMMAND> placeholder the first time it acquires a child. Call this after grafting, and the tree is indistinguishable from one that declared the same commands in KDL.

The alternative — writing the tree out and parsing it back, which is how this was reached before — costs a KDL round trip of the whole spec. For a large one that is a quarter of a second to fix up strings.

pub fn resolve_mount_outputs( &mut self, outputs: &HashMap<String, String>, ) -> Result<(), UsageErr>

Resolve every mount from supplied command outputs without spawning processes.

This is intended for deterministic generators and conformance harnesses. The map is keyed by each mount’s exact run declaration. Missing entries are an error, so injecting a partial view cannot silently execute the remainder.

pub fn parse_file(file: &Path) -> Result<Spec, UsageErr>

Parse a spec from a file.

Automatically detects whether the file is:

• A .kdl or .usage.kdl file containing a raw spec
• A script file with embedded #USAGE comments

If bin is not specified in the spec, it defaults to the filename.

pub fn parse_script(file: &Path) -> Result<Spec, UsageErr>

Parse a spec from a script file’s embedded USAGE comments.

Extracts the spec from comment lines marked with #USAGE, //USAGE, ::USAGE, or their [USAGE] variants. If bin is not specified in the spec, it defaults to the filename.

pub fn parse_script_str(input: &str) -> Result<Spec, UsageErr>

Parse a spec from a script string’s embedded USAGE comments.

Extracts the spec from comment lines marked with #USAGE, //USAGE, ::USAGE, or their [USAGE] variants. Unlike Self::parse_script, this function cannot infer bin or name from a filename. Relative include paths are rejected because there is no source path to resolve them against; absolute include paths remain supported.

pub fn parse_str_with_path(input: &str, file: &Path) -> Result<Spec, UsageErr>

Parse spec text that came from file, without reading the file itself.

For a caller that already holds the spec — because it extracted the spec lines from a larger file, or rendered them from a template — but knows which file they came from. The path is what relative include paths resolve against, and what diagnostics name, so the same text parsed through FromStr differs from this only in that its includes have nothing to be relative to.

pub fn parse_str_with_path_and_env( input: &str, file: &Path, env: &HashMap<String, String>, ) -> Result<Spec, UsageErr>

Parse spec text from file, expanding environment variables in include paths.

Expansion is deliberately limited to an include node’s file property. It accepts $NAME, ${NAME}, and $$; an undefined variable is an error. Other spec strings are left byte-for-byte unchanged. Included files inherit the same environment for nested includes.

pub fn parse_spec(input: &str) -> Result<Spec, UsageErr>

👎Deprecated

pub fn is_empty(&self) -> bool

pub fn for_view(&self, id: &str) -> Result<Spec, UsageErr>

Materialize one declared executable view.

This is a cold-path operation for documentation and completion generation. The canonical spec remains unchanged; the returned spec promotes the view’s command to the root and carries only the root globals the view declares.

pub fn view_for_program(&self, program: &str) -> Option<&str>

The stable identifier of the executable view selected by a program name.

pub fn merge(&mut self, other: Spec)

Trait Implementations

impl Clone for Spec

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Spec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Spec

fn default() -> Self

Returns the “default value” for a type.

impl Display for Spec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<SpecCommand> for Spec

A spec wrapping one command, for command trees built in Rust rather than parsed from KDL.

The command’s own name becomes the spec’s name and bin, and its help becomes the spec’s about — the same correspondence usage-dynamic applies in the other direction when it grafts a spec into a host as a command.

fn from(cmd: SpecCommand) -> Self

Converts to this type from the input type.

impl FromStr for Spec

type Err = UsageErr

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Serialize for Spec

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.