Struct ParamSchema 

#[non_exhaustive]
pub struct ParamSchema {
    pub name: String,
    pub param_type: String,
    pub required: bool,
    pub default: Option<Value>,
    pub description: String,
    pub aliases: Vec<String>,
    pub consumes: usize,
    pub repeatable: bool,
    pub positional: bool,
}

Schema for a tool parameter.

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

Parameter name.

param_type: String

Type hint (string, int, bool, array, object, any).

required: bool

Whether this parameter is required.

default: Option<Value>

Default value if not required.

description: String

Description for help text.

aliases: Vec<String>

Alternative names/flags for this parameter (e.g., “-r”, “-R” for “recursive”).

consumes: usize

Number of positional tokens this non-bool flag consumes per occurrence.

Default 1 (standard --flag value). Set to 2 for --flag NAME VALUE patterns such as jq’s --arg / --argjson. When consumes > 1, the kernel collects each occurrence as an inner array and accumulates repeated occurrences under the same named key — the tool sees a Value::Json(Array(Array(...))) listing every (N-tuple) occurrence.

repeatable: bool

True when this flag may appear more than once and each occurrence should be kept (clap’s ArgAction::Append, i.e. a Vec<_> value flag like sed’s -e). When set, the kernel accumulates every occurrence under the same named key as a Value::Json(Array(...)) instead of letting the last write win — the “no silent drop” contract for repeated flags. Orthogonal to consumes: consumes is values-per-occurrence, repeatable is occurrences-per-invocation.

positional: bool

True for positional arguments (cat foo.txt), false for flags (grep --ignore-case). The validator matches positional params against args.positional by their order among positionals only, independent of where they sit in the clap struct. Default false so hand-built ParamSchema::required(...) constructors keep flag semantics; clap-reflected positionals set it via arg.get_index().is_some().

Implementations

impl ParamSchema

pub fn required( name: impl Into<String>, param_type: impl Into<String>, description: impl Into<String>, ) -> ParamSchema

Create a required parameter.

pub fn optional( name: impl Into<String>, param_type: impl Into<String>, default: Value, description: impl Into<String>, ) -> ParamSchema

Create an optional parameter with a default value.

pub fn new( name: impl Into<String>, param_type: impl Into<String>, ) -> ParamSchema

Create a minimal parameter (not required, no default, empty description, consumes 1, flag — not positional). Chain the with_* setters to fill in fields. Use this when each field is computed independently (e.g. reflected from clap) rather than fitting the required/optional shortcuts. Keeps construction working across the #[non_exhaustive] boundary.

pub fn with_description(self, description: impl Into<String>) -> ParamSchema

Set the human-readable description.

pub fn with_required(self, required: bool) -> ParamSchema

Set whether the parameter is required.

pub fn with_default(self, default: Option<Value>) -> ParamSchema

Set the default value (used when the parameter is omitted).

pub fn with_positional(self, positional: bool) -> ParamSchema

Set the positional flag from a computed boolean (the parameterless positional sets it unconditionally to true).

pub fn positional(self) -> ParamSchema

Mark this parameter as positional (matched by argv order rather than by name). Used by params_from_clap for clap args with an assigned index, and by hand-written schemas for positional parameters like jq’s filter.

pub fn with_aliases( self, aliases: impl IntoIterator<Item = impl Into<String>>, ) -> ParamSchema

Add alternative names/flags for this parameter.

Aliases are used for short flags like -r, -R that map to recursive.

pub fn consumes(self, n: usize) -> ParamSchema

Declare how many positional tokens this non-bool flag consumes per occurrence (--flag v1 v2 ...). Default is 1. Panics on 0 — a flag that consumes nothing is a bool flag, not a schema-typed param.

pub fn with_repeatable(self, repeatable: bool) -> ParamSchema

Mark this flag as repeatable: each occurrence is accumulated rather than overwritten (see repeatable). Set from a computed boolean so clap reflection can pass ArgAction::Append directly.

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

Check if a flag name matches this parameter or any of its aliases.

Trait Implementations

impl Clone for ParamSchema

fn clone(&self) -> ParamSchema

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ParamSchema

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ParamSchema

fn deserialize<__D>( __deserializer: __D, ) -> Result<ParamSchema, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ParamSchema

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

where __S: Serializer,

Serialize this value into the given Serde serializer.