Struct Catalog 

pub struct Catalog<'a> { /* private fields */ }

A validated collection of caller-supplied runtime command specs.

Building one validates; it does not assemble. The merged tree help and completion navigate costs a KDL round trip of the whole host spec, and dispatching a plugin command needs none of it — so it is built when something asks for it, and a host that only ever runs plugins never pays. See app.

Implementations

impl<'a> Catalog<'a>

pub fn builder(host: SpecView<'a>) -> Builder<'a>

Begin a catalog over a derive-generated Cli::app().

pub fn app(&self) -> Result<App<'_>, &Error>

Help and completion over the whole tree, static commands and runtime ones alike.

The merged tree is assembled here, on the first call, and kept. Building it is a KDL round trip of the host spec — cheap next to rendering a page, and not something parse_external should ever pay for, which is why it waits until somebody asks.

The error is a disagreement between the derived tables and the spec model that read them, which Builder::build cannot see because it has not lowered the host yet.

pub fn is_assembled(&self) -> bool

Whether the merged tree has been assembled yet.

app builds it once and keeps it, so this answers whether the next call is the expensive one. A catalog that is only ever dispatched through never assembles.

pub fn parse_external( &self, parent: &str, argv: &[OsString], ) -> Result<Option<Outcome>, Error>

Parse the argv an external-subcommand variant captured.

parent is the static command path the catch-all sits on, with the empty string meaning the root. The first token is the runtime command’s name, by any spelling it answers to.

Two of the outcomes here are the caller’s to handle rather than errors:

• Ok(None) — no catalogued command answers to that name. Whatever the host did with unrecognized words before it had a catalog, it should still do.
• Err(Error::NonUtf8) — a token the portable spec model cannot represent, because it parses Strings and this one is not one. The derive handed over OsStrings, which lose nothing, so the argv is still intact: dispatch it the same way as Ok(None) rather than failing a command whose argument happens to be an unusual path.

Defaults and environment fallbacks are applied by the plugin’s own spec, and --help and --version come back as Outcomes rather than as errors.

Trait Implementations

impl<'a> Debug for Catalog<'a>

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

Formats the value using the given formatter.