Documentation
¶
Overview ¶
Package cmdutil provides reusable CLI helper functions for Cobra commands. Both the open-source CLI and private overlays import this package to avoid duplicating flag validation, time parsing, and UX helpers.
Index ¶
- Constants
- Variables
- func ConfirmDelete(cmd *cobra.Command, resourceType, resourceName string) bool
- func DetectNumericTypeError(err error) (flagName, badValue string, ok bool)
- func FlagOrFallback(cmd *cobra.Command, primary string, aliases ...string) string
- func GroupRunE(cmd *cobra.Command, args []string) error
- func HintSubCmd(use, hint string) *cobra.Command
- func IsGroup(cmd *cobra.Command) bool
- func LevenshteinDist(a, b string) int
- func LevenshteinThreshold(nameLen int) int
- func MarkGroup(cmd *cobra.Command)
- func MustFlagOrFallback(cmd *cobra.Command, primary string, aliases ...string) (string, error)
- func MustFlagWithHint(cmd *cobra.Command, name, example string) (string, error)
- func MustGetFlag(cmd *cobra.Command, name string) string
- func OverridePriority(cmd *cobra.Command) int
- func ParseISOTimeToMillis(flagName, value string) (int64, error)
- func SetOverridePriority(cmd *cobra.Command, priority int)
- func SuffixLooksLikeValue(suffix, typ, format string, enum []string) bool
- func ValidateRequiredFlagWithAliases(cmd *cobra.Command, primary string, aliases ...string) error
- func ValidateRequiredFlags(cmd *cobra.Command, names ...string) error
- func ValidateTimeRange(startMs, endMs int64) error
- func VisibleFlagNames(cmd *cobra.Command) []string
- type FlagFixResult
Constants ¶
const KindAnnotation = "dws.kind"
KindAnnotation is the annotation key for marking command kinds.
const KindGroup = "group"
KindGroup marks a command created as a group container.
const OverridePriorityAnnotation = "dws.override-priority"
OverridePriorityAnnotation is the cobra.Command.Annotations key used to declare a command's merge-time override priority. Higher values win when same-named leaves collide during merge. Exported so overlays and helpers can reference the same key as the core merge logic without spelling drift.
Variables ¶
var CommonFlagAliases = map[string]string{
"json": "format json",
"output": "format",
"out": "format",
"o": "format",
"silent": "quiet",
"dry": "dry-run",
"force": "yes",
"f": "yes",
"timeout-seconds": "timeout",
"device-flow": "device",
"deviceflow": "device",
}
CommonFlagAliases maps commonly misused flag names to their correct equivalents.
var FlexTimeLayouts = []string{ time.RFC3339, "2006-01-02T15:04:05Z", "2006-01-02T15:04:05-07:00", "2006-01-02T15:04:05", "2006-01-02 15:04:05", "2006-01-02T15:04", "2006-01-02 15:04", "2006-01-02", "2006/01/02 15:04:05", "2006/01/02", "20060102", }
FlexTimeLayouts is the ordered list of time formats tried by ParseISOTimeToMillis.
Functions ¶
func ConfirmDelete ¶
ConfirmDelete asks for interactive confirmation before destructive operations. Returns true if --yes/-y flag is set or the user types "yes"/"y".
func DetectNumericTypeError ¶
DetectNumericTypeError checks if err is a Cobra/pflag numeric type validation error. Returns the flag name and the bad value if detected.
func FlagOrFallback ¶
FlagOrFallback reads the primary flag; if empty, falls back through alias flags in order, returning the first non-empty value.
func GroupRunE ¶
GroupRunE is a reusable RunE for parent (group) commands that have no business logic of their own. With args it returns an error listing available subcommands; without args it shows help.
func HintSubCmd ¶
HintSubCmd creates a hidden subcommand that only prints a disambiguation hint.
func LevenshteinDist ¶
LevenshteinDist returns the edit distance between two strings.
func LevenshteinThreshold ¶
LevenshteinThreshold returns the max edit distance allowed based on string length.
func MustFlagOrFallback ¶
MustFlagOrFallback works like FlagOrFallback but returns an error when all flags are empty.
func MustFlagWithHint ¶
MustFlagWithHint returns an error with an explicit usage example when the flag is empty.
func MustGetFlag ¶
MustGetFlag retrieves a string flag value, checking both local and inherited flags.
func OverridePriority ¶ added in v1.0.16
OverridePriority returns the override priority annotation value on cmd, or 0 if the annotation is absent or malformed.
func ParseISOTimeToMillis ¶
ParseISOTimeToMillis parses a time string into a millisecond Unix timestamp. Supports RFC3339, UTC Z, timezone-less, space-separated, date-only, and more. When the input lacks an explicit timezone, Asia/Shanghai is assumed.
func SetOverridePriority ¶ added in v1.0.16
SetOverridePriority stamps the override priority annotation on cmd. A positive value asks the merge layer to promote this command over a same-named leaf with a lower (or unset) priority.
func SuffixLooksLikeValue ¶ added in v1.0.27
SuffixLooksLikeValue decides whether a candidate suffix from a glued "--flagsuffix" token plausibly represents a value for a flag's declared type/format/enum. Shared by StickyHandler (PreParse) and SuggestFlagFix (unknown-flag recovery).
typ is a pflag value type string (e.g. "int", "bool", "string"); format is JSON Schema "format" when present (e.g. "date-time"); enum is the schema enum list when present.
func ValidateRequiredFlagWithAliases ¶
ValidateRequiredFlagWithAliases checks that at least one of the primary flag or its aliases is non-empty.
func ValidateRequiredFlags ¶
ValidateRequiredFlags checks that all named string flags are non-empty. Returns a formatted error listing all missing flags, or nil.
func ValidateTimeRange ¶
ValidateTimeRange checks that endMs is strictly after startMs.
func VisibleFlagNames ¶ added in v1.0.27
VisibleFlagNames returns sorted candidate flag names for cmd.Flags() using flagFixCandidate. Intended for agent-facing error recovery (available_flags).
Types ¶
type FlagFixResult ¶
FlagFixResult holds the result of SuggestFlagFix analysis.
func SuggestFlagFix ¶
func SuggestFlagFix(cmd *cobra.Command, flagErr error) FlagFixResult
SuggestFlagFix detects flag-value concatenation errors, common flag aliases, and Levenshtein-close typos.
Source Files