cli

type Action func(args []string, options map[string]string) int

type App interface {
	// Description returns the application description to be output in the usage.
	Description() string
	// Args returns required and optional positional arguments for the top-level application.
	Args() []Arg
	// Options permitted for the top-level application and all sub-commands.
	Options() []Option
	// Commands returns the set of first-level sub-commands for the application.
	Commands() []Command
	// Action returns the application action when no sub-command is specified.
	Action() Action

	// WithArg adds a positional argument to the application. Specifying last application/command
	// argument as optional permits unlimited number of further positional arguments (at least one
	// optional argument needs to be specified in the definition for this case).
	WithArg(arg Arg) App
	// WithOption adds a permitted option to the application and all sub-commands.
	WithOption(opt Option) App
	// WithCommand adds a first-level sub-command to the application.
	WithCommand(cmd Command) App
	// WithAction sets the action function to execute after successful parsing of commands, arguments
	// and options to the top-level application.
	WithAction(action Action) App

	// Parse parses the original application arguments into the command invocation path (application ->
	// first level command -> second level command etc.), a list of validated positional arguments matching
	// the command being invoked (the last one in the invocation path) and a map of validated options
	// matching one of the invocation path elements, from the top application down to the command being invoked.
	// An error is returned if a command is not found or arguments or options are invalid. In case of an error,
	// the invocation path is normally also computed and returned (the content of arguments and options is not
	// guaranteed).
	Parse(appargs []string) (invocation []string, args []string, opts map[string]string, err error)
	// Run parses the argument list and runs the command specified with the corresponding options and arguments.
	Run(appargs []string, w io.Writer) int
	// Usage prints out the full usage help.
	Usage(invocation []string, w io.Writer) error
}

type Arg interface {
	// Key defines how the argument will be shown in the usage string.
	Key() string
	// Description returns the description of the argument usage
	Description() string
	// Type defines argument type. Default is string, which is not validated,
	// other types are validated by simple string parsing into boolean, int and float.
	Type() ValueType
	// Optional specifies that an argument may be omitted. No non-optional arguments
	// should follow an optional one (no validation for this scenario as this is
	// the definition time exception, rather than incorrect input at runtime).
	Optional() bool

	// WithType sets the argument type.
	WithType(at ValueType) Arg
	// AsOptional sets the argument as optional.
	AsOptional() Arg
}

type Command interface {
	// Key returns the command name.
	Key() string
	// Shortcut returns the command shortcut if not empty.
	Shortcut() string
	// Description returns the command description to be output in the usage.
	Description() string
	// Args returns required and optional positional arguments for this command.
	Args() []Arg
	// Options permitted for this command and its sub-commands.
	Options() []Option
	// Commands returns the set of sub-commands for this command.
	Commands() []Command
	// Action returns the command action when no further sub-command is specified.
	Action() Action

	// WithShortcut adds a (shorter) command alias, e.g. `co` for `checkout`.
	WithShortcut(shortcut string) Command
	// WithArg adds a positional argument to the command. Specifying last application/command
	// argument as optional permits unlimited number of further positional arguments (at least one
	// optional argument needs to be specified in the definition for this case).
	WithArg(arg Arg) Command
	// WithOption adds a permitted option to the command and all sub-commands.
	WithOption(opt Option) Command
	// WithCommand adds a next-level sub-command to the command.
	WithCommand(cmd Command) Command
	// WithAction sets the action function for this command.
	WithAction(action Action) Command
}

type Option interface {
	// Key returns the complete key of an option (used with the -- notation), required.
	Key() string
	// CharKey returns a single-character key of an option (used with the - notation), optional.
	CharKey() rune
	// Description returns the option description for the usage string.
	Description() string
	// Type returns the option type (string by default) to be used to decide if a value is required and for
	// value validation.
	Type() ValueType

	// WithChar sets the char key for the option.
	WithChar(char rune) Option
	// WithType sets the option value type.
	WithType(ft ValueType) Option
}

type ValueType int