Add instance command registry and composition
This commit is contained in:
265
command.go
Normal file
265
command.go
Normal file
@@ -0,0 +1,265 @@
|
||||
package commandkit
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// Command is an opaque command declaration. Use NewCommand or Group to create
|
||||
// declarations and WithChildren to compose them.
|
||||
type Command struct {
|
||||
name string
|
||||
summary string
|
||||
description string
|
||||
children []Command
|
||||
payload commandPayload
|
||||
}
|
||||
|
||||
// Supplied carries a value and whether it was explicitly provided.
|
||||
type Supplied[T any] struct {
|
||||
// Value is the associated value.
|
||||
Value T
|
||||
// Set reports whether a caller explicitly supplied the value.
|
||||
Set bool
|
||||
}
|
||||
|
||||
// FlagMeta describes a command flag.
|
||||
type FlagMeta struct {
|
||||
// Name is the flag name without leading dashes.
|
||||
Name string
|
||||
// Short is an optional one-byte spelling.
|
||||
Short string
|
||||
// Usage briefly describes the flag.
|
||||
Usage string
|
||||
// Required reports whether execution requires the flag to be supplied.
|
||||
Required bool
|
||||
}
|
||||
|
||||
// ArgumentMeta describes a positional command argument.
|
||||
type ArgumentMeta struct {
|
||||
// Name is the argument name shown in command help.
|
||||
Name string
|
||||
// Usage briefly describes the argument.
|
||||
Usage string
|
||||
}
|
||||
|
||||
// Flag represents a typed binding for a command flag.
|
||||
type Flag[I any] struct {
|
||||
binding flagBinding[I]
|
||||
}
|
||||
|
||||
type flagBinding[I any] struct {
|
||||
meta FlagMeta
|
||||
prepare func([]string) (func(*I), error)
|
||||
valid bool
|
||||
}
|
||||
|
||||
// Argument represents a typed binding for a positional command argument.
|
||||
type Argument[I any] struct {
|
||||
binding argumentBinding[I]
|
||||
}
|
||||
|
||||
type argumentBinding[I any] struct {
|
||||
meta ArgumentMeta
|
||||
min int
|
||||
max int
|
||||
prepare func([]string) (func(*I), error)
|
||||
valid bool
|
||||
}
|
||||
|
||||
// CommandSpec declares one command using typed input and handler callbacks.
|
||||
type CommandSpec[I any] struct {
|
||||
// Name is one command path component.
|
||||
Name string
|
||||
// Summary is a short description of the command.
|
||||
Summary string
|
||||
// Description provides additional command detail.
|
||||
Description string
|
||||
// NewInput creates an input value for execution. A nil factory uses a fresh
|
||||
// zero value.
|
||||
NewInput func() I
|
||||
// Flags declares the command's local flags.
|
||||
Flags []Flag[I]
|
||||
// Arguments declares the command's positional inputs.
|
||||
Arguments []Argument[I]
|
||||
// CheckInput validates declared combinations of parsed inputs.
|
||||
CheckInput func(I) error
|
||||
// Run handles an invocation. It may be nil for a command used as a group.
|
||||
Run func(Invocation, I) Outcome
|
||||
}
|
||||
|
||||
type commandPayload interface {
|
||||
validate() error
|
||||
hasRun() bool
|
||||
newInput() any
|
||||
run(Invocation, any) Outcome
|
||||
}
|
||||
|
||||
type typedCommand[I any] struct {
|
||||
spec CommandSpec[I]
|
||||
}
|
||||
|
||||
func (c typedCommand[I]) validate() error {
|
||||
return validateBindings(c.spec.Flags, c.spec.Arguments)
|
||||
}
|
||||
|
||||
func (c typedCommand[I]) hasRun() bool {
|
||||
return c.spec.Run != nil
|
||||
}
|
||||
|
||||
func (c typedCommand[I]) newInput() any {
|
||||
var input I
|
||||
if c.spec.NewInput != nil {
|
||||
input = c.spec.NewInput()
|
||||
}
|
||||
return &input
|
||||
}
|
||||
|
||||
func (c typedCommand[I]) run(invocation Invocation, input any) Outcome {
|
||||
return c.spec.Run(invocation, *input.(*I))
|
||||
}
|
||||
|
||||
// NewCommand validates and creates a typed command declaration. It retains
|
||||
// callbacks without invoking them and copies the declarative flag and argument
|
||||
// slices.
|
||||
func NewCommand[I any](spec CommandSpec[I]) (Command, error) {
|
||||
if err := validateCommandName(spec.Name); err != nil {
|
||||
return Command{}, err
|
||||
}
|
||||
copySpec := spec
|
||||
copySpec.Flags = append([]Flag[I](nil), spec.Flags...)
|
||||
copySpec.Arguments = append([]Argument[I](nil), spec.Arguments...)
|
||||
payload := typedCommand[I]{spec: copySpec}
|
||||
if err := payload.validate(); err != nil {
|
||||
return Command{}, fmt.Errorf("command %q: %w", spec.Name, err)
|
||||
}
|
||||
return Command{
|
||||
name: spec.Name,
|
||||
summary: spec.Summary,
|
||||
description: spec.Description,
|
||||
payload: payload,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// Group creates a non-runnable command group with the supplied children.
|
||||
func Group(name, summary string, children ...Command) (Command, error) {
|
||||
if err := validateCommandName(name); err != nil {
|
||||
return Command{}, err
|
||||
}
|
||||
group := Command{name: name, summary: summary, children: cloneCommands(children)}
|
||||
if err := validateCommandDeclaration(group); err != nil {
|
||||
return Command{}, err
|
||||
}
|
||||
return group, nil
|
||||
}
|
||||
|
||||
// WithChildren returns a copy of parent with the supplied relative child
|
||||
// declarations. The parent's optional handler and input bindings are retained.
|
||||
func WithChildren(parent Command, children ...Command) (Command, error) {
|
||||
if err := validateCommandDeclaration(parent); err != nil {
|
||||
return Command{}, fmt.Errorf("parent command: %w", err)
|
||||
}
|
||||
combined := make([]Command, 0, len(parent.children)+len(children))
|
||||
combined = append(combined, parent.children...)
|
||||
combined = append(combined, children...)
|
||||
result := parent
|
||||
result.children = cloneCommands(combined)
|
||||
if err := validateCommandDeclaration(result); err != nil {
|
||||
return Command{}, err
|
||||
}
|
||||
return result, nil
|
||||
}
|
||||
|
||||
func cloneCommands(commands []Command) []Command {
|
||||
if len(commands) == 0 {
|
||||
return nil
|
||||
}
|
||||
cloned := make([]Command, len(commands))
|
||||
for i, command := range commands {
|
||||
cloned[i] = cloneCommand(command)
|
||||
}
|
||||
return cloned
|
||||
}
|
||||
|
||||
func cloneCommand(command Command) Command {
|
||||
command.children = cloneCommands(command.children)
|
||||
return command
|
||||
}
|
||||
|
||||
func validateCommandDeclaration(command Command) error {
|
||||
if err := validateCommandName(command.name); err != nil {
|
||||
return err
|
||||
}
|
||||
if command.payload != nil {
|
||||
if err := command.payload.validate(); err != nil {
|
||||
return fmt.Errorf("command %q: %w", command.name, err)
|
||||
}
|
||||
}
|
||||
|
||||
children := make(map[string]struct{}, len(command.children))
|
||||
for _, child := range command.children {
|
||||
if err := validateCommandDeclaration(child); err != nil {
|
||||
return err
|
||||
}
|
||||
if _, exists := children[child.name]; exists {
|
||||
return fmt.Errorf("duplicate child command %q under %q", child.name, command.name)
|
||||
}
|
||||
children[child.name] = struct{}{}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func validateCommandName(name string) error {
|
||||
fields := strings.Fields(name)
|
||||
if len(fields) != 1 || fields[0] != name || strings.HasPrefix(name, "-") || name == "--" {
|
||||
return fmt.Errorf("command name %q must be one non-option token", name)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func validateBindings[I any](flags []Flag[I], arguments []Argument[I]) error {
|
||||
flagNames := make(map[string]struct{}, len(flags))
|
||||
shortNames := make(map[string]struct{}, len(flags))
|
||||
for _, flag := range flags {
|
||||
binding := flag.binding
|
||||
if binding.meta.Name == "" || strings.ContainsAny(binding.meta.Name, " \t\r\n") || strings.HasPrefix(binding.meta.Name, "-") {
|
||||
return fmt.Errorf("flag name %q must be a nonempty token without leading dashes", binding.meta.Name)
|
||||
}
|
||||
if binding.meta.Name == "help" {
|
||||
return fmt.Errorf("flag name %q is reserved for help", binding.meta.Name)
|
||||
}
|
||||
if _, exists := flagNames[binding.meta.Name]; exists {
|
||||
return fmt.Errorf("duplicate flag name %q", binding.meta.Name)
|
||||
}
|
||||
flagNames[binding.meta.Name] = struct{}{}
|
||||
if binding.meta.Short != "" {
|
||||
if len(binding.meta.Short) != 1 || binding.meta.Short == "-" {
|
||||
return fmt.Errorf("short spelling %q must be one byte", binding.meta.Short)
|
||||
}
|
||||
if binding.meta.Short == "h" {
|
||||
return fmt.Errorf("short spelling %q is reserved for help", binding.meta.Short)
|
||||
}
|
||||
if _, exists := shortNames[binding.meta.Short]; exists {
|
||||
return fmt.Errorf("duplicate short spelling %q", binding.meta.Short)
|
||||
}
|
||||
shortNames[binding.meta.Short] = struct{}{}
|
||||
}
|
||||
if !binding.valid || binding.prepare == nil {
|
||||
return fmt.Errorf("flag %q is missing parser or setter wiring", binding.meta.Name)
|
||||
}
|
||||
}
|
||||
|
||||
for _, argument := range arguments {
|
||||
binding := argument.binding
|
||||
if binding.meta.Name == "" {
|
||||
return fmt.Errorf("argument name must not be empty")
|
||||
}
|
||||
if binding.min < 0 || binding.max < -1 || (binding.max >= 0 && binding.min > binding.max) {
|
||||
return fmt.Errorf("argument %q has invalid bounds %d..%d", binding.meta.Name, binding.min, binding.max)
|
||||
}
|
||||
if !binding.valid || binding.prepare == nil {
|
||||
return fmt.Errorf("argument %q is missing parser or setter wiring", binding.meta.Name)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
Reference in New Issue
Block a user