xcli

func (ArrayDescriptor[T]) ParseAndValidate ¶

func (ad ArrayDescriptor[T]) ParseAndValidate(flag string, raw string, spec xclistruc.Flag) (any, error)

ParseAndValidate orchestrates JSON matrix deserialization over array flag inputs.

It decodes structured terminal string blocks using native encoding capabilities, validates total collection capacities metrics, and iteratively executes multi-layered domain limits and physical validation restrictions hooks over every deserialized item instance.

Arguments:

• flag: The command line flag identifier label causing the failure (e.g., "--ids").
• raw: The raw unparsed text payload extracted from the command arguments collection.
• spec: The complete core flag layout containing the validation metadata guidelines.

Returns:

• any: The fully converted, type-safe native Go slice matching the target element layout ([]T).
• error: Returns an xerrors.IErrorCLI capturing visual telemetry diagnostics if any rule fails.

Error & Panic Natures:

• Complex Errors: Fails early if the raw input structure violates strict JSON formatting guidelines. Evaluates high-level collection capacity boundary lengths via custom helpers. Iterates over deserialized items, throwing formatted CLI errors if an item-level constraint or a physical disk permission assertion fails evaluation targets.

func (ArrayDescriptor[T]) ValidateCapacity ¶

func (ad ArrayDescriptor[T]) ValidateCapacity(flag string, total int, spec xclistruc.Flag) error

validateCapacity enforces slice size limits against spec guidelines without reflection.

It delegates collection item metrics checking directly to the specialized core validation package layers to isolate error visual formatting structures.

Arguments:

• flag: The command line flag identifier label causing the failure (e.g., "--ids").
• total: The total number of items parsed and identified inside the active slice collection.
• spec: The complete core flag layout containing the validation metadata guidelines.

Returns:

• error: Returns an xerrors.IErrorCLI if the count violates configured boundaries.

Error & Panic Natures:

• Complex Errors: Routes length counters down to the package validation infrastructure, triggering a multi-line visual terminal error layout if minItems or maxItems are violated.

func (*Command) TriggerHelp ¶

func (c *Command) TriggerHelp() error

TriggerHelp intercepts the flow and renders the automatic command documentation.

It evaluates operational descriptions metadata fields and directly serializes aligned visual tables mapping usage definitions, child subcommands, and flags guidelines to standard stdout tracks.

Returns:

• error: Returns a structured error tracking instance if writing stdout triggers telemetry blocks.

func (*Command) ValidateAndHydrateFlags ¶

func (c *Command) ValidateAndHydrateFlags(
	rawFlags map[string]string,
) (
	*xclistruc.FlagValues,
	error,
)

ValidateAndHydrateFlags loops through registered constraints performing types translation and bounds enforcement.

It checks flag mandatory presence, injects fallback defaults allocation blocks, and leverages the package-level central registry directory to resolve runtime type translations dynamically.

Arguments:

• rawFlags: The extracted command line layout map pairing flag strings to text values.

Returns:

• *xclistruc.FlagValues: A populated type-safe context directory containing translated Go instances.
• error: Returns an xerrors.IErrorCLI capturing visual telemetry diagnostics if any validation path fails.

Error & Panic Natures:

• Complex Errors: Fails immediately if a required token is missing from raw inputs. Queries the global type registry throwing errors if a type metadata token is unmapped. Performs zombie variable tracking blocks, failing if unregistered flag tokens are found.

func (*Router) Run ¶

func (r *Router) Run(rawArgs []string) error

Run reads the raw terminal arguments, resolves the command path, validates the flags, checks for help triggers, and executes the final command hook.

Arguments:

• rawArgs: The slice of strings representing terminal inputs (usually os.Args[1:]).

Returns:

• error: Returns an xerrors.IErrorCLI if a command is not found or flag parsing/validation fails.

func (TypedDescriptor[T]) ParseAndValidate ¶

func (td TypedDescriptor[T]) ParseAndValidate(
	flag string,
	raw string,
	spec xclistruc.Flag,
) (any, error)

ParseAndValidate orchestrates the complete strongly-typed pipeline for single terminal values.

It handles primitive mapping, standard constraint limits enforcement, and specialized physical file system privilege validation tracks using compile-time type dispatch.

Arguments:

• flag: The command line flag identifier label causing the failure (e.g., "--output").
• raw: The raw unparsed text payload extracted from the command arguments collection.
• spec: The complete core flag layout containing the validation metadata guidelines.

Returns:

• any: The fully converted, type-safe native Go primitive instance.
• error: Returns an xerrors.IErrorCLI capturing visual telemetry diagnostics if any rule fails.

Error & Panic Natures:

• Complex Errors: Evaluates sequential pipeline layers. Fails early if the core type parser throws an execution blocker. Sequentially triggers LimitValidator and DiskValidator bounds hooks only if they are actively configured inside the global registration matrix.