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 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 default_subcommand: Option<String>,
    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, then each include, recursively.

What a build script has to watch. A generator that watches only the file it was pointed at rebuilds nothing when an included file changes — and include is how a CLI with many settings keeps them in a file of their own, so that is the file most likely to be edited.

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>

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 six pre-rendered sections — {{about}}, {{usage}}, {{commands}}, {{args}}, {{flags}}, {{after_help}} — which an author may reorder, omit or wrap in text of their own. Nothing else is substituted: a closed vocabulary is what lets an interpreter, a compiled parser and a generated Go program agree on where a section starts and ends rather than on a template language’s semantics.

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>

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.

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 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_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) -> Spec

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() -> Spec

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 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.