tinyflags.go

// Package tinyflags provides a high-level API for defining and parsing
// CLI flags with support for dynamic groups, custom types, and rich usage output.
package tinyflags

import (
	"errors"

	"github.com/containeroo/tinyflags/internal/core"
	"github.com/containeroo/tinyflags/internal/dynamic"
	"github.com/containeroo/tinyflags/internal/engine"
)

// ErrorHandling defines how parsing errors are handled.
type ErrorHandling = engine.ErrorHandling

// ValueSource identifies where an effective flag value came from.
type ValueSource = engine.ValueSource

// ValueOrigin identifies the exact input that supplied an effective flag value.
type ValueOrigin = engine.ValueOrigin

// Override describes one explicitly supplied flag value and its origin.
type Override = engine.Override

// Overrides contains explicitly supplied flag values keyed by canonical flag name.
type Overrides = engine.Overrides

const (
	// ValueSourceDefault means a flag kept its default value.
	ValueSourceDefault = engine.ValueSourceDefault
	// ValueSourceFlag means a command-line flag supplied the value.
	ValueSourceFlag = engine.ValueSourceFlag
	// ValueSourceEnvironment means an environment variable supplied the value.
	ValueSourceEnvironment = engine.ValueSourceEnvironment
)

const (
	ContinueOnError = engine.ContinueOnError // Continue and return error
	ExitOnError     = engine.ExitOnError     // Exit with error message
	PanicOnError    = engine.PanicOnError    // Panic on error
)

// Common user-triggered exit conditions.
type (
	HelpRequested    = engine.HelpRequested
	VersionRequested = engine.VersionRequested
)

// UsageError wraps a semantic parse error with rendered help text.
type UsageError struct {
	Err  error  // Underlying parsing or validation error.
	Help string // Usage text that explains how to correct the error.
}

// Error returns the wrapped error message.
func (e *UsageError) Error() string {
	if e == nil || e.Err == nil {
		return ""
	}
	return e.Err.Error()
}

// Unwrap exposes the semantic parse error.
func (e *UsageError) Unwrap() error {
	if e == nil {
		return nil
	}
	return e.Err
}

// CommandRequired is returned when one command requires a subcommand selection.
type CommandRequired struct {
	Command string // Name of the command that requires a subcommand.
}

// Error returns the human-readable message for a missing required subcommand.
func (e *CommandRequired) Error() string {
	return `command "` + e.Command + `" requires a subcommand`
}

var (
	IsHelpRequested    = engine.IsHelpRequested
	IsVersionRequested = engine.IsVersionRequested
	RequestHelp        = engine.RequestHelp
	RequestVersion     = engine.RequestVersion
)

// IsCommandRequired checks whether err indicates a missing required subcommand.
func IsCommandRequired(err error) bool {
	var target *CommandRequired
	return errors.As(err, &target)
}

// HelpText extracts rendered help text from a usage-bearing error.
func HelpText(err error) (string, bool) {
	var usageErr *UsageError
	if !errors.As(err, &usageErr) || usageErr == nil || usageErr.Help == "" {
		return "", false
	}
	return usageErr.Help, true
}

// FlagPrintMode controls how the usage line is rendered.
type FlagPrintMode = engine.FlagPrintMode

const (
	PrintNone  = engine.PrintNone  // Omits usage line entirely
	PrintFlags = engine.PrintFlags // Prints: [flags]
	PrintShort = engine.PrintShort // Prints: -v
	PrintLong  = engine.PrintLong  // Prints: --verbose
	PrintBoth  = engine.PrintBoth  // Prints: -v|--verbose
)

// Exported types for advanced access.
type (
	DynamicGroup = dynamic.Group // Dynamic group of instance-scoped flags
	StaticFlag   = core.BaseFlag // Static flag definition metadata
	Flag[T any]  = core.Flag[T]  // Minimal flag handle interface
)

// FlagSet is the user-facing flag parser and usage configurator.
type FlagSet struct {
	impl  *engine.FlagSet // Internal implementation that owns flag state.
	Usage func()          // Optional custom usage function
}

// NewFlagSet creates a new flag set with the given name and error handling mode.
func NewFlagSet(name string, handling ErrorHandling) *FlagSet {
	return &FlagSet{impl: engine.NewFlagSet(name, handling)}
}