Module surface 

Available on crate feature surface-model only.

A CLI’s commands and flags as plain data, taken from its Clap types.

Clap remains the command grammar. Surface lists what a user of the CLI sees, for generated documentation files and the tests that compare them with the CLI. It holds the binary name, the mise task name, every command and alias, every argument, the Usage KDL, and the #USAGE mount line (see usage).

The surface-model feature builds a Surface. surface-serde adds serialization. surface-templates adds the shared minijinja fragments and the render function. A generated documentation file is then a render of the CLI’s own Clap types.

Structs

Surface

What a user sees of one Clap command tree.

SurfaceArgument

One positional argument or flag in a Surface, which Surface::new builds. A field can join it in a minor release.

SurfaceCommand

One command in a Surface, which Surface::new builds. A field can join it in a minor release.

Enums

SurfaceRequirement

Whether Clap requires an argument, as SurfaceArgument::requirement reports.

SurfaceScope

How far Clap propagates an argument, as SurfaceArgument::scope reports.

Constants

COMMANDS_FRAGMENTsurface-templates

Template source for ctl/commands.md.jinja: the macro command_inventory(surface) renders a table of the visible top-level commands, with their visible aliases and descriptions.

INVOCATION_FRAGMENTsurface-templates

Template source for ctl/invocation.md.jinja: the macro mounted_invocation(surface, examples) renders example mise run lines and the rule that they take no --.

VERSION_FRAGMENTsurface-templates

Template source for ctl/version.md.jinja: the macro version_line(version) renders the version: line of a generated file’s frontmatter.

Functions

add_fragmentssurface-templates

Add ctl-core’s shared fragments to environment, under the names ctl/version.md.jinja, ctl/invocation.md.jinja, and ctl/commands.md.jinja. A template imports them from there.

environmentsurface-templates

Create an Environment that holds the shared fragments.

rendersurface-templates

Render the template source, named name, in a fresh environment.