Struct Node 

pub struct Node { /* private fields */ }

Carries two metadata fields used by stratified (multi-tap) completion:

• category — free-form display tag. Apps can group root commands by category in expanded help / future renderers (e.g. workloads, documentation, tools).
• level — visibility tier. The Nth tab tap reveals every root-level node with level <= N. Default DEFAULT_LEVEL (= 1) means “always shown from the first tap.” Use a higher level (2, 3, …) for less-discoverable commands so the first tap stays focused on a small set the user wants by default.

Existing callers that didn’t set these fields get the pre-existing behavior automatically (everything visible at tap 1, no category metadata).

A node in the command tree. Carries everything a command-tree node can have: subcommand children, flags, providers, discovery metadata, help text, and a free-form attachment slot.

“Leaf” and “Group” are no longer separate variants. A node with no children is leaf-shaped; a node with children is group-shaped; a node with both is hybrid (e.g., report --workload x base, where report accepts --workload and has a base subcommand). Walkers branch on children.is_empty() only when the distinction actually matters.

All builder methods (with_*) return self so they chain. Methods that operate on children (e.g. with_child) work on any node — calling them just adds the child, regardless of whether the node was previously leaf-shaped or not.

Implementations

impl Node

pub fn new() -> Self

Empty node — no flags, no children, no metadata. Build up from here using the with_* builders.

pub fn leaf(flags: &[&str]) -> Self

Convenience: a leaf-shaped node carrying the supplied value-taking flags (none of them booleans).

pub fn leaf_with_flags(value_flags: &[&str], boolean_flags: &[&str]) -> Self

Convenience: a leaf-shaped node with separate value-taking and boolean flag lists.

pub fn group(children: Vec<(&str, Node)>) -> Self

Convenience: a group-shaped node from a list of (name, child) pairs. Add flags to the group separately via Node::with_flags / Node::with_boolean_flags.

pub fn empty_group() -> Self

Empty group — no children, no flags. Add via Node::with_child.

pub fn is_leaf(&self) -> bool

Leaf-shaped if it has no children. A node with both flags AND children is not leaf-shaped — it’s hybrid.

pub fn is_group(&self) -> bool

Group-shaped if it has at least one child.

pub fn with_child(self, name: &str, child: Node) -> Self

Add a child to this node. Works on any node; if the node was previously leaf-shaped, this turns it into a hybrid (flags + children).

pub fn children(&self) -> &BTreeMap<String, Node>

Direct access to children (empty for leaf-shaped nodes).

pub fn children_mut(&mut self) -> &mut BTreeMap<String, Node>

Mutable access to children — used by internal walkers.

pub fn child_names(&self) -> Vec<&str>

Names of this node’s children, in BTreeMap order.

pub fn child(&self, name: &str) -> Option<&Node>

Look up a child by name.

pub fn with_flags(self, flags: &[&str]) -> Self

Add value-taking flags to this node. Idempotent — duplicates are skipped.

pub fn with_boolean_flags(self, flags: &[&str]) -> Self

Add boolean flags (no value expected) to this node. Idempotent.

pub fn with_short_alias(self, short: &str, long: &str) -> Self

Register a short alias (-c) for a long flag (--config). The alias participates in value-position detection and value completion exactly like the long form.

pub fn flags(&self) -> &[String]

All flag names this node accepts (value-taking + boolean), in declared order.

pub fn is_flag(&self, flag: &str) -> bool

Returns true if flag is a boolean flag on this node.

pub fn options(&self) -> Vec<&str>

Convenience accessor — same as Node::flags but as a Vec<&str>. Kept for callers that prefer the &str view.

pub fn with_value_provider(self, flag: &str, provider: ValueProvider) -> Self

Attach a value provider to one of this node’s flags.

pub fn with_flag_conflict(self, flag: &str, conflicts: &str) -> Self

Declare that flag cannot be combined with conflicts — once conflicts is on the line, flag is withheld from completion. One direction only; callers wanting symmetric exclusion (the normal case — see cli::build_completion_tree) register both directions.

pub fn with_value_provider_aliases( self, aliases: &[&str], provider: ValueProvider, ) -> Self

Attach the same value provider to every name in aliases — e.g. --tofile and --to-file.

pub fn value_providers(&self) -> &BTreeMap<String, ValueProvider>

Direct access to the value-provider map (used by walkers).

pub fn with_positional_provider(self, provider: ValueProvider) -> Self

Attach a provider for this command’s first positional argument.

pub fn positional_provider(&self) -> Option<&ValueProvider>

The first-positional provider, if any.

pub fn with_positional_slots(self, slots: usize) -> Self

Declare how many positional slots the provider serves. The provider receives the completed words and decides per slot.

pub fn with_dynamic_options(self, provider: DynamicOptionsProvider) -> Self

Attach a dynamic options provider.

The provider is called during completion to discover additional key= options from context (e.g., workload-file parameters).

pub fn dynamic_options(&self) -> Option<DynamicOptionsProvider>

The attached dynamic options provider, if any.

pub fn with_category(self, cat: &str) -> Self

Tag this node with a display category.

pub fn category(&self) -> Option<&str>

Get the node’s category tag, if any.

pub fn with_stability(self, stability: Stability) -> Self

Declare this command’s maturity tier (see Stability). Controls whether it’s offered during completion at the active threshold.

pub fn stability(&self) -> Stability

This node’s maturity tier (default Stability::Stable).

pub fn with_level(self, lvl: u32) -> Self

Set the tap-tier visibility for this node.

pub fn level(&self) -> u32

Effective tap-tier level — explicit value if set, otherwise DEFAULT_LEVEL.

pub fn level_explicit(&self) -> Option<u32>

Explicit tap-tier level — None when with_level was never called. Used by strict-metadata validation.

pub fn with_help(self, text: &str) -> Self

Attach a one-line help summary.

pub fn help(&self) -> Option<&str>

Get the node’s help text, if any.

pub fn with_flag_help(self, flag: &str, help: &str) -> Self

Attach help text for one of this node’s flags.

pub fn with_flag_long_help(self, flag: &str, help: &str) -> Self

Builder: register extended help for a flag — surfaced on a rapid triple-tap at the value position. Mirrors clap’s Arg::long_help shape.

pub fn flag_long_help_for(&self, flag: &str) -> Option<&str>

Lookup extended help for a flag.

pub fn flag_help_for(&self, flag: &str) -> Option<&str>

Get help text for one of this node’s flags, if any.

pub fn with_subtree_provider(self, provider: SubtreeProvider) -> Self

Attach a context-aware completion override for this subtree.

pub fn subtree_provider(&self) -> Option<&SubtreeProvider>

The subtree provider, if any.

pub fn with_extras(self, extras: Extras) -> Self

Attach a free-form payload (handler, parser state, etc.).

pub fn extras(&self) -> Option<&Extras>

The attached extras payload, if any.

Trait Implementations

impl Clone for Node

fn clone(&self) -> Node

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Node

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

Formats the value using the given formatter.

impl Default for Node

fn default() -> Node

Returns the “default value” for a type.