cliutil

func AddCLIOption ¶ added in v0.2.0

func AddCLIOption(flagDef FlagDef) (err error)

func AppendErr ¶

func AppendErr(errs []error, err error) []error

func BuildCommandTree ¶

func BuildCommandTree() (err error)

BuildCommandTree builds the command hierarchy from registrations This should be called by gmover.Initialize() after all init() functions complete

func CallInitializerFuncs ¶

func CallInitializerFuncs(args InitializerArgs) (err error)

func CombineErrs ¶

func CombineErrs(errs []error) error

CombineErrs bundles a slice of errors into a single composite error that unwraps to its members. Order is preserved and nils are skipped. Returns nil for an empty/fully-nil slice, or the sole error when there is exactly one.

func ErrValue ¶

func ErrValue[T any](err error, key string) (T, bool)

ErrValue extracts a single metadata value by key with type safety. Returns the value and true if found and the value is of type T. Returns the zero value of T and false if not found or type mismatch.

Example:

status, ok := doterr.ErrValue[int](err, "http_status")
if ok {
    fmt.Printf("Status: %d\n", status)
}

name, ok := doterr.ErrValue[string](err, "parameter_name")

func Errorf ¶

func Errorf(format string, args ...any)

Errorf writes to formatted error writer

func Errors ¶

func Errors(err error) []error

Errors returns the errors stored on a doterr entry. If err is a doterr entry, returns its errors. If err is a joined error (has Unwrap() []error), scans immediate children left-to-right and returns errors from the first doterr entry found. Otherwise returns nil. The returned slice preserves insertion order and is a copy.

Note: These errors may be sentinel errors (e.g., ErrRepo), custom error types (e.g., *rfc9457.Error), or any other error type stored in the entry.

func FindErr ¶

func FindErr[T error](err error) (out T, ok bool)

FindErr walks an error tree (including errors.Join trees) and returns the first match for target (via errors.As).

func Initialize ¶

func Initialize(w Writer) (err error)

func IsTerminalError ¶

func IsTerminalError(err error) (isTermErr bool)

IsTerminalError checks if an error is related to terminal/input operations These errors should abort the entire operation rather than continue

func NewErr ¶

func NewErr(parts ...any) error

NewErr builds a standalone structured entry (no primary cause inside). Accepted parts:

• error — sentinel/tag (required: at least one, must be first)
• KV{Key,Value} — explicit key/value
• "key", value — implicit pair (value can be any type, including error)
• error — optional trailing cause (joined last via errors.Join)

Pattern: one or more sentinels (error), then zero or more key-value pairs, then optional trailing cause (error). After the first string key, all remaining args must form valid pairs, except for an optional final error. Returns nil if no meaningful parts are provided after validation. Returns a validation error joined with the partial entry if validation fails.

func Printf ¶

func Printf(format string, args ...any)

Printf writes formatted writer

func RegisterCommand ¶

func RegisterCommand(cmd Command, parents ...Command) (err error)

RegisterCommand registers a command with optional parent type declarations First argument is the actual command, remaining arguments are parent type prototypes Example: RegisterCommand(&JobRunCmd{...}, &JobCmd{})

func RegisterInitializerFunc ¶

func RegisterInitializerFunc(f InitializerFunc)

func SetWriter ¶

func SetWriter(w Writer)

SetWriter sets the global writer writer (primarily for testing)

func ShowCmdHelp ¶

func ShowCmdHelp(cmdName string, args UsageArgs) (err error)

ShowCmdHelp displays help for a specific command

func ShowMainHelp ¶

func ShowMainHelp(args UsageArgs) error

ShowMainHelp displays the main help screen

func Stderrf ¶

func Stderrf(format string, args ...any)

func Stdiof ¶

func Stdiof(w io.Writer, format string, args ...any)

func Stdoutf ¶

func Stdoutf(format string, args ...any)

func ValidateCmds ¶

func ValidateCmds() (err error)

ValidateCmds ensures all registered commands have handlers

func ValidateCommands ¶

func ValidateCommands() (err error)

func WithErr ¶

func WithErr(parts ...any) error

WithErr is a flexible enrichment helper. Typical uses:

// Enrich an existing composite error (err may be an errors.Join tree):
err = doterr.With(err, "Foo", 10)

// Build an entry and join a trailing cause in one shot:
err = doterr.With("endpoint", ep, ErrTemplate, cause) // 'cause' is last

Behavior:

1. If the FIRST arg is an error, it is treated as the base error to enrich: • If it is a doterr entry, merge KVs/sentinels into that entry. • If it is a multi-unwrap (errors.Join tree), find the RIGHTMOST doterr entry, merge into it, and rebuild preserving order. • If no doterr entry is found, a new entry will be joined in (see step 3).

2. After consuming the base (if present), if the LAST remaining arg is an error, it is treated as the CAUSE and joined LAST.

3. The remaining middle args (if any) are collected into an entry. If we enriched an existing doterr entry in step 1, that merged entry is used; otherwise, a fresh entry is created. If there is a trailing CAUSE from step 2, the result is errors.Join(entry, cause). If there is no cause, the entry is returned.

Note: For inter-function composition, prefer New() with trailing cause:

return doterr.New(ErrRepo, "key", val, cause) // cause last