cli

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: MIT Imports: 14 Imported by: 0

README

Nagi CLI for Go

日本語

Nagi CLI for Go provides a native command-application framework with a validated Command Graph, typed values, injected process services, structured Help and Diagnostics, and policy-controlled Exit Status

It uses Nagi Text for terminal-Cell-aware help alignment and does not depend on Nagi Surface or Nagi TUI

Requirements

  • Go 1.25 or newer
  • Linux or macOS on x86-64 or ARM64 for process integration

Installation

go get github.com/mayahiro/nagicli-go@latest

Quick start

Run the basic command example:

go run ./examples/basic Nagi

Capabilities

  • Local and explicitly inherited long, short, clustered, repeated, required, defaulted, and environment-backed options
  • Positional arguments, nested subcommands, aliases, and -- termination
  • Raw byte strings, UTF-8 strings, signed 64-bit integers, finite values, and custom typed parsers
  • Source-aware option relations, four portable option-group rules, and typed Invocation validators
  • Command-local value IDs, exact stable-ID scopes, and fallible required typed access
  • Generic Hidden and Deprecated command and option lifecycle metadata with structured notices
  • Generic Sensitive Value metadata with Help, Diagnostic, formatting, and completion redaction
  • Application-owned Value Source adapters with fixed command-line, environment, external, and default precedence
  • Opt-in bounded Response File expansion with injected file reads and optional standard input
  • Structured deterministic Help, controllable subcommand Usage Variants, custom sections, whole-graph traversal, optional Markdown and man renderers, and help [COMMAND...]
  • Stable Diagnostic codes, categories, value targets, and hints with plain or stable JSON rendering and configurable exit-code mapping
  • Injected stdin, stdout, stderr, environment, current directory, and context.Context cancellation
  • Parser-first dispatch and parsed-Invocation execution for command-by-command adoption
  • Immutable handler-free completion resolution, dynamic providers, and Bash, Zsh, Fish, and PowerShell generators
  • Optional line-oriented Confirm, Select, Input, and Secret prompts with injected I/O
  • Optional synchronous TTY status, spinner, progress, and plain-log fallback with injected I/O
  • Process-free application tests through package clitest

The shared CLI semantics define the observable contract and Rust parity. The public CLI API guide explains inherited options, command-local scopes, Value Source adapters, Response Files, completion, Help presentation, lifecycle and Sensitive Value metadata, structured validators, and staged adoption

Testing applications

Package clitest injects process inputs and captures status and output without starting a process or installing signal handlers. The basic example includes an executable application test

go test ./examples/basic

Examples

Example Command
Basic command go run ./examples/basic Nagi
Nested subcommands go run ./examples/subcommands start -vv
Staged adoption go run ./examples/staged inspect page
JSON Diagnostic go run ./examples/json-diagnostic
Command lifecycle go run ./examples/lifecycle --legacy old
Sensitive Value go run ./examples/sensitive-values --token demo-token
Value Source Adapter go run ./examples/value-sources
Response File go run ./examples/response-files @examples/response-files/arguments.txt
Derived Help documents go run ./examples/documentation markdown
Shell completion go run ./examples/completion generate bash
Lightweight prompts go run ./examples/prompt
TTY-aware status go run ./examples/status

All examples are included in go build ./...

Limitations

Shell-specific generation, derived Help documents, line-oriented Prompt, and synchronous Status Reporter are optional, and applications own completion installation, dynamic candidate I/O, credential handling, approval policy, status timing, and progress meaning. Sensitive Value metadata redacts framework projections but does not zeroize memory or hide process arguments from the operating system or shell history. Already loaded configuration can be mapped through a Value Resolver, but configuration-file loading and CLI-to-TUI integration are not provided. Response Files are disabled unless explicitly enabled and use Nagi's bounded tokenizer rather than a shell; they do not expand variables, globs, tildes, or environment values. Long-running handlers and completion providers must poll the injected cancellation context cooperatively. The portable graph does not model arbitrary invocation grammars. Help-only Usage Variants can document validator-backed forms without changing parser semantics

License

Source code is available under the MIT License

Documentation

Overview

Package cli provides a validated command graph, scoped typed Invocations, structured Help and Diagnostics, and an injected policy-controlled runtime for native Go command applications.

Options are local unless Inherited makes them visible in selected descendants. Every value remains in its declaration scope. Parent and child Commands may reuse local value IDs. Invocation access starts at a documented current scope, while Scope selects one exact stable command-ID path. RequireValueAs provides fallible schema-required typed access.

Help-only Usage Variants and SubcommandUsage control presentation without changing parsing. InvocationValidator returns a structured Diagnostic with application codes, option or argument targets, and remediation hints. VisitHelpDocuments validates once and streams structured Help for every visible command. Package document owns optional deterministic Markdown and man rendering.

OptionSpec.Sensitive and Argument.Sensitive attach generic presentation metadata. Framework Help, parser Diagnostics, formatting, and completion redact or suppress those values while explicit Invocation access preserves the original raw and typed data.

ValueResolver adapts already loaded application configuration into selected Value Option fallbacks without giving Nagi ownership of its schema or I/O. Fixed precedence remains command line, environment, external resolver, then command-definition default.

ExpandResponseFiles provides an opt-in, resource-bounded lexical layer for @file arguments without shell, variable, glob, tilde, or environment expansion. Ordinary parser and runtime entry points preserve leading @ literally unless Response Files are enabled through Context or ProcessOptions.

CompletionEngine snapshots the validated graph without handlers and resolves static candidates plus only the active Option or Argument provider. Package completion owns shell-specific generation and its reserved protocol.

Parse, RunParsedWithPolicy, RunInvocationWithPolicy, and RuntimePolicy's pure rendering and status helpers support command-by-command adoption in an existing CLI. RunProcess remains the complete process integration.

Index

Constants

View Source 
const JSONDiagnosticSchema = "nagi.cli.diagnostic.v1"

JSONDiagnosticSchema is the stable schema identifier emitted by JSONDiagnosticRenderer

View Source 
const RedactedValue = "<redacted>"

RedactedValue is the stable marker used when a framework projection hides a Sensitive value

Variables

This section is empty.

Functions

func ExpandResponseFiles added in v0.4.0 

func ExpandResponseFiles(
	arguments []string,
	baseDirectory string,
	options ResponseFileOptions,
	reader ResponseFileReader,
	standardInput io.Reader,
) ([]string, error)

ExpandResponseFiles expands opt-in @file arguments through injected file and standard-input readers

Expansion is independent of a Command Graph. Returned strings retain their platform bytes and can be passed to Command.Parse or Command.Run

func ValueAs 

func ValueAs[T any](values ValueLookup, id string) (T, bool)

ValueAs returns the first parser result when its dynamic type is T

Types

type Argument 

type Argument struct {
	// contains filtered or unexported fields
}

Argument defines one positional command value

func Positional 

func Positional(id string) *Argument

Positional constructs a raw platform-value positional argument

func (*Argument) CompletionProvider added in v0.4.0 

func (a *Argument) CompletionProvider(provider CompletionProvider) *Argument

CompletionProvider sets the dynamic completion provider for this positional argument

The provider is only called while this argument is the active completion target. Parsing and handler execution never call it

func (Argument) Format added in v0.4.0 

func (a Argument) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing parser or provider state

func (*Argument) Help 

func (a *Argument) Help(help string) *Argument

Help sets the positional description

func (*Argument) ID 

func (a *Argument) ID() string

ID returns the stable value identifier

func (*Argument) IsSensitive added in v0.4.0 

func (a *Argument) IsSensitive() bool

IsSensitive reports whether this positional value requires redaction in framework-controlled projections

func (*Argument) Parser 

func (a *Argument) Parser(parser ValueParser) *Argument

Parser sets the typed Value Parser

func (*Argument) Repeated 

func (a *Argument) Repeated() *Argument

Repeated allows this final positional to consume remaining values

func (*Argument) Required 

func (a *Argument) Required() *Argument

Required requires this positional argument

func (*Argument) Sensitive added in v0.4.0 

func (a *Argument) Sensitive() *Argument

Sensitive marks this positional value for redaction in framework-controlled Help, Diagnostic, formatting, and completion projections

Parsing and explicit raw or typed value access remain unchanged

type Command 

type Command struct {
	// contains filtered or unexported fields
}

Command is one validated node in a Command Graph

func NewCommand 

func NewCommand(name string) *Command

NewCommand constructs a command whose stable ID matches its name

func (*Command) About 

func (c *Command) About(about string) *Command

About sets the short command description

func (*Command) Alias 

func (c *Command) Alias(alias string) *Command

Alias adds one child-command spelling

func (*Command) Argument 

func (c *Command) Argument(argument *Argument) *Command

Argument appends a positional in consumption order

func (*Command) Deprecated added in v0.4.0 

func (c *Command) Deprecated(replacement string) *Command

Deprecated marks this command deprecated with an application-provided replacement hint while preserving parsing and handler execution

func (*Command) Deprecation added in v0.4.0 

func (c *Command) Deprecation() (Deprecation, bool)

Deprecation returns replacement metadata when this command is deprecated

func (*Command) Description 

func (c *Command) Description() string

Description returns the short description

func (*Command) Example added in v0.3.0 

func (c *Command) Example(name, invocation string) *Command

Example appends one named command-line example

func (Command) Format added in v0.4.0 

func (c Command) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without recursively exposing Command Graph values, parsers, providers, validators, or handlers

func (*Command) Handle 

func (c *Command) Handle(handler Handler) *Command

Handle sets the language-native command handler

func (*Command) HelpDocument added in v0.3.0 

func (c *Command) HelpDocument(path []string) (HelpDocument, error)

HelpDocument returns structured Help for a canonical command path

func (*Command) HelpSection added in v0.3.0 

func (c *Command) HelpSection(section *HelpSection) *Command

HelpSection appends one application-defined structured Help section

func (*Command) Hidden added in v0.4.0 

func (c *Command) Hidden() *Command

Hidden omits this command from parent Help, completion, and derived documentation while preserving explicit selection and direct Help

func (*Command) ID 

func (c *Command) ID(id string) *Command

ID sets the stable identity independently of the command name

func (*Command) IsHidden added in v0.4.0 

func (c *Command) IsHidden() bool

IsHidden reports whether this command is omitted from parent projections 

func (c *Command) Link(label, url string) *Command

Link appends one labeled documentation link

func (*Command) Name 

func (c *Command) Name() string

Name returns the canonical command name

func (*Command) Note added in v0.3.0 

func (c *Command) Note(note string) *Command

Note appends one structured Help note

func (*Command) Option 

func (c *Command) Option(option *OptionSpec) *Command

Option appends an option in help-definition order

func (*Command) OptionGroup added in v0.3.0 

func (c *Command) OptionGroup(group *OptionGroup) *Command

OptionGroup appends one portable option-group constraint

func (*Command) Parse 

func (c *Command) Parse(arguments []string) (ParseResult, error)

Parse parses arguments after the program name with an empty environment

func (*Command) ParseWithEnvironment 

func (c *Command) ParseWithEnvironment(arguments []string, environment map[string]string) (ParseResult, error)

ParseWithEnvironment parses argv and injected environment values

func (*Command) ParseWithValueResolver added in v0.4.0 

func (c *Command) ParseWithValueResolver(
	arguments []string,
	environment map[string]string,
	resolver ValueResolver,
) (ParseResult, error)

ParseWithValueResolver parses argv, environment, and application-owned fallbacks

The resolver is called only for selected Value Options that have no command-line or environment value. A nil resolver behaves like ParseWithEnvironment

func (*Command) RenderHelp 

func (c *Command) RenderHelp(path []string) (string, error)

RenderHelp renders standard Help for a canonical command path

func (*Command) RequireSubcommand 

func (c *Command) RequireSubcommand() *Command

RequireSubcommand requires one child command to be selected

func (*Command) Run 

func (c *Command) Run(context *Context, arguments []string) (Outcome, error)

Run parses and executes arguments through an injected Context

func (*Command) RunInvocation added in v0.3.2 

func (c *Command) RunInvocation(
	context *Context,
	invocation *Invocation,
) (Outcome, error)

RunInvocation executes one Invocation validated by this Command Graph

An Invocation whose canonical or stable command path does not identify the same graph is rejected

func (*Command) RunInvocationWithPolicy added in v0.3.2 

func (c *Command) RunInvocationWithPolicy(
	context *Context,
	invocation *Invocation,
	policy RuntimePolicy,
) (Outcome, error)

RunInvocationWithPolicy executes one Invocation validated by this Command Graph through a policy

An Invocation whose canonical or stable command path does not identify the same graph is rejected

func (*Command) RunParsed added in v0.3.2 

func (c *Command) RunParsed(context *Context, result ParseResult) (Outcome, error)

RunParsed executes a result parsed by this Command Graph through the default policy

func (*Command) RunParsedWithPolicy added in v0.3.2 

func (c *Command) RunParsedWithPolicy(
	context *Context,
	result ParseResult,
	policy RuntimePolicy,
) (Outcome, error)

RunParsedWithPolicy executes a result parsed by this Command Graph through a policy

This is the staged-adoption bridge between parser-only dispatch and Nagi Help, version, or registered Handler execution. A result whose canonical or stable path does not identify the same graph is rejected

func (*Command) RunProcess 

func (c *Command) RunProcess() (ExitStatus, error)

RunProcess executes this command against the current process and returns its status

func (*Command) RunProcessWithOptions added in v0.4.0 

func (c *Command) RunProcessWithOptions(options ProcessOptions) (ExitStatus, error)

RunProcessWithOptions executes this command against the current process with composable Runtime, Value Resolver, and Response File options

func (*Command) RunProcessWithPolicy added in v0.3.0 

func (c *Command) RunProcessWithPolicy(policy RuntimePolicy) (ExitStatus, error)

RunProcessWithPolicy executes this command with an explicit Runtime Policy

func (*Command) RunProcessWithPolicyAndValueResolver added in v0.4.0 

func (c *Command) RunProcessWithPolicyAndValueResolver(
	policy RuntimePolicy,
	resolver ValueResolver,
) (ExitStatus, error)

RunProcessWithPolicyAndValueResolver executes this command against the current process with an explicit Runtime Policy and Value Resolver

func (*Command) RunProcessWithValueResolver added in v0.4.0 

func (c *Command) RunProcessWithValueResolver(resolver ValueResolver) (ExitStatus, error)

RunProcessWithValueResolver executes this command against the current process with an application-owned Value Resolver

func (*Command) RunWithPolicy added in v0.3.0 

func (c *Command) RunWithPolicy(
	context *Context,
	arguments []string,
	policy RuntimePolicy,
) (Outcome, error)

RunWithPolicy parses and executes arguments through an explicit Runtime Policy

func (*Command) StableID 

func (c *Command) StableID() string

StableID returns the command identity

func (*Command) Subcommand 

func (c *Command) Subcommand(command *Command) *Command

Subcommand appends a child command in help-definition order

func (*Command) SubcommandUsage added in v0.3.2 

func (c *Command) SubcommandUsage(mode SubcommandUsageMode) *Command

SubcommandUsage selects generic, hidden, or expanded child usage in Help

It changes Help presentation only and does not change parsing, validation, Diagnostics, or Invocation values

func (*Command) UsageVariant added in v0.3.1 

func (c *Command) UsageVariant(id, syntax string) *Command

UsageVariant appends one Help-only invocation syntax with a stable ID

The syntax is a non-empty suffix relative to the canonical command path and does not change argv parsing, Invocation validation, Diagnostic usage, or Invocation values

func (*Command) Validate 

func (c *Command) Validate() error

Validate checks the entire Command Graph before argv is consumed

func (*Command) Validator added in v0.3.0 

func (c *Command) Validator(validator InvocationValidator) *Command

Validator appends one language-native typed Invocation validator

func (*Command) Version 

func (c *Command) Version(version string) *Command

Version sets the root version used by the built-in version action

func (*Command) VisitHelpDocuments added in v0.4.0 

func (c *Command) VisitHelpDocuments(visitor func(HelpDocument) bool) error

VisitHelpDocuments visits visible commands in definition-order preorder

The graph is validated once before the first callback. The root is visited first, hidden command subtrees are omitted, and returning false stops traversal successfully. The Command Graph must not be mutated while this synchronous traversal is active. A nil visitor returns an Invalid Specification Diagnostic.

type CompletionCandidate added in v0.4.0 

type CompletionCandidate struct {
	// contains filtered or unexported fields
}

CompletionCandidate is one portable completion candidate

func NewCompletionCandidate added in v0.4.0 

func NewCompletionCandidate(value string) CompletionCandidate

NewCompletionCandidate constructs a Value candidate that appends a space when selected

func (CompletionCandidate) AppendSpace added in v0.4.0 

func (c CompletionCandidate) AppendSpace() bool

AppendSpace reports whether adapters should append a space after insertion

func (CompletionCandidate) Deprecation added in v0.4.0 

func (c CompletionCandidate) Deprecation() (Deprecation, bool)

Deprecation returns replacement metadata for a deprecated static candidate

func (CompletionCandidate) Description added in v0.4.0 

func (c CompletionCandidate) Description() string

Description returns the optional short description

func (CompletionCandidate) DisplayLabel added in v0.4.0 

func (c CompletionCandidate) DisplayLabel() string

DisplayLabel returns the display label, defaulting to the inserted value

func (CompletionCandidate) Kind added in v0.4.0 

func (c CompletionCandidate) Kind() CompletionCandidateKind

Kind returns the semantic candidate kind

func (CompletionCandidate) Value added in v0.4.0 

func (c CompletionCandidate) Value() string

Value returns the complete text inserted for this candidate

func (CompletionCandidate) WithAppendSpace added in v0.4.0 

func (c CompletionCandidate) WithAppendSpace(appendSpace bool) CompletionCandidate

WithAppendSpace controls whether adapters append a space after this candidate

func (CompletionCandidate) WithDescription added in v0.4.0 

func (c CompletionCandidate) WithDescription(description string) CompletionCandidate

WithDescription sets a short human-readable candidate description

An empty description is treated as absent

func (CompletionCandidate) WithDisplayLabel added in v0.4.0 

func (c CompletionCandidate) WithDisplayLabel(label string) CompletionCandidate

WithDisplayLabel sets text displayed separately from the inserted value

An empty label restores the inserted value as the display label

func (CompletionCandidate) WithKind added in v0.4.0 

func (c CompletionCandidate) WithKind(kind CompletionCandidateKind) CompletionCandidate

WithKind sets the semantic candidate kind

type CompletionCandidateKind added in v0.4.0 

type CompletionCandidateKind uint8

CompletionCandidateKind classifies a candidate for presentation adapters 

const (
	// CompletionCandidateCommand identifies a child command name or alias
	CompletionCandidateCommand CompletionCandidateKind = iota
	// CompletionCandidateOption identifies a long or short option spelling
	CompletionCandidateOption
	// CompletionCandidateValue identifies an option or positional value
	CompletionCandidateValue
)

type CompletionEngine added in v0.4.0 

type CompletionEngine struct {
	// contains filtered or unexported fields
}

CompletionEngine is an immutable handler-free projection of a validated Command Graph

func NewCompletionEngine added in v0.4.0 

func NewCompletionEngine(command *Command) (*CompletionEngine, error)

NewCompletionEngine validates and snapshots a Command Graph for repeated requests

func (*CompletionEngine) Complete added in v0.4.0 

func (e *CompletionEngine) Complete(ctx context.Context, input CompletionInput) (CompletionResult, error)

Complete resolves static candidates and only the active target's dynamic provider

It does not run Value Parsers, fallbacks, validators, or handlers

func (*CompletionEngine) RootName added in v0.4.0 

func (e *CompletionEngine) RootName() string

RootName returns the canonical program name used by shell generators

type CompletionError added in v0.4.0 

type CompletionError struct {
	// contains filtered or unexported fields
}

CompletionError is a completion-specific failure separate from parsing and handlers

func (*CompletionError) Error added in v0.4.0 

func (e *CompletionError) Error() string

Error implements error

func (*CompletionError) Kind added in v0.4.0 

func (e *CompletionError) Kind() CompletionErrorKind

Kind returns the failure category

func (*CompletionError) Message added in v0.4.0 

func (e *CompletionError) Message() string

Message returns the human-readable failure message

func (*CompletionError) Target added in v0.4.0 

func (e *CompletionError) Target() (CompletionTarget, bool)

Target returns the active target when resolution reached one

func (*CompletionError) Unwrap added in v0.4.0 

func (e *CompletionError) Unwrap() error

Unwrap exposes provider or context cancellation causes

type CompletionErrorKind added in v0.4.0 

type CompletionErrorKind uint8

CompletionErrorKind classifies a completion resolution failure 

const (
	// CompletionErrorCancelled means cancellation occurred before completion finished
	CompletionErrorCancelled CompletionErrorKind = iota
	// CompletionErrorProvider means the active dynamic provider returned an error
	CompletionErrorProvider
	// CompletionErrorInvalidCandidate means a candidate is unsafe for shell adapters
	CompletionErrorInvalidCandidate
)

type CompletionInput added in v0.4.0 

type CompletionInput struct {
	// contains filtered or unexported fields
}

CompletionInput is tokenized shell input for one completion request

func NewCompletionInput added in v0.4.0 

func NewCompletionInput(arguments []string, current string) CompletionInput

NewCompletionInput constructs input from completed arguments and the token prefix at the cursor

Arguments exclude the program name and the current token

func (CompletionInput) Arguments added in v0.4.0 

func (i CompletionInput) Arguments() []string

Arguments returns completed arguments before the token at the cursor

func (CompletionInput) Current added in v0.4.0 

func (i CompletionInput) Current() string

Current returns the token prefix at the cursor

func (CompletionInput) Format added in v0.4.0 

func (i CompletionInput) Format(state fmt.State, _ rune)

Format implements fmt.Formatter while treating every raw shell token as opaque because Completion Input has no Command Graph metadata

type CompletionOccurrence added in v0.4.0 

type CompletionOccurrence struct {
	// contains filtered or unexported fields
}

CompletionOccurrence is one recognized raw occurrence before the active token

func (CompletionOccurrence) Format added in v0.4.0 

func (o CompletionOccurrence) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing a Sensitive occurrence

func (CompletionOccurrence) Kind added in v0.4.0 

func (o CompletionOccurrence) Kind() CompletionOccurrenceKind

Kind returns whether this occurrence is a Flag, Count, or raw Value

func (CompletionOccurrence) Raw added in v0.4.0 

func (o CompletionOccurrence) Raw() (string, bool)

Raw returns the raw value for Value occurrences

func (CompletionOccurrence) Target added in v0.4.0 

func (o CompletionOccurrence) Target() CompletionTarget

Target returns the stable option or argument target

type CompletionOccurrenceKind added in v0.4.0 

type CompletionOccurrenceKind uint8

CompletionOccurrenceKind identifies how one partial argv occurrence was represented 

const (
	// CompletionOccurrenceFlag identifies a Boolean Flag option occurrence
	CompletionOccurrenceFlag CompletionOccurrenceKind = iota
	// CompletionOccurrenceCount identifies a Count option occurrence
	CompletionOccurrenceCount
	// CompletionOccurrenceValue identifies a Value option or positional occurrence
	CompletionOccurrenceValue
)

type CompletionProvider added in v0.4.0 

type CompletionProvider func(context.Context, CompletionRequest) ([]CompletionCandidate, error)

CompletionProvider supplies runtime candidates for one active Option or Argument target

type CompletionRequest added in v0.4.0 

type CompletionRequest struct {
	// contains filtered or unexported fields
}

CompletionRequest is one normalized request passed to a dynamic provider

func (CompletionRequest) Arguments added in v0.4.0 

func (r CompletionRequest) Arguments() []string

Arguments returns completed arguments exactly as supplied by the shell adapter

func (CompletionRequest) CommandIDPath added in v0.4.0 

func (r CompletionRequest) CommandIDPath() []string

CommandIDPath returns the selected stable command-ID path

func (CompletionRequest) CommandPath added in v0.4.0 

func (r CompletionRequest) CommandPath() []string

CommandPath returns the selected canonical command path

func (CompletionRequest) Current added in v0.4.0 

func (r CompletionRequest) Current() string

Current returns the complete token prefix at the cursor

func (CompletionRequest) Format added in v0.4.0 

func (r CompletionRequest) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing Sensitive or unclassified shell input

func (CompletionRequest) PartialOccurrences added in v0.4.0 

func (r CompletionRequest) PartialOccurrences() []CompletionOccurrence

PartialOccurrences returns recognized argv occurrences in original order

Completion does not run Value Parsers, fallbacks, or validators

func (CompletionRequest) Prefix added in v0.4.0 

func (r CompletionRequest) Prefix() string

Prefix returns the target-local prefix being completed

Attached long and short option syntax is removed from this prefix

func (CompletionRequest) Target added in v0.4.0 

func (r CompletionRequest) Target() CompletionTarget

Target returns the active completion target

type CompletionResult added in v0.4.0 

type CompletionResult struct {
	// contains filtered or unexported fields
}

CompletionResult contains the normalized request and deterministic candidates

func (CompletionResult) Candidates added in v0.4.0 

func (r CompletionResult) Candidates() []CompletionCandidate

Candidates returns candidates in deterministic source order

func (CompletionResult) Format added in v0.4.0 

func (r CompletionResult) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing request input or candidate values

func (CompletionResult) Request added in v0.4.0 

func (r CompletionResult) Request() CompletionRequest

Request returns the normalized request used for static and dynamic candidates

type CompletionTarget added in v0.4.0 

type CompletionTarget struct {
	// contains filtered or unexported fields
}

CompletionTarget identifies one target by stable Command Graph identity

func (CompletionTarget) CommandIDPath added in v0.4.0 

func (t CompletionTarget) CommandIDPath() []string

CommandIDPath returns the stable path of the command that owns this target

func (CompletionTarget) IsSensitive added in v0.4.0 

func (t CompletionTarget) IsSensitive() bool

IsSensitive reports whether the active value declaration is Sensitive

func (CompletionTarget) Kind added in v0.4.0 

func (t CompletionTarget) Kind() CompletionTargetKind

Kind returns the target category

func (CompletionTarget) ValueID added in v0.4.0 

func (t CompletionTarget) ValueID() string

ValueID returns the command-local value ID for an Option or Argument target

type CompletionTargetKind added in v0.4.0 

type CompletionTargetKind uint8

CompletionTargetKind identifies the syntax target being completed 

const (
	// CompletionTargetCommand identifies child-command or command-level syntax
	CompletionTargetCommand CompletionTargetKind = iota
	// CompletionTargetOption identifies a named option value
	CompletionTargetOption
	// CompletionTargetArgument identifies a positional argument value
	CompletionTargetArgument
)

type Context 

type Context struct {
	// contains filtered or unexported fields
}

Context contains the process services injected into a command handler

func NewContext 

func NewContext(
	stdin io.Reader,
	stdout io.Writer,
	stderr io.Writer,
	environment map[string]string,
	currentDirectory string,
) *Context

NewContext constructs an injected Context without cancellation

func NewContextWithCancellation 

func NewContextWithCancellation(
	stdin io.Reader,
	stdout io.Writer,
	stderr io.Writer,
	environment map[string]string,
	currentDirectory string,
	cancellation stdcontext.Context,
) *Context

NewContextWithCancellation constructs an injected Context with an explicit cancellation source

func (*Context) Cancellation 

func (c *Context) Cancellation() stdcontext.Context

Cancellation returns the cooperative cancellation source

func (*Context) CurrentDirectory 

func (c *Context) CurrentDirectory() string

CurrentDirectory returns the injected current directory

func (*Context) Environment 

func (c *Context) Environment(name string) (string, bool)

Environment returns one injected environment value

func (*Context) EnvironmentValues 

func (c *Context) EnvironmentValues() map[string]string

EnvironmentValues returns a copy of the injected environment

func (*Context) ResponseFileOptions added in v0.4.0 

func (c *Context) ResponseFileOptions() (ResponseFileOptions, bool)

ResponseFileOptions returns configured options and whether expansion is enabled

func (*Context) Stderr 

func (c *Context) Stderr() io.Writer

Stderr returns standard error access

func (*Context) Stdin 

func (c *Context) Stdin() io.Reader

Stdin returns standard input access

func (*Context) Stdout 

func (c *Context) Stdout() io.Writer

Stdout returns standard output access

func (*Context) ValueResolver added in v0.4.0 

func (c *Context) ValueResolver() ValueResolver

ValueResolver returns the configured application Value Resolver

func (*Context) WithResponseFiles added in v0.4.0 

func (c *Context) WithResponseFiles(
	options ResponseFileOptions,
	reader ResponseFileReader,
) *Context

WithResponseFiles configures opt-in Response File expansion

Exact @- expansion, when enabled in options, consumes this Context's standard input. A nil reader supports standard-input-only expansion; a file include then returns an invalid-specification Diagnostic

func (*Context) WithValueResolver added in v0.4.0 

func (c *Context) WithValueResolver(resolver ValueResolver) *Context

WithValueResolver configures an application-owned Value Resolver

The resolver receives only selected Value Options that remain unresolved after command-line and environment processing. A nil resolver clears it

func (*Context) WithoutResponseFiles added in v0.4.0 

func (c *Context) WithoutResponseFiles() *Context

WithoutResponseFiles disables Response File expansion

type Deprecation added in v0.4.0 

type Deprecation struct {
	// contains filtered or unexported fields
}

Deprecation contains replacement metadata for a deprecated Command or Option

func (Deprecation) Replacement added in v0.4.0 

func (d Deprecation) Replacement() string

Replacement returns the application-provided replacement hint

type DeprecationNotice added in v0.4.0 

type DeprecationNotice struct {
	// contains filtered or unexported fields
}

DeprecationNotice is one non-fatal use of deprecated Command Graph syntax

func (DeprecationNotice) CommandIDPath added in v0.4.0 

func (n DeprecationNotice) CommandIDPath() []string

CommandIDPath returns a copy of the stable path of the target declaration

func (DeprecationNotice) CommandPath added in v0.4.0 

func (n DeprecationNotice) CommandPath() []string

CommandPath returns a copy of the canonical selected path when the syntax was used

func (DeprecationNotice) Replacement added in v0.4.0 

func (n DeprecationNotice) Replacement() string

Replacement returns the application-provided replacement hint

func (DeprecationNotice) Spelling added in v0.4.0 

func (n DeprecationNotice) Spelling() string

Spelling returns the recognized argv spelling, or the canonical root name when the root Command itself is deprecated

func (DeprecationNotice) TargetKind added in v0.4.0 

func (n DeprecationNotice) TargetKind() DeprecationTargetKind

TargetKind returns whether this notice identifies a Command or Option

func (DeprecationNotice) ValueID added in v0.4.0 

func (n DeprecationNotice) ValueID() string

ValueID returns the command-local option ID for an Option notice

type DeprecationNoticeRenderer added in v0.4.0 

type DeprecationNoticeRenderer interface {
	// RenderDeprecationNotice returns text with one final newline
	RenderDeprecationNotice(notice DeprecationNotice) string
}

DeprecationNoticeRenderer renders one non-fatal deprecation notice

type DeprecationTargetKind added in v0.4.0 

type DeprecationTargetKind uint8

DeprecationTargetKind identifies whether a notice targets a Command or Option 

const (
	// DeprecationTargetCommand identifies a selected deprecated Command
	DeprecationTargetCommand DeprecationTargetKind = iota
	// DeprecationTargetOption identifies a deprecated command-line Option
	DeprecationTargetOption
)

type Diagnostic 

type Diagnostic struct {
	// contains filtered or unexported fields
}

Diagnostic is a structured definition, parser, or handler failure

func NewDiagnostic 

func NewDiagnostic(code DiagnosticCode, message string) *Diagnostic

NewDiagnostic constructs a Diagnostic with the semantic category for its code

func (*Diagnostic) Category added in v0.3.0 

func (d *Diagnostic) Category() DiagnosticCategory

Category returns the semantic failure category

func (*Diagnostic) Code 

func (d *Diagnostic) Code() DiagnosticCode

Code returns the stable diagnostic code

func (*Diagnostic) CommandPath 

func (d *Diagnostic) CommandPath() []string

CommandPath returns a copy of the canonical command path

func (*Diagnostic) Error 

func (d *Diagnostic) Error() string

Error implements error without a trailing newline

func (*Diagnostic) Hints added in v0.3.2 

func (d *Diagnostic) Hints() []string

Hints returns human-readable remediation hints in insertion order

func (*Diagnostic) Message 

func (d *Diagnostic) Message() string

Message returns the human-readable message

func (*Diagnostic) Render 

func (d *Diagnostic) Render() string

Render returns deterministic plain text with one final newline

func (*Diagnostic) Targets added in v0.3.2 

func (d *Diagnostic) Targets() []DiagnosticTarget

Targets returns structured option and argument targets in insertion order

func (*Diagnostic) Usage 

func (d *Diagnostic) Usage() string

Usage returns one usage line without the prefix. It returns an empty string for both absent usage and explicitly present empty usage; UsageValue distinguishes those states

func (*Diagnostic) UsageValue added in v0.4.0 

func (d *Diagnostic) UsageValue() (string, bool)

UsageValue returns the usage line and whether it is present

func (*Diagnostic) WithCategory added in v0.3.0 

func (d *Diagnostic) WithCategory(category DiagnosticCategory) *Diagnostic

WithCategory overrides the semantic category and returns the receiver

func (*Diagnostic) WithCommandPath 

func (d *Diagnostic) WithCommandPath(path []string) *Diagnostic

WithCommandPath sets the canonical command path and returns the receiver

func (*Diagnostic) WithHint added in v0.3.2 

func (d *Diagnostic) WithHint(hint string) *Diagnostic

WithHint appends one human-readable remediation hint

func (*Diagnostic) WithTarget added in v0.3.2 

func (d *Diagnostic) WithTarget(target DiagnosticTarget) *Diagnostic

WithTarget appends one structured option or argument target

func (*Diagnostic) WithUsage 

func (d *Diagnostic) WithUsage(usage string) *Diagnostic

WithUsage sets one present usage line without the usage prefix and returns the receiver. An empty string remains present

type DiagnosticCategory added in v0.3.0 

type DiagnosticCategory string

DiagnosticCategory is a stable semantic failure category 

const (
	// CategorySpecification reports an invalid Command Graph
	CategorySpecification DiagnosticCategory = "specification"
	// CategoryUsage reports invalid command-line usage
	CategoryUsage DiagnosticCategory = "usage"
	// CategoryExecution reports application execution failure
	CategoryExecution DiagnosticCategory = "execution"
	// CategoryCancellation reports cooperative cancellation
	CategoryCancellation DiagnosticCategory = "cancellation"
	// CategoryIO reports an injected I/O failure
	CategoryIO DiagnosticCategory = "io"
)

type DiagnosticCode 

type DiagnosticCode string

DiagnosticCode is a stable machine-readable framework or application code 

const (
	// CodeInvalidSpecification reports an inconsistent Command Graph
	CodeInvalidSpecification DiagnosticCode = "invalid-specification"
	// CodeUnknownOption reports an unknown long or short option
	CodeUnknownOption DiagnosticCode = "unknown-option"
	// CodeUnexpectedOptionValue reports a value attached to a flag or count
	CodeUnexpectedOptionValue DiagnosticCode = "unexpected-option-value"
	// CodeMissingOptionValue reports a Value option without a value
	CodeMissingOptionValue DiagnosticCode = "missing-option-value"
	// CodeDuplicateOption reports a repeated non-repeatable option
	CodeDuplicateOption DiagnosticCode = "duplicate-option"
	// CodeUnknownCommand reports an unknown child command
	CodeUnknownCommand DiagnosticCode = "unknown-command"
	// CodeMissingSubcommand reports a required child command
	CodeMissingSubcommand DiagnosticCode = "missing-subcommand"
	// CodeUnexpectedArgument reports an extra positional value
	CodeUnexpectedArgument DiagnosticCode = "unexpected-argument"
	// CodeMissingRequired reports a missing required value
	CodeMissingRequired DiagnosticCode = "missing-required"
	// CodeInvalidValue reports a Value Parser rejection
	CodeInvalidValue DiagnosticCode = "invalid-value"
	// CodeRequires reports an unsatisfied option requirement
	CodeRequires DiagnosticCode = "requires"
	// CodeConflicts reports two conflicting options
	CodeConflicts DiagnosticCode = "conflicts"
	// CodeOptionGroup reports an option-group cardinality violation
	CodeOptionGroup DiagnosticCode = "option-group"
	// CodeValidation reports a language-native Invocation validator rejection
	CodeValidation DiagnosticCode = "validation"
	// CodeMissingHandler reports a selected command without a handler
	CodeMissingHandler DiagnosticCode = "missing-handler"
	// CodeHandlerError reports an application handler failure
	CodeHandlerError DiagnosticCode = "handler-error"
	// CodeCancelled reports cooperative cancellation
	CodeCancelled DiagnosticCode = "cancelled"
	// CodeIOError reports an injected I/O failure
	CodeIOError DiagnosticCode = "io-error"
	// CodeResponseFileIO reports a Response File read failure
	CodeResponseFileIO DiagnosticCode = "response-file-io"
	// CodeResponseFileEncoding reports a non-UTF-8 Response File
	CodeResponseFileEncoding DiagnosticCode = "response-file-encoding"
	// CodeResponseFileSyntax reports invalid Response File tokenization
	CodeResponseFileSyntax DiagnosticCode = "response-file-syntax"
	// CodeResponseFileCycle reports a lexical include cycle
	CodeResponseFileCycle DiagnosticCode = "response-file-cycle"
	// CodeResponseFileLimit reports a Response File resource limit
	CodeResponseFileLimit DiagnosticCode = "response-file-limit"
	// CodeResponseFileStdin reports disabled or repeated standard-input expansion
	CodeResponseFileStdin DiagnosticCode = "response-file-stdin"
)

type DiagnosticRenderer added in v0.3.0 

type DiagnosticRenderer interface {
	// RenderDiagnostic returns text with one final newline
	RenderDiagnostic(diagnostic *Diagnostic) string
}

DiagnosticRenderer renders one structured Diagnostic

type DiagnosticTarget added in v0.3.2 

type DiagnosticTarget struct {
	// contains filtered or unexported fields
}

DiagnosticTarget identifies one option, argument, or Response File

func ArgumentTarget added in v0.3.2 

func ArgumentTarget(valueID string) DiagnosticTarget

ArgumentTarget constructs an argument target in the current Invocation scope

func OptionTarget added in v0.3.2 

func OptionTarget(valueID string) DiagnosticTarget

OptionTarget constructs an option target in the current Invocation scope

func ResponseFileTarget added in v0.4.0 

func ResponseFileTarget(reference string) DiagnosticTarget

ResponseFileTarget constructs a target for an include reference without its leading at sign

func (DiagnosticTarget) CommandIDPath added in v0.3.2 

func (t DiagnosticTarget) CommandIDPath() []string

CommandIDPath returns a copy of the stable command-ID path

func (DiagnosticTarget) IsSensitive added in v0.4.0 

func (t DiagnosticTarget) IsSensitive() bool

IsSensitive reports whether this target identifies a Sensitive Value declaration

func (DiagnosticTarget) Kind added in v0.3.2 

func (t DiagnosticTarget) Kind() DiagnosticTargetKind

Kind returns the entity kind identified by this target

func (DiagnosticTarget) ValueID added in v0.3.2 

func (t DiagnosticTarget) ValueID() string

ValueID returns the command-local value ID or Response File reference

func (DiagnosticTarget) ValueOrigin added in v0.4.0 

func (t DiagnosticTarget) ValueOrigin() (ValueOrigin, bool)

ValueOrigin returns the origin when this Diagnostic concerns one raw value

func (DiagnosticTarget) WithCommandIDPath added in v0.3.2 

func (t DiagnosticTarget) WithCommandIDPath(path ...string) DiagnosticTarget

WithCommandIDPath returns a copy with an explicit stable command-ID path

type DiagnosticTargetKind added in v0.3.2 

type DiagnosticTargetKind string

DiagnosticTargetKind identifies an option, argument, or Response File 

const (
	// TargetOption identifies a command option
	TargetOption DiagnosticTargetKind = "option"
	// TargetArgument identifies a positional argument
	TargetArgument DiagnosticTargetKind = "argument"
	// TargetResponseFile identifies a Response File include reference
	TargetResponseFile DiagnosticTargetKind = "response-file"
)

type ExitCodePolicy added in v0.3.0 

type ExitCodePolicy struct {
	// contains filtered or unexported fields
}

ExitCodePolicy maps semantic Diagnostic categories to process statuses

func DefaultExitCodePolicy added in v0.3.0 

func DefaultExitCodePolicy() ExitCodePolicy

DefaultExitCodePolicy returns the portable Nagi status mapping

func (ExitCodePolicy) StatusFor added in v0.3.0 

func (p ExitCodePolicy) StatusFor(category DiagnosticCategory) ExitStatus

StatusFor returns the process status for a semantic category

func (ExitCodePolicy) WithStatus added in v0.3.0 

func (p ExitCodePolicy) WithStatus(category DiagnosticCategory, status ExitStatus) ExitCodePolicy

WithStatus returns a copy with one category mapping replaced

type ExitStatus 

type ExitStatus uint8

ExitStatus is a portable process status from 0 through 255 

const (
	// StatusSuccess indicates successful execution
	StatusSuccess ExitStatus = 0
	// StatusFailure indicates a general application failure
	StatusFailure ExitStatus = 1
	// StatusUsage indicates command syntax or usage failure
	StatusUsage ExitStatus = 2
	// StatusCancelled indicates SIGINT-compatible cancellation
	StatusCancelled ExitStatus = 130
)

type FilesystemResponseFileReader added in v0.4.0 

type FilesystemResponseFileReader struct{}

FilesystemResponseFileReader is a stateless process-filesystem reader

func (FilesystemResponseFileReader) ReadResponseFile added in v0.4.0 

func (FilesystemResponseFileReader) ReadResponseFile(request ResponseFileReadRequest) ([]byte, *Diagnostic)

ReadResponseFile reads one bounded file from the process filesystem

type Handler 

type Handler func(context *Context, invocation *Invocation) (Outcome, error)

Handler executes one validated Invocation with the selected leaf as current scope

type HelpBlock added in v0.3.0 

type HelpBlock struct {
	// Kind selects paragraph or labeled-entry rendering
	Kind HelpBlockKind
	// Label is used by HelpBlockEntry
	Label string
	// Text is paragraph text or an entry description
	Text string
}

HelpBlock is one ordered block in a custom Help section

type HelpBlockKind added in v0.3.0 

type HelpBlockKind uint8

HelpBlockKind distinguishes custom-section paragraphs and entries 

const (
	// HelpBlockParagraph is one indented text block
	HelpBlockParagraph HelpBlockKind = iota
	// HelpBlockEntry is one cell-aligned labeled description
	HelpBlockEntry
)

type HelpDocument added in v0.3.0 

type HelpDocument struct {
	// contains filtered or unexported fields
}

HelpDocument is the structured, renderer-independent Help representation

func (HelpDocument) Arguments added in v0.3.0 

func (d HelpDocument) Arguments() []HelpEntry

Arguments returns a copy of positional-argument entries

func (HelpDocument) CommandPath added in v0.3.0 

func (d HelpDocument) CommandPath() []string

CommandPath returns the canonical root-to-target path

func (HelpDocument) Commands added in v0.3.0 

func (d HelpDocument) Commands() []HelpEntry

Commands returns a copy of child-command entries

func (HelpDocument) Deprecation added in v0.4.0 

func (d HelpDocument) Deprecation() (Deprecation, bool)

Deprecation returns replacement metadata when the selected command is deprecated

func (HelpDocument) Description added in v0.3.0 

func (d HelpDocument) Description() string

Description returns the command description

func (HelpDocument) Examples added in v0.3.0 

func (d HelpDocument) Examples() []HelpExample

Examples returns a copy of named examples

func (HelpDocument) InheritedOptions added in v0.4.0 

func (d HelpDocument) InheritedOptions() []HelpInheritedOption

InheritedOptions returns a deep copy in outermost-to-nearest ancestor and definition order. 

func (d HelpDocument) Links() []HelpLink

Links returns a copy of documentation links

func (HelpDocument) Notes added in v0.3.0 

func (d HelpDocument) Notes() []string

Notes returns a copy of Help notes

func (HelpDocument) OptionGroups added in v0.3.0 

func (d HelpDocument) OptionGroups() []HelpOptionGroup

OptionGroups returns a deep copy of option-group metadata

func (HelpDocument) OptionRelations added in v0.3.0 

func (d HelpDocument) OptionRelations() []HelpOptionRelation

OptionRelations returns a copy of pairwise option constraints

func (HelpDocument) Options added in v0.3.0 

func (d HelpDocument) Options() []HelpEntry

Options returns a copy of option entries

func (HelpDocument) Sections added in v0.3.0 

func (d HelpDocument) Sections() []HelpSection

Sections returns a deep copy of custom Help sections

func (HelpDocument) Usage added in v0.3.0 

func (d HelpDocument) Usage() []string

Usage returns a copy of rendered usage lines

func (HelpDocument) UsageVariants added in v0.3.1 

func (d HelpDocument) UsageVariants() []HelpUsageVariant

UsageVariants returns a copy of structured usage metadata

type HelpEntry added in v0.3.0 

type HelpEntry struct {
	// ID is the stable command, argument, option, or generated entry identifier
	ID string
	// Label is the cell-aligned entry label
	Label string
	// Description explains the labeled item
	Description string
	// contains filtered or unexported fields
}

HelpEntry is one labeled description in a Help Document

func (HelpEntry) Deprecation added in v0.4.0 

func (e HelpEntry) Deprecation() (Deprecation, bool)

Deprecation returns replacement metadata when this entry is deprecated

func (HelpEntry) IsSensitive added in v0.4.0 

func (e HelpEntry) IsSensitive() bool

IsSensitive reports whether this entry describes a Sensitive Value declaration

type HelpExample added in v0.3.0 

type HelpExample struct {
	// Name identifies the purpose of the example
	Name string
	// Invocation is the complete example command line
	Invocation string
}

HelpExample is one named command invocation

type HelpInheritedOption added in v0.4.0 

type HelpInheritedOption struct {
	// CommandPath is the source canonical command path.
	CommandPath []string
	// CommandIDPath is the source stable command-ID path.
	CommandIDPath []string
	// ID is the source-local stable option ID.
	ID string
	// Label is the option display label.
	Label string
	// Description excludes the rendered origin note.
	Description string
	// contains filtered or unexported fields
}

HelpInheritedOption is one option inherited from an ancestor in a Help Document.

func (HelpInheritedOption) Deprecation added in v0.4.0 

func (o HelpInheritedOption) Deprecation() (Deprecation, bool)

Deprecation returns replacement metadata when this inherited option is deprecated

func (HelpInheritedOption) IsSensitive added in v0.4.0 

func (o HelpInheritedOption) IsSensitive() bool

IsSensitive reports whether this inherited option is Sensitive 

type HelpLink struct {
	// Label identifies the linked resource
	Label string
	// URL is the link target
	URL string
}

HelpLink is one labeled documentation link

type HelpOptionGroup added in v0.3.0 

type HelpOptionGroup struct {
	// ID is the stable group identifier
	ID string
	// Kind is the group validation rule
	Kind OptionGroupKind
	// Presence selects resolved or command-line presence
	Presence PresenceBasis
	// OptionIDs contains stable member IDs in definition order
	OptionIDs []string
	// OptionLabels contains display spellings in definition order
	OptionLabels []string
}

HelpOptionGroup describes one portable option-group constraint

type HelpOptionRelation added in v0.3.0 

type HelpOptionRelation struct {
	// Kind selects requires or conflicts behavior
	Kind HelpOptionRelationKind
	// SourceID is the stable source option ID
	SourceID string
	// SourceLabel is the source option display spelling
	SourceLabel string
	// TargetID is the stable target option ID
	TargetID string
	// TargetLabel is the target option display spelling
	TargetLabel string
	// Presence selects resolved or command-line presence
	Presence PresenceBasis
}

HelpOptionRelation describes one portable pairwise option constraint

type HelpOptionRelationKind added in v0.3.0 

type HelpOptionRelationKind uint8

HelpOptionRelationKind distinguishes requires and conflicts constraints 

const (
	// HelpRelationRequires requires the target when the source is present
	HelpRelationRequires HelpOptionRelationKind = iota
	// HelpRelationConflicts rejects the source and target together
	HelpRelationConflicts
)

type HelpRenderer added in v0.3.0 

type HelpRenderer interface {
	// RenderHelp returns deterministic text with one final newline
	RenderHelp(document HelpDocument) string
}

HelpRenderer renders one structured Help Document

type HelpSection added in v0.3.0 

type HelpSection struct {
	// contains filtered or unexported fields
}

HelpSection is one application-defined structured Help section

func NewHelpSection added in v0.3.0 

func NewHelpSection(id, heading string) *HelpSection

NewHelpSection constructs an empty custom Help section

func (HelpSection) Blocks added in v0.3.0 

func (s HelpSection) Blocks() []HelpBlock

Blocks returns a copy of the ordered section blocks

func (*HelpSection) Entry added in v0.3.0 

func (s *HelpSection) Entry(label, description string) *HelpSection

Entry appends one labeled description

func (HelpSection) Heading added in v0.3.0 

func (s HelpSection) Heading() string

Heading returns the rendered section heading

func (HelpSection) ID added in v0.3.0 

func (s HelpSection) ID() string

ID returns the stable section identifier

func (*HelpSection) Paragraph added in v0.3.0 

func (s *HelpSection) Paragraph(text string) *HelpSection

Paragraph appends one text paragraph

type HelpUsageVariant added in v0.3.1 

type HelpUsageVariant struct {
	// CommandIDPath identifies the source Command using stable IDs
	CommandIDPath []string
	// ID is the stable variant identifier
	ID string
	// Syntax is the command-path-relative syntax suffix
	Syntax string
	// CommandLine is the complete canonical usage line
	CommandLine string
}

HelpUsageVariant is one structured invocation syntax in a Help Document

type Invocation 

type Invocation struct {
	// contains filtered or unexported fields
}

Invocation is one canonical parsed command path and its command-local typed value scopes

Unqualified access starts at the current scope and searches ancestors. The nearest declaration shadows an ancestor even when it has no resolved value. Validators temporarily use their defining Command as current; handlers and returned Invocations use the selected leaf

func (*Invocation) CommandIDPath added in v0.3.2 

func (i *Invocation) CommandIDPath() []string

CommandIDPath returns a copy of the stable root-to-leaf command-ID path

func (*Invocation) CommandPath 

func (i *Invocation) CommandPath() []string

CommandPath returns a copy of the canonical root-to-leaf path

func (*Invocation) Contains 

func (i *Invocation) Contains(id string) bool

Contains reports whether the nearest visible declaration has a value

func (*Invocation) Count 

func (i *Invocation) Count(id string) (uint64, bool)

Count returns occurrences for the nearest visible count declaration

func (*Invocation) CurrentScope added in v0.3.2 

func (i *Invocation) CurrentScope() InvocationScope

CurrentScope returns the exact scope where unqualified lookup starts

func (*Invocation) DeprecationNotices added in v0.4.0 

func (i *Invocation) DeprecationNotices() []DeprecationNotice

DeprecationNotices returns deprecated Command and Option uses in deterministic first-use order

A deprecated root Command comes first. Subsequent targets follow their first successful argv occurrence. Each stable target occurs at most once. Environment, external, and default value resolution do not produce notices

func (*Invocation) Flag 

func (i *Invocation) Flag(id string) (bool, bool)

Flag returns Boolean presence for the nearest visible flag declaration

func (Invocation) Format added in v0.4.0 

func (i Invocation) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing parsed values

func (*Invocation) IsRepeated 

func (i *Invocation) IsRepeated(id string) bool

IsRepeated reports whether a value ID was declared as repeatable

func (*Invocation) ParsedValues 

func (i *Invocation) ParsedValues(id string) []ParsedValue

ParsedValues returns values for the nearest visible Value declaration

func (*Invocation) RawValue 

func (i *Invocation) RawValue(id string) (string, bool)

RawValue returns the first raw value

func (*Invocation) Scope added in v0.3.2 

func (i *Invocation) Scope(commandIDPath ...string) (InvocationScope, bool)

Scope returns an exact local scope selected by stable command-ID path

func (*Invocation) Scopes added in v0.3.2 

func (i *Invocation) Scopes() []InvocationScope

Scopes returns exact command scopes in root-to-leaf order

func (*Invocation) Supplied added in v0.3.0 

func (i *Invocation) Supplied(id string) bool

Supplied reports whether the nearest visible declaration was present in argv

func (*Invocation) ValueIDs 

func (i *Invocation) ValueIDs() []string

ValueIDs returns sorted visible IDs that have a value

func (*Invocation) ValueIsSensitive added in v0.4.0 

func (i *Invocation) ValueIsSensitive(id string) bool

ValueIsSensitive reports whether the nearest visible Value declaration is Sensitive

func (*Invocation) ValueScopeIDPath added in v0.3.2 

func (i *Invocation) ValueScopeIDPath() []string

ValueScopeIDPath returns the current stable path where unqualified lookup starts

type InvocationScope added in v0.3.2 

type InvocationScope struct {
	// contains filtered or unexported fields
}

InvocationScope is one exact command-local value scope

func (InvocationScope) CommandIDPath added in v0.3.2 

func (s InvocationScope) CommandIDPath() []string

CommandIDPath returns the stable command-ID path for this exact scope

func (InvocationScope) CommandPath added in v0.3.2 

func (s InvocationScope) CommandPath() []string

CommandPath returns the canonical path prefix for this exact scope

func (InvocationScope) Contains added in v0.3.2 

func (s InvocationScope) Contains(id string) bool

Contains reports whether one local declaration has a value

func (InvocationScope) Count added in v0.3.2 

func (s InvocationScope) Count(id string) (uint64, bool)

Count returns occurrences for one local count declaration

func (InvocationScope) Flag added in v0.3.2 

func (s InvocationScope) Flag(id string) (bool, bool)

Flag returns Boolean presence for one local flag declaration

func (InvocationScope) Format added in v0.4.0 

func (s InvocationScope) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing parsed values

func (InvocationScope) IsRepeated added in v0.3.2 

func (s InvocationScope) IsRepeated(id string) bool

IsRepeated reports whether a local Value declaration is repeatable

func (InvocationScope) ParsedValues added in v0.3.2 

func (s InvocationScope) ParsedValues(id string) []ParsedValue

ParsedValues returns a copy of local parsed values and sources

func (InvocationScope) RawValue added in v0.3.2 

func (s InvocationScope) RawValue(id string) (string, bool)

RawValue returns the first local raw value

func (InvocationScope) Supplied added in v0.3.2 

func (s InvocationScope) Supplied(id string) bool

Supplied reports whether one local declaration was present in argv

func (InvocationScope) ValueIDs added in v0.3.2 

func (s InvocationScope) ValueIDs() []string

ValueIDs returns sorted local IDs that have a value

func (InvocationScope) ValueIsSensitive added in v0.4.0 

func (s InvocationScope) ValueIsSensitive(id string) bool

ValueIsSensitive reports whether one local Value declaration is Sensitive

func (InvocationScope) ValueScopeIDPath added in v0.3.2 

func (s InvocationScope) ValueScopeIDPath() []string

ValueScopeIDPath returns the stable path used by this exact value scope

type InvocationValidator added in v0.3.0 

type InvocationValidator func(invocation *Invocation) *Diagnostic

InvocationValidator returns a structured application validation failure

A nil result accepts the Invocation. The Invocation current scope is the Command that declared the validator

type JSONDiagnosticRenderer added in v0.4.0 

type JSONDiagnosticRenderer struct{}

JSONDiagnosticRenderer renders one structured Diagnostic as a stable newline-delimited JSON object

Its zero value is ready to use. Object member order, string escaping, nullability, and the final newline are part of the public format contract

func (JSONDiagnosticRenderer) RenderDiagnostic added in v0.4.0 

func (JSONDiagnosticRenderer) RenderDiagnostic(diagnostic *Diagnostic) string

RenderDiagnostic renders one compact JSON object with one final newline

type OptionGroup added in v0.3.0 

type OptionGroup struct {
	// contains filtered or unexported fields
}

OptionGroup applies one cardinality rule to local command options

func AllOrNone added in v0.3.0 

func AllOrNone(id string, optionIDs ...string) *OptionGroup

AllOrNone constructs a group whose options must occur together

func AtLeastOne added in v0.3.0 

func AtLeastOne(id string, optionIDs ...string) *OptionGroup

AtLeastOne constructs a group requiring one or more options

func AtMostOne added in v0.3.0 

func AtMostOne(id string, optionIDs ...string) *OptionGroup

AtMostOne constructs an optional mutually exclusive option group

func ExactlyOne added in v0.3.0 

func ExactlyOne(id string, optionIDs ...string) *OptionGroup

ExactlyOne constructs a required mutually exclusive option group

func (*OptionGroup) ID added in v0.3.0 

func (g *OptionGroup) ID() string

ID returns the stable group identifier

func (*OptionGroup) Kind added in v0.3.0 

func (g *OptionGroup) Kind() OptionGroupKind

Kind returns the group cardinality rule

func (*OptionGroup) OptionIDs added in v0.3.0 

func (g *OptionGroup) OptionIDs() []string

OptionIDs returns a copy of group members in definition order

func (*OptionGroup) Presence added in v0.3.0 

func (g *OptionGroup) Presence(presence PresenceBasis) *OptionGroup

Presence changes how this group determines whether an option is present

func (*OptionGroup) PresenceBasis added in v0.3.0 

func (g *OptionGroup) PresenceBasis() PresenceBasis

PresenceBasis returns the group's presence basis

type OptionGroupKind added in v0.3.0 

type OptionGroupKind uint8

OptionGroupKind controls how many group members may be present 

const (
	// GroupAtMostOne accepts zero or one present option
	GroupAtMostOne OptionGroupKind = iota
	// GroupExactlyOne accepts exactly one present option
	GroupExactlyOne
	// GroupAtLeastOne accepts one or more present options
	GroupAtLeastOne
	// GroupAllOrNone accepts zero options or every option
	GroupAllOrNone
)

type OptionKind 

type OptionKind uint8

OptionKind controls option storage and parsing 

const (
	// OptionFlag stores Boolean presence
	OptionFlag OptionKind = iota
	// OptionCount stores an occurrence count
	OptionCount
	// OptionValue stores parser-produced values
	OptionValue
)

type OptionSpec 

type OptionSpec struct {
	// contains filtered or unexported fields
}

OptionSpec defines one named command option

func Count 

func Count(id string) *OptionSpec

Count constructs an occurrence counter

func Flag 

func Flag(id string) *OptionSpec

Flag constructs a Boolean option

func ValueOption 

func ValueOption(id string) *OptionSpec

ValueOption constructs a raw platform-value option

func (*OptionSpec) CompletionProvider added in v0.4.0 

func (o *OptionSpec) CompletionProvider(provider CompletionProvider) *OptionSpec

CompletionProvider sets the dynamic completion provider for this Value option

The provider is only called while this option's value is the active completion target. Parsing and handler execution never call it

func (*OptionSpec) Conflicts 

func (o *OptionSpec) Conflicts(id string) *OptionSpec

Conflicts adds a conflicting option

func (*OptionSpec) ConflictsSupplied added in v0.3.0 

func (o *OptionSpec) ConflictsSupplied(id string) *OptionSpec

ConflictsSupplied conflicts with another command-line-supplied option

func (*OptionSpec) ConflictsWithPresence added in v0.3.0 

func (o *OptionSpec) ConflictsWithPresence(id string, presence PresenceBasis) *OptionSpec

ConflictsWithPresence adds a conflict with an explicit presence basis

func (*OptionSpec) Default 

func (o *OptionSpec) Default(value string) *OptionSpec

Default sets a command-definition fallback

func (*OptionSpec) Deprecated added in v0.4.0 

func (o *OptionSpec) Deprecated(replacement string) *OptionSpec

Deprecated marks this option deprecated with an application-provided replacement hint while preserving parsing

func (*OptionSpec) Deprecation added in v0.4.0 

func (o *OptionSpec) Deprecation() (Deprecation, bool)

Deprecation returns replacement metadata when this option is deprecated

func (*OptionSpec) Environment 

func (o *OptionSpec) Environment(name string) *OptionSpec

Environment sets an injected environment fallback

func (OptionSpec) Format added in v0.4.0 

func (o OptionSpec) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing a Sensitive option value

func (*OptionSpec) Help 

func (o *OptionSpec) Help(help string) *OptionSpec

Help sets the option description

func (*OptionSpec) Hidden added in v0.4.0 

func (o *OptionSpec) Hidden() *OptionSpec

Hidden omits this option from Help, completion, and derived documentation while preserving explicit argv parsing

func (*OptionSpec) ID 

func (o *OptionSpec) ID() string

ID returns the stable value identifier

func (*OptionSpec) Inherited added in v0.4.0 

func (o *OptionSpec) Inherited() *OptionSpec

Inherited makes this option visible in its declaring command and selected descendants. Recognition continues after subcommand selection and positionals until --. Parsed values remain stored in the declaring command scope. Graph validation rejects descendant spelling collisions.

func (*OptionSpec) IsHidden added in v0.4.0 

func (o *OptionSpec) IsHidden() bool

IsHidden reports whether this option is omitted from generated projections

func (*OptionSpec) IsInherited added in v0.4.0 

func (o *OptionSpec) IsInherited() bool

IsInherited reports whether this option is visible in selected descendant commands.

func (*OptionSpec) IsSensitive added in v0.4.0 

func (o *OptionSpec) IsSensitive() bool

IsSensitive reports whether this Value option requires redaction in framework-controlled projections

func (*OptionSpec) Kind 

func (o *OptionSpec) Kind() OptionKind

Kind returns the option kind

func (*OptionSpec) Long 

func (o *OptionSpec) Long(name string) *OptionSpec

Long sets the long option name without leading hyphens

func (*OptionSpec) Parser 

func (o *OptionSpec) Parser(parser ValueParser) *OptionSpec

Parser sets the typed Value Parser

func (*OptionSpec) Repeated 

func (o *OptionSpec) Repeated() *OptionSpec

Repeated allows a Value option to appear multiple times

func (*OptionSpec) Required 

func (o *OptionSpec) Required() *OptionSpec

Required requires this option after source resolution

func (*OptionSpec) Requires 

func (o *OptionSpec) Requires(id string) *OptionSpec

Requires adds an option requirement

func (*OptionSpec) RequiresSupplied added in v0.3.0 

func (o *OptionSpec) RequiresSupplied(id string) *OptionSpec

RequiresSupplied requires another command-line-supplied option

func (*OptionSpec) RequiresWithPresence added in v0.3.0 

func (o *OptionSpec) RequiresWithPresence(id string, presence PresenceBasis) *OptionSpec

RequiresWithPresence adds an option requirement with an explicit presence basis

func (*OptionSpec) Sensitive added in v0.4.0 

func (o *OptionSpec) Sensitive() *OptionSpec

Sensitive marks this Value option for redaction in framework-controlled Help, Diagnostic, formatting, and completion projections

Parsing and explicit raw or typed value access remain unchanged

func (*OptionSpec) Short 

func (o *OptionSpec) Short(name byte) *OptionSpec

Short sets the one-byte short option name

type Outcome 

type Outcome struct {
	// contains filtered or unexported fields
}

Outcome is the result of one command handler

func NewOutcome 

func NewOutcome(status ExitStatus) Outcome

NewOutcome constructs an Outcome with an explicit status

func Success 

func Success() Outcome

Success constructs a successful Outcome

func (Outcome) Status 

func (o Outcome) Status() ExitStatus

Status returns the process status

type ParseResult 

type ParseResult struct {
	// contains filtered or unexported fields
}

ParseResult is the result of argv parsing before handler execution

func (ParseResult) CommandIDPath added in v0.3.2 

func (r ParseResult) CommandIDPath() []string

CommandIDPath returns the selected stable command-ID path

func (ParseResult) CommandPath 

func (r ParseResult) CommandPath() []string

CommandPath returns the selected canonical command path

func (ParseResult) Format added in v0.4.0 

func (r ParseResult) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing parsed values

func (ParseResult) Invocation 

func (r ParseResult) Invocation() *Invocation

Invocation returns the validated invocation when Kind is ParseInvocation

func (ParseResult) Kind 

func (r ParseResult) Kind() ParseResultKind

Kind returns the parse result category

func (ParseResult) Version 

func (r ParseResult) Version() string

Version returns the configured version when Kind is ParseVersion

type ParseResultKind 

type ParseResultKind uint8

ParseResultKind distinguishes invocation, help, and version actions 

const (
	// ParseInvocation is a validated Invocation
	ParseInvocation ParseResultKind = iota
	// ParseHelp requests help for the selected command
	ParseHelp
	// ParseVersion requests the configured root version
	ParseVersion
)

type ParsedValue 

type ParsedValue struct {
	// contains filtered or unexported fields
}

ParsedValue stores one raw value, its source, and its typed parser result

func (ParsedValue) Format added in v0.4.0 

func (v ParsedValue) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing a Sensitive raw value or any typed parser result

func (ParsedValue) IsSensitive added in v0.4.0 

func (v ParsedValue) IsSensitive() bool

IsSensitive reports whether framework-controlled display must redact this value

func (ParsedValue) Origin added in v0.4.0 

func (v ParsedValue) Origin() ValueOrigin

Origin returns the source category and optional source identity

func (ParsedValue) Raw 

func (v ParsedValue) Raw() string

Raw returns the platform argument bytes as a Go string

func (ParsedValue) Source 

func (v ParsedValue) Source() ValueSource

Source returns where this value came from

func (ParsedValue) Typed 

func (v ParsedValue) Typed() any

Typed returns the language-native parser result

type PlainDeprecationNoticeRenderer added in v0.4.0 

type PlainDeprecationNoticeRenderer struct{}

PlainDeprecationNoticeRenderer renders stable plain deprecation notice text

func (PlainDeprecationNoticeRenderer) RenderDeprecationNotice added in v0.4.0 

func (PlainDeprecationNoticeRenderer) RenderDeprecationNotice(notice DeprecationNotice) string

RenderDeprecationNotice renders the stable warning and replacement hint

type PlainDiagnosticRenderer added in v0.3.0 

type PlainDiagnosticRenderer struct {
	// contains filtered or unexported fields
}

PlainDiagnosticRenderer renders stable plain Diagnostic text

func DefaultPlainDiagnosticRenderer added in v0.3.0 

func DefaultPlainDiagnosticRenderer() PlainDiagnosticRenderer

DefaultPlainDiagnosticRenderer returns the standard Nagi renderer

func (PlainDiagnosticRenderer) RenderDiagnostic added in v0.3.0 

func (r PlainDiagnosticRenderer) RenderDiagnostic(diagnostic *Diagnostic) string

RenderDiagnostic renders the configured plain format

func (PlainDiagnosticRenderer) WithPrefix added in v0.3.0 

func (r PlainDiagnosticRenderer) WithPrefix(prefix string) PlainDiagnosticRenderer

WithPrefix returns a copy using prefix before the diagnostic code

func (PlainDiagnosticRenderer) WithUsage added in v0.3.0 

func (r PlainDiagnosticRenderer) WithUsage(show bool) PlainDiagnosticRenderer

WithUsage returns a copy that includes or omits available usage text

type PlainHelpRenderer added in v0.3.0 

type PlainHelpRenderer struct{}

PlainHelpRenderer renders the standard cell-aware plain Help format

func (PlainHelpRenderer) RenderHelp added in v0.3.0 

func (PlainHelpRenderer) RenderHelp(document HelpDocument) string

RenderHelp renders the standard Help section order

type PresenceBasis added in v0.3.0 

type PresenceBasis uint8

PresenceBasis selects resolved or command-line presence for validation 

const (
	// PresenceResolved counts command-line, environment, external, or default values
	PresenceResolved PresenceBasis = iota
	// PresenceCommandLine counts only values supplied in argv
	PresenceCommandLine
)

type ProcessOptions added in v0.4.0 

type ProcessOptions struct {
	// contains filtered or unexported fields
}

ProcessOptions composes complete process Runtime services

Its zero value uses the default Runtime Policy without a Value Resolver or Response File expansion

func DefaultProcessOptions added in v0.4.0 

func DefaultProcessOptions() ProcessOptions

DefaultProcessOptions returns process integration without optional services

func (ProcessOptions) Policy added in v0.4.0 

func (o ProcessOptions) Policy() RuntimePolicy

Policy returns the configured normalized Runtime Policy

func (ProcessOptions) ResponseFileOptions added in v0.4.0 

func (o ProcessOptions) ResponseFileOptions() (ResponseFileOptions, bool)

ResponseFileOptions returns configured options and whether expansion is enabled

func (ProcessOptions) ValueResolver added in v0.4.0 

func (o ProcessOptions) ValueResolver() ValueResolver

ValueResolver returns the configured application Value Resolver

func (ProcessOptions) WithPolicy added in v0.4.0 

func (o ProcessOptions) WithPolicy(policy RuntimePolicy) ProcessOptions

WithPolicy returns a copy using an explicit Runtime Policy

func (ProcessOptions) WithResponseFiles added in v0.4.0 

func (o ProcessOptions) WithResponseFiles(options ResponseFileOptions) ProcessOptions

WithResponseFiles returns a copy enabling filesystem-backed Response Files

func (ProcessOptions) WithValueResolver added in v0.4.0 

func (o ProcessOptions) WithValueResolver(resolver ValueResolver) ProcessOptions

WithValueResolver returns a copy using an application-owned Value Resolver

func (ProcessOptions) WithoutResponseFiles added in v0.4.0 

func (o ProcessOptions) WithoutResponseFiles() ProcessOptions

WithoutResponseFiles returns a copy without Response File expansion

func (ProcessOptions) WithoutValueResolver added in v0.4.0 

func (o ProcessOptions) WithoutValueResolver() ProcessOptions

WithoutValueResolver returns a copy without a Value Resolver

type ResponseFileLimits added in v0.4.0 

type ResponseFileLimits struct {
	// contains filtered or unexported fields
}

ResponseFileLimits bounds one Response File expansion

Its zero value selects the portable defaults

func (ResponseFileLimits) MaxDepth added in v0.4.0 

func (l ResponseFileLimits) MaxDepth() int

MaxDepth returns the active include-depth limit

func (ResponseFileLimits) MaxSourceBytes added in v0.4.0 

func (l ResponseFileLimits) MaxSourceBytes() int

MaxSourceBytes returns the aggregate source-byte limit

func (ResponseFileLimits) MaxSources added in v0.4.0 

func (l ResponseFileLimits) MaxSources() int

MaxSources returns the source-read count limit

func (ResponseFileLimits) MaxTokenBytes added in v0.4.0 

func (l ResponseFileLimits) MaxTokenBytes() int

MaxTokenBytes returns the aggregate token-byte limit

func (ResponseFileLimits) MaxTokens added in v0.4.0 

func (l ResponseFileLimits) MaxTokens() int

MaxTokens returns the examined-token count limit

func (ResponseFileLimits) WithMaxDepth added in v0.4.0 

func (l ResponseFileLimits) WithMaxDepth(value int) ResponseFileLimits

WithMaxDepth returns a copy with the active include-depth limit replaced

func (ResponseFileLimits) WithMaxSourceBytes added in v0.4.0 

func (l ResponseFileLimits) WithMaxSourceBytes(value int) ResponseFileLimits

WithMaxSourceBytes returns a copy with the aggregate source-byte limit replaced

func (ResponseFileLimits) WithMaxSources added in v0.4.0 

func (l ResponseFileLimits) WithMaxSources(value int) ResponseFileLimits

WithMaxSources returns a copy with the source-read count limit replaced

func (ResponseFileLimits) WithMaxTokenBytes added in v0.4.0 

func (l ResponseFileLimits) WithMaxTokenBytes(value int) ResponseFileLimits

WithMaxTokenBytes returns a copy with the aggregate token-byte limit replaced

func (ResponseFileLimits) WithMaxTokens added in v0.4.0 

func (l ResponseFileLimits) WithMaxTokens(value int) ResponseFileLimits

WithMaxTokens returns a copy with the examined-token count limit replaced

type ResponseFileOptions added in v0.4.0 

type ResponseFileOptions struct {
	// contains filtered or unexported fields
}

ResponseFileOptions selects opt-in behavior for one expansion

Its zero value uses the default limits and disables exact @- expansion

func (ResponseFileOptions) Limits added in v0.4.0 

func (o ResponseFileOptions) Limits() ResponseFileLimits

Limits returns the configured normalized resource limits

func (ResponseFileOptions) StandardInputEnabled added in v0.4.0 

func (o ResponseFileOptions) StandardInputEnabled() bool

StandardInputEnabled reports whether exact @- expansion is enabled

func (ResponseFileOptions) WithLimits added in v0.4.0 

func (o ResponseFileOptions) WithLimits(limits ResponseFileLimits) ResponseFileOptions

WithLimits returns a copy using the provided resource limits

func (ResponseFileOptions) WithStandardInput added in v0.4.0 

func (o ResponseFileOptions) WithStandardInput(enabled bool) ResponseFileOptions

WithStandardInput returns a copy that enables or disables exact @- expansion

type ResponseFileReadRequest added in v0.4.0 

type ResponseFileReadRequest struct {
	// contains filtered or unexported fields
}

ResponseFileReadRequest is one bounded request sent to an injected reader

func (ResponseFileReadRequest) Path added in v0.4.0 

func (r ResponseFileReadRequest) Path() string

Path returns the lexically resolved platform-native file path

func (ResponseFileReadRequest) ReadLimit added in v0.4.0 

func (r ResponseFileReadRequest) ReadLimit() int

ReadLimit returns the maximum bytes needed by the expander

The value is one greater than the remaining accepted byte count when representable, allowing a reader to report a limit crossing without loading the rest of the source

type ResponseFileReader added in v0.4.0 

type ResponseFileReader interface {
	// ReadResponseFile reads at most the requested bytes or returns a Diagnostic
	ReadResponseFile(ResponseFileReadRequest) ([]byte, *Diagnostic)
}

ResponseFileReader reads Response File bytes from an injected or real filesystem

type ResponseFileReaderFunc added in v0.4.0 

type ResponseFileReaderFunc func(ResponseFileReadRequest) ([]byte, *Diagnostic)

ResponseFileReaderFunc adapts a function into a ResponseFileReader

func (ResponseFileReaderFunc) ReadResponseFile added in v0.4.0 

func (f ResponseFileReaderFunc) ReadResponseFile(request ResponseFileReadRequest) ([]byte, *Diagnostic)

ReadResponseFile calls the adapted function

type RuntimePolicy added in v0.3.0 

type RuntimePolicy struct {
	// contains filtered or unexported fields
}

RuntimePolicy selects rendering and category-to-status mapping

func DefaultRuntimePolicy added in v0.3.0 

func DefaultRuntimePolicy() RuntimePolicy

DefaultRuntimePolicy returns deterministic Nagi runtime behavior

func (RuntimePolicy) ExitCodePolicy added in v0.3.2 

func (p RuntimePolicy) ExitCodePolicy() ExitCodePolicy

ExitCodePolicy returns the configured category-to-status mapping

func (RuntimePolicy) RenderDeprecationNotice added in v0.4.0 

func (p RuntimePolicy) RenderDeprecationNotice(notice DeprecationNotice) (string, bool)

RenderDeprecationNotice renders one notice when notice output is enabled

func (RuntimePolicy) RenderDiagnostic added in v0.3.2 

func (p RuntimePolicy) RenderDiagnostic(diagnostic *Diagnostic) string

RenderDiagnostic renders one Diagnostic without writing to process output

func (RuntimePolicy) RenderHelp added in v0.3.2 

func (p RuntimePolicy) RenderHelp(document HelpDocument) string

RenderHelp renders one Help Document without writing to process output

func (RuntimePolicy) StatusForDiagnostic added in v0.3.2 

func (p RuntimePolicy) StatusForDiagnostic(diagnostic *Diagnostic) ExitStatus

StatusForDiagnostic returns the configured process status for one Diagnostic

func (RuntimePolicy) WithDeprecationNoticeRenderer added in v0.4.0 

func (p RuntimePolicy) WithDeprecationNoticeRenderer(
	renderer DeprecationNoticeRenderer,
) RuntimePolicy

WithDeprecationNoticeRenderer returns a copy that renders Invocation deprecation notices before handler execution

func (RuntimePolicy) WithDiagnosticRenderer added in v0.3.0 

func (p RuntimePolicy) WithDiagnosticRenderer(renderer DiagnosticRenderer) RuntimePolicy

WithDiagnosticRenderer returns a copy using the provided Diagnostic renderer

func (RuntimePolicy) WithExitCodePolicy added in v0.3.0 

func (p RuntimePolicy) WithExitCodePolicy(policy ExitCodePolicy) RuntimePolicy

WithExitCodePolicy returns a copy using the provided status mapping

func (RuntimePolicy) WithHelpRenderer added in v0.3.0 

func (p RuntimePolicy) WithHelpRenderer(renderer HelpRenderer) RuntimePolicy

WithHelpRenderer returns a copy using the provided Help renderer

func (RuntimePolicy) WithoutDeprecationNoticeRenderer added in v0.4.0 

func (p RuntimePolicy) WithoutDeprecationNoticeRenderer() RuntimePolicy

WithoutDeprecationNoticeRenderer returns a copy without automatic deprecation notice output

type SubcommandUsageMode added in v0.3.2 

type SubcommandUsageMode uint8

SubcommandUsageMode selects how parent Help presents subcommand syntax 

const (
	// SubcommandUsageAuto generates one generic optional-subcommand usage line
	SubcommandUsageAuto SubcommandUsageMode = iota
	// SubcommandUsageHidden omits generated optional-subcommand usage
	SubcommandUsageHidden
	// SubcommandUsageExpanded expands each immediate child's direct variants without recursion
	SubcommandUsageExpanded
)

type ValueAccessError added in v0.3.2 

type ValueAccessError struct {
	// contains filtered or unexported fields
}

ValueAccessError reports why required typed value access failed

func RequireValueAs added in v0.3.2 

func RequireValueAs[T any](values ValueLookup, id string) (T, *ValueAccessError)

RequireValueAs returns the first parser result or a structured access error

Environment, external, and default values are resolved before this lookup

func (*ValueAccessError) CommandIDPath added in v0.3.2 

func (e *ValueAccessError) CommandIDPath() []string

CommandIDPath returns the stable scope path used for the lookup

func (*ValueAccessError) Error added in v0.3.2 

func (e *ValueAccessError) Error() string

Error implements error

func (*ValueAccessError) Kind added in v0.3.2 

func (e *ValueAccessError) Kind() ValueAccessErrorKind

Kind returns whether the value was missing or had another dynamic type

func (*ValueAccessError) ValueID added in v0.3.2 

func (e *ValueAccessError) ValueID() string

ValueID returns the requested command-local value ID

type ValueAccessErrorKind added in v0.3.2 

type ValueAccessErrorKind uint8

ValueAccessErrorKind distinguishes missing values and parser type mismatches 

const (
	// ValueMissing means no resolved value exists for the requested ID
	ValueMissing ValueAccessErrorKind = iota
	// ValueTypeMismatch means the parser result does not have the requested type
	ValueTypeMismatch
)

type ValueLookup added in v0.3.2 

type ValueLookup interface {
	// ValueScopeIDPath returns the stable command-ID path used by this lookup
	ValueScopeIDPath() []string
	// ParsedValues returns parsed values and sources for one ID
	ParsedValues(id string) []ParsedValue
}

ValueLookup provides typed value access for an Invocation or exact scope

type ValueOrigin added in v0.4.0 

type ValueOrigin struct {
	// contains filtered or unexported fields
}

ValueOrigin identifies one resolved source and its optional portable identity

func (ValueOrigin) Identity added in v0.4.0 

func (o ValueOrigin) Identity() (string, bool)

Identity returns the environment name or non-secret external identity when present

func (ValueOrigin) Source added in v0.4.0 

func (o ValueOrigin) Source() ValueSource

Source returns the source category

type ValueParser 

type ValueParser interface {
	// Parse returns a typed value or a human-readable validation reason
	Parse(raw string) (any, error)
	// Metavar returns the help placeholder without angle brackets
	Metavar() string
	// PossibleValues returns a documented finite value set when one exists
	PossibleValues() []string
}

ValueParser parses one raw option or positional value

func CustomParser 

func CustomParser[T any](metavar string, parse func(string) (T, error)) ValueParser

CustomParser adapts a typed Go function into a ValueParser

func IntegerParser 

func IntegerParser() ValueParser

IntegerParser returns a parser for signed 64-bit decimal integers

func PossibleValuesParser 

func PossibleValuesParser(values ...string) ValueParser

PossibleValuesParser returns a parser that accepts an exact finite value set

func RawParser 

func RawParser() ValueParser

RawParser returns a parser that preserves arbitrary bytes

func StringParser 

func StringParser() ValueParser

StringParser returns a parser that requires valid UTF-8

type ValueResolution added in v0.4.0 

type ValueResolution struct {
	// contains filtered or unexported fields
}

ValueResolution contains raw values returned by an application resolver

Its zero value is unresolved and permits the configured Default

func MergeValueResolution added in v0.4.0 

func MergeValueResolution(sourceIdentity string, values ...string) ValueResolution

MergeValueResolution returns external values followed by Default

Merge is valid only for a repeated Value Option. The source identity is validated during parsing and must use the stable ASCII identifier grammar

func ReplaceValueResolution added in v0.4.0 

func ReplaceValueResolution(sourceIdentity string, values ...string) ValueResolution

ReplaceValueResolution returns external values that suppress Default

The source identity is validated during parsing and must use the stable ASCII identifier grammar

func (ValueResolution) Format added in v0.4.0 

func (r ValueResolution) Format(state fmt.State, _ rune)

Format implements fmt.Formatter without exposing resolver raw values

func (ValueResolution) IsResolved added in v0.4.0 

func (r ValueResolution) IsResolved() bool

IsResolved reports whether a resolver supplied a result

func (ValueResolution) Mode added in v0.4.0 

func (r ValueResolution) Mode() ValueResolutionMode

Mode returns whether external values replace or merge with Default

func (ValueResolution) SourceIdentity added in v0.4.0 

func (r ValueResolution) SourceIdentity() (string, bool)

SourceIdentity returns the external source identity when resolved

func (ValueResolution) Values added in v0.4.0 

func (r ValueResolution) Values() []string

Values returns a copy of raw values in resolver order

type ValueResolutionMode added in v0.4.0 

type ValueResolutionMode uint8

ValueResolutionMode selects whether external values replace or merge with Default 

const (
	// ValueResolutionReplace suppresses the configured Default
	ValueResolutionReplace ValueResolutionMode = iota
	// ValueResolutionMerge appends the configured Default after external values
	ValueResolutionMerge
)

type ValueResolutionRequest added in v0.4.0 

type ValueResolutionRequest struct {
	// contains filtered or unexported fields
}

ValueResolutionRequest describes one selected unresolved Value Option

func (ValueResolutionRequest) CommandIDPath added in v0.4.0 

func (r ValueResolutionRequest) CommandIDPath() []string

CommandIDPath returns the stable path declaring this Value Option

func (ValueResolutionRequest) CommandPath added in v0.4.0 

func (r ValueResolutionRequest) CommandPath() []string

CommandPath returns the canonical path declaring this Value Option

func (ValueResolutionRequest) IsRepeated added in v0.4.0 

func (r ValueResolutionRequest) IsRepeated() bool

IsRepeated reports whether the Value Option accepts multiple values

func (ValueResolutionRequest) IsSensitive added in v0.4.0 

func (r ValueResolutionRequest) IsSensitive() bool

IsSensitive reports whether the Value Option is Sensitive

func (ValueResolutionRequest) SelectedCommandIDPath added in v0.4.0 

func (r ValueResolutionRequest) SelectedCommandIDPath() []string

SelectedCommandIDPath returns the complete selected stable command-ID path

func (ValueResolutionRequest) SelectedCommandPath added in v0.4.0 

func (r ValueResolutionRequest) SelectedCommandPath() []string

SelectedCommandPath returns the complete selected canonical command path

func (ValueResolutionRequest) ValueID added in v0.4.0 

func (r ValueResolutionRequest) ValueID() string

ValueID returns the command-local Value Option ID

type ValueResolver added in v0.4.0 

type ValueResolver func(ValueResolutionRequest) (ValueResolution, *Diagnostic)

ValueResolver maps already loaded application configuration to raw Value Option fallbacks synchronously during parsing

A nil Diagnostic reports success. The zero ValueResolution is unresolved. A resolver should project application state rather than start file or network I/O

type ValueSource 

type ValueSource uint8

ValueSource identifies where a parsed value came from 

const (
	// SourceCommandLine indicates an argv value
	SourceCommandLine ValueSource = iota
	// SourceEnvironment indicates an injected environment fallback
	SourceEnvironment
	// SourceDefault indicates a command-definition fallback
	SourceDefault
	// SourceExternal indicates an application Value Resolver fallback
	SourceExternal
)

Source Files

View all Source files

Directories

Path Synopsis
Package clitest provides process-free test support for Nagi CLI applications
 Package clitest provides process-free test support for Nagi CLI applications
Package completion generates shell integrations for a Nagi CLI CompletionEngine and handles their reserved runtime protocol before normal command dispatch
 Package completion generates shell integrations for a Nagi CLI CompletionEngine and handles their reserved runtime protocol before normal command dispatch
Package document renders Nagi CLI Help Documents as Markdown or man pages without performing filesystem I/O
 Package document renders Nagi CLI Help Documents as Markdown or man pages without performing filesystem I/O
examples
basic command
Command basic is a minimal Nagi CLI application
 Command basic is a minimal Nagi CLI application
completion command
Command completion demonstrates generated shell scripts and their reserved protocol
 Command completion demonstrates generated shell scripts and their reserved protocol
documentation command
Command documentation renders every visible command Help Document without retaining all pages
 Command documentation renders every visible command Help Document without retaining all pages
json-diagnostic command
Command json-diagnostic renders one structured Diagnostic as stable JSON
 Command json-diagnostic renders one structured Diagnostic as stable JSON
lifecycle command
Command lifecycle hides internal syntax and reports deprecated syntax
 Command lifecycle hides internal syntax and reports deprecated syntax
prompt command
Command prompt demonstrates optional line-oriented interactive prompts
 Command prompt demonstrates optional line-oriented interactive prompts
response-files command
Response Files expand opt-in argument containers before command parsing
 Response Files expand opt-in argument containers before command parsing
sensitive-values command
Sensitive Value redaction preserves explicit handler access
 Sensitive Value redaction preserves explicit handler access
staged command
Command staged demonstrates incremental Nagi CLI adoption
 Command staged demonstrates incremental Nagi CLI adoption
status command
Command status demonstrates TTY-aware status reporting with plain-log fallback
 Command status demonstrates TTY-aware status reporting with plain-log fallback
subcommands command
Command subcommands demonstrates a nested Nagi CLI application
 Command subcommands demonstrates a nested Nagi CLI application
value-sources command
Value Source Adapter maps application-owned configuration into CLI fallbacks
 Value Source Adapter maps application-owned configuration into CLI fallbacks
internal
conformance
Package conformance contains private helpers for shared fixture tests
 Package conformance contains private helpers for shared fixture tests
Package prompt provides lightweight line-oriented interactive prompts above Nagi CLI Core
 Package prompt provides lightweight line-oriented interactive prompts above Nagi CLI Core
Package status provides synchronous TTY-aware status reporting above Nagi CLI Core
 Package status provides synchronous TTY-aware status reporting above Nagi CLI Core

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.