disambiguate

Documentation

Overview

Package disambiguate provides Symfony-style command prefix matching and colon notation for Cobra CLI applications.

This package enables shorthand command syntax like "c:v" → "config validate", with case-insensitive prefix matching and optional interactive disambiguation.

Basic usage:

rootCmd := &cobra.Command{Use: "mytool"}
// ... add commands ...

// Pre-process args for colon notation
args := os.Args[1:]
if len(args) > 0 && strings.Contains(args[0], ":") {
	resolved, matches, err := disambiguate.ResolveColonPath(rootCmd, args[0])
	if err == nil {
		rootCmd.SetArgs(append(resolved, args[1:]...))
	}
}

Index

• func FormatAmbiguousError(prefix string, matches []CommandMatch) string
• func FormatMatchNames(matches []CommandMatch) string
• func IsInteractive() bool
• type CommandMatch
  • func FindPrefixMatches(parent *cobra.Command, prefix string) []CommandMatch
  • func FindPrefixMatchesInPath(root *cobra.Command, prefix string) []CommandMatch
  • func ResolveColonPath(root *cobra.Command, path string) ([]string, []CommandMatch, error)
  • func SelectCommand(matches []CommandMatch, prefix string) (*CommandMatch, error)

Functions

func FormatAmbiguousError

func FormatAmbiguousError(prefix string, matches []CommandMatch) string

FormatAmbiguousError returns a formatted error message for ambiguous commands.

func FormatMatchNames

func FormatMatchNames(matches []CommandMatch) string

FormatMatchNames returns a comma-separated list of command names.

func IsInteractive

func IsInteractive() bool

IsInteractive returns true if stdin is a terminal (TTY).

Types

type CommandMatch

type CommandMatch struct {
	Command     *cobra.Command // The matched Cobra command
	MatchedName string         // The name that matched (command name)
	Path        []string       // Full path for subcommands (e.g., ["config", "validate"])
}

CommandMatch represents a command that matches a prefix.

func FindPrefixMatches

func FindPrefixMatches(parent *cobra.Command, prefix string) []CommandMatch

FindPrefixMatches finds all available commands matching the given prefix. Matching is case-insensitive.

An empty prefix matches all available commands.

func FindPrefixMatchesInPath

func FindPrefixMatchesInPath(root *cobra.Command, prefix string) []CommandMatch

FindPrefixMatchesInPath searches for commands matching the prefix at any level of the command tree. It returns all unique command paths that match.

func ResolveColonPath

func ResolveColonPath(root *cobra.Command, path string) ([]string, []CommandMatch, error)

ResolveColonPath resolves a colon-separated command path like "c:v" to ["config", "validate"].

Returns:

• resolved: the resolved path segments
• matches: ambiguous matches at the last level (empty if unambiguous)
• error: if resolution fails

If the path is unambiguous, the matches slice will be empty. If ambiguous, the caller can use SelectCommand for interactive selection.

func SelectCommand

func SelectCommand(matches []CommandMatch, prefix string) (*CommandMatch, error)

SelectCommand prompts the user to select from matching commands. Returns an error if not in interactive mode or user cancels.