standalone

Documentation

Overview

Package standalone holds the input handling shared by standalone scripts that declare their own command-line interface: value parsing, positional validation, help annotations, and usage errors.

Index

• Constants
• func AnnotateFlags(set *pflag.FlagSet, declared []flags.Flag)
• func CheckBoolPositional(set *pflag.FlagSet, argv []string) error
• func DefaultName(filename string) string
• func DescribeArguments(cmd *cobra.Command, specs []*flags.PositionalArgSpec)
• func LabelListFlags(set *pflag.FlagSet)
• func NewUsageError(cmd *cobra.Command, invoked string, cause error) error
• func ParseDecimalInt(raw string) (int, error)
• func ParseStringList(raw string) ([]string, error)
• func ValidatePositionals(specs []*flags.PositionalArgSpec, positional []string) error
• type DecimalInt
  • func NewDecimalInt(initial int) *DecimalInt
  • func (v *DecimalInt) Set(raw string) error
  • func (v *DecimalInt) String() string
  • func (v *DecimalInt) Type() string
• type ValueError
  • func (e *ValueError) Error() string
  • func (e *ValueError) Is(target error) bool
  • func (e *ValueError) Unwrap() error

Constants

const UsageExitCode = 2

UsageExitCode is the exit status for command-line input a script's interface does not accept, matching the convention of Atmos's own usage errors.

Functions

func AnnotateFlags

func AnnotateFlags(set *pflag.FlagSet, declared []flags.Flag)

AnnotateFlags appends what the help output would otherwise omit to each declared flag's description: whether it is required, its allowed values, and the environment variable bound to it.

func CheckBoolPositional

func CheckBoolPositional(set *pflag.FlagSet, argv []string) error

CheckBoolPositional rejects a true/false word that directly follows a boolean flag. Boolean flags never consume the next word, so `--verbose false` would silently turn the flag on and pass "false" as a positional argument.

func DefaultName

func DefaultName(filename string) string

DefaultName derives a command name from a script filename by dropping the extension, so help reads `Usage: tool [flags]` rather than `Usage: tool.star [flags]`. The result follows the same character rules as an explicit command name.

func DescribeArguments

func DescribeArguments(cmd *cobra.Command, specs []*flags.PositionalArgSpec)

DescribeArguments adds an Arguments section to the command's help. Required arguments appear as <name> and optional ones as [name], matching the usage line. Arguments without a description are listed by name only, and a command with no arguments gets no section.

func LabelListFlags

func LabelListFlags(set *pflag.FlagSet)

LabelListFlags renames the displayed type of string-list flags from `strings` to `list`. It replaces the flags' values, so call it only once parsing is finished and the values are no longer read.

func NewUsageError

func NewUsageError(cmd *cobra.Command, invoked string, cause error) error

NewUsageError presents a failure to parse the user's command line as a usage error rather than a script failure. The invoked argument is the script as the user typed it, so the hint can be copied as-is.

func ParseDecimalInt

func ParseDecimalInt(raw string) (int, error)

ParseDecimalInt parses raw as a base-10 integer, for both command-line and environment values.

func ParseStringList

func ParseStringList(raw string) ([]string, error)

ParseStringList splits a list value the way pflag's StringSlice does for command-line values: comma-separated, with CSV quoting for items that contain commas. An empty value is an empty list.

func ValidatePositionals

func ValidatePositionals(specs []*flags.PositionalArgSpec, positional []string) error

ValidatePositionals checks the number of positional values against the declared arguments and names the first missing required argument.

Types

type DecimalInt

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

DecimalInt is a pflag.Value for integer flags. Unlike pflag's own integer flags it accepts only base-10 digits, so `010` is ten and `0x10` is rejected instead of being read as octal or hex.

func NewDecimalInt

func NewDecimalInt(initial int) *DecimalInt

NewDecimalInt creates a DecimalInt holding the flag's default value.

func (*DecimalInt) Set

func (v *DecimalInt) Set(raw string) error

Set parses a base-10 integer.

func (*DecimalInt) String

func (v *DecimalInt) String() string

String returns the current value in decimal, which is the text pflag reads typed values from.

func (*DecimalInt) Type

func (v *DecimalInt) Type() string

Type names the flag type shown in help output.

type ValueError

type ValueError struct {
	Reason string
	Cause  error
}

ValueError reports why a flag value was rejected. Its message is the bare reason: the callers that surface it add the flag name and, for environment values, the variable, so a sentinel prefix here would repeat in the output. It still satisfies errors.Is(err, ErrInvalidFlagValue).

func (*ValueError) Error

func (e *ValueError) Error() string

Error returns the reason alone.

func (*ValueError) Is

func (e *ValueError) Is(target error) bool

Is makes every value error satisfy ErrInvalidFlagValue.

func (*ValueError) Unwrap

func (e *ValueError) Unwrap() error

Unwrap exposes the underlying parse error, if any.