charli

type Action int

type AmbiguousValueError struct {
	Option    *Option // the [Option] in question
	OptionArg string  // the first argument (which triggered the [Option])
	Value     string  // the second argument (which is ambiguous)
}

type App struct {
	// Headline is the text displayed at the top of help output,
	// above the 'Usage:' line.
	//
	// Text surrounded by {curly braces} will be highlighted.
	Headline string

	// Description is a longer description of the app,
	// which may be several paragraphs long.
	//
	// If using only a single command, this won't be displayed.
	// Instead, set [Command.Description].
	//
	// In global help output, this is displayed below the 'Usage:' line.
	// Each line will be indented by 2 spaces.
	//
	// It should start and end with a newline `\n`.
	// This is because it's designed to be written using a raw string literal,
	// with each backtick on a separate line, like this:
	//
	//  const description = `
	//  This is the first paragraph.
	//
	//  This is the second paragraph.
	//  `
	//
	// The text won't be automatically justified when printed.
	// Generally, it should be pre-justified at 78 characters
	// (to make up for the 2-space indent).
	//
	// Text surrounded by {curly braces} will be highlighted.
	Description string

	// Commands configures the app's [Command]s,
	// in the order they should be displayed in help output.
	//
	// If only one command is configured,
	// the parser won't require a command name will be supplied at all,
	// and [Command.Name] should be omitted.
	// Otherwise, all commands must have a name.
	//
	// Commands must not have duplicate names.
	Commands []Command

	// GlobalOptions configures [Option]s that apply to every command in
	// [App.Commands].
	// They are effectively prepended to every [Command.Options] slice.
	//
	// Note that unless [App.HelpAccess] explicitly removes it,
	// `-h/--help` is always available.
	// The help flags override any flag with `-h` or `--help` that you may
	// configure.
	GlobalOptions []Option

	// DefaultCommand is the name of the command to run if none is supplied.
	// If blank, the parser will require a command.
	//
	// Note that setting a default can introduce some ambiguity
	// where the first supplied argument isn't an option
	// (ie. it doesn't start with `-`).
	//
	// If only one command is configured,
	// this must be blank.
	DefaultCommand string

	// HelpAccess specifies how users can access help.
	//
	// This is a bitmask.
	// It should be [HelpFlag], [HelpCommand], or both.
	//
	// If nothing is supplied, it will default to [HelpFlag].
	HelpAccess HelpAccess

	// ErrorHandler is a callback which, if set,
	// will handle [App.Parse] errors as they happen.
	//
	// If this *isn't* set,
	// errors will be aggregated in [Result.Errs].
	ErrorHandler func(error)

	// HighlightColor is the color used for highlighting in help output.
	//
	// To disable color, don't use this.
	// Instead, set [github.com/fatih/color.NoColor] to true.
	HighlightColor color.Attribute
}

type Args struct {
	// Count is the number of required positional arguments.
	//
	// When parsing, if more positional arguments than Count are supplied,
	// those arguments are excluded from [Result.Args].
	//
	// If [Args.Varadic] is set, this becomes the *minimum* number of arguments.
	Count int

	// Varadic indicates whether to allow more positional arguments
	// than are specified in [Args.Count].
	Varadic bool

	// Metavars is a list of names for the positional arguments.
	//
	// Omitted metavars will default to `ARG`.
	//
	// They are displayed in the 'Usage:' line at the top of help output,
	// like `Usage: program ARG1 ARG2 ARG3`.
	//
	// They should be uppercase, but this is not a requirement.
	//
	// In help output, if [Args.Varadic] is true:
	//
	//   - `[--]` will be prepended.
	//   - Metavars with an index higher than [Args.Count] will be
	//     `[bracketed]`.
	//   - The last metavar will be ellipsized, like `ARG...`.
	Metavars []string
}

type CombinedEqualsError struct {
	Arg string // the combined argument in question
}

type CombinedValueError struct {
	Option      *Option // the [Option] in question
	Arg         string  // the option's name (as used in the combined argument)
	CombinedArg string  // the combined argument it is part of
}

type Command struct {
	// Name is the command name.
	//
	// It should be short (ideally a single word, or kebab-case if not).
	Name string

	// Headline is a one-line summary of the command.
	//
	// In global help output,
	// it is displayed alongside the command name in the 'Commands:' listing.
	// In command help output,
	// it is also displayed below the 'Usage:' line.
	//
	// Text surrounded by {curly braces} will be highlighted.
	Headline string

	// Description is a longer description of the command,
	// which may be several paragraphs long.
	// In command help output, it is displayed below the 'Usage:' line.
	// Each line will be indented by 2 spaces.
	//
	// It should start and end with a newline `\n`.
	// This is because it's designed to be written using a raw string literal,
	// with each backtick on a separate line, like this:
	//
	//  const description = `
	//  This is the first paragraph.
	//
	//  This is the second paragraph.
	//  `
	//
	// The text won't be automatically justified when printed.
	// Generally, it should be pre-justified at 78 characters
	// (to make up for the 2-space indent).
	//
	// Text surrounded by {curly braces} will be highlighted.
	Description string

	// Options is a slice of this command's unique [Option]s,
	// in order of display in command help output.
	// If [App.GlobalOptions] is set, those options will effectively be
	// prepended to this slice.
	//
	// Note that unless [App.HelpAccess] explicitly removes it,
	// `-h/--help` is always available.
	// The help flags override any flag with `-h` or `--help` that you may
	// configure.
	Options []Option

	// Args is the configuration for this command's positional arguments.
	//
	// If left blank, no positional arguments will be allowed.
	Args Args

	// Run is the function to execute if this Command is chosen.
	//
	// Supplying this function is actually entirely optional,
	// as it's up to you whether to call it.
	// You may wish to have an entirely different way of reacting to the
	// command the user has chosen.
	//
	// If you are supplying a Run function, it should:
	//
	//   - Validate the option values in the passed [Result].
	//   - Call [Result.Error] (or its other `Error*` functions) in the case
	//     of errors).
	//   - Return before doing any meaningful work if [Result.Fail] is true.
	//
	// [Result.Fail] may additionally be set by this function for any reason.
	//
	// Responsibility for processing and displaying [Result.Errs] should
	// generally be with the caller,
	// or you may wish to set [App.ErrorHandler].
	Run func(r *Result)
}

type DuplicateOptionError struct {
	Option      *OptionResult // the [OptionResult] set in the first instance
	Arg         string        // the argument in question
	CombinedArg string        // the combined argument it is part of (if applicable)

}

type HelpAccess uint8

type InvalidChoiceError struct {
	Option    *Option // the [Option] in question
	JoinedArg string  // the argument(s) in question, which may be concatenated
	Value     string  // the invalid value
}

type InvalidCommandError struct {
	Program     string     // the name of the program
	Name        string     // the name of the invalid command
	SuggestHelp HelpAccess // how to suggest CLI help is accessed
}

type InvalidOptionError struct {
	Arg         string // the invalid option's argument
	CombinedArg string // the combined argument it is part of (if applicable)
}

type MissingArgsError struct {
	Metavars []string // the metavars for the missing arguments
}

type MissingCommandError struct {
	Program    string     // the name of the program
	HelpAccess HelpAccess // how to suggest CLI help is accessed
}

type MissingValueError struct {
	Option  *Option // the [Option] in question
	Arg     string  // the argument that triggered the option
	Metavar string  // the option's metavar
}

type Option struct {
	// Short is the short option name. This and/or [Option.Long] must be set.
	//
	// Short options have a single hyphen followed by a character (like `-a`).
	// Omit the hyphen, as this is a rune.
	//
	// `-` isn't a valid value for this,
	// because `--` is a special argument used to disable option parsing.
	Short rune

	// Long is the long option name. This and/or [Option.Short] must be set.
	//
	// Long options have a double hyphen followed by a string (like `--option`).
	// Don't include the hyphens.
	Long string

	// Flag indicates whether this option should take no value.
	// Flags are effectively boolean.
	//
	// If true, the option will be listed without [Option.Metavar]
	// in help output (like `--option` rather than `--option ARG`).
	//
	// After parsing, in this option's [OptionResult],
	// [OptionResult.IsSet] can be used to check whether the flag was supplied.
	Flag bool

	// Choices constrains this option's values to a list.
	//
	// Available choices will be appended to the option's headline in help
	// output.
	// This should only be used for simple, short sets of strings.
	//
	// This is invalid if set on flags.
	Choices []string

	// Metavar is the term for this option's value. It is shown in help output
	// after the option name(s), like `VALUE` in `-o/--option VALUE`.
	//
	// If omitted, it will default to `ARG`.
	//
	// It should be uppercase, but this is not a requirement.
	//
	// It is invalid if set with [Option.Flag].
	Metavar string

	// Headline is a one-line summary of the option,
	// shown in the 'Options:' section of help output.
	//
	// Text surrounded by {curly braces} will be highlighted.
	Headline string
}

type OptionResult struct {
	// Option is the [Option] that this refers to.
	Option *Option

	// Value is the option's string value.
	// This may be blank if an empty value was supplied (like `--opt ”`) -
	// [OptionResult.IsSet] is preferable when checking whether an option
	// was supplied at all.
	//
	// If the option is a flag, this will always be blank.
	Value string

	// IsSet indicates whether the option was supplied.
	IsSet bool
}

type Result struct {
	// Action indicates what the parser suggests should happen next.
	// See [Action] for details.
	Action Action

	// Errs is a slice of all errors encountered during parsing.
	// You may choose to append errors from your own validations
	// using the [Result.Error] functions.
	//
	// Note that if [App.ErrorHandler] is set, this slice will not be appended
	// to automatically.
	// [App.ErrorHandler] may re-implement this behavior, if desired.
	Errs []error

	// Fail is true if any error has occurred during parsing.
	// If you are using the [Result.Error] functions in your own validations,
	// any call to those functions will set this to true.
	//
	// If true, it is suggested that the program exits with a failure code.
	//
	// Note also that it is valid for Fail to be true when [Result.Errs] is
	// empty - for example, when [Result.Action] is [Help], but extraneous
	// arguments were supplied.
	Fail bool

	// App is the [App] that [App.Parse] was called on.
	App *App

	// Command is the [Command] chosen by the user.
	// This may be nil when [Result.Action] != [Proceed].
	Command *Command

	// Options is a map of [Option] names to [OptionResult]s.
	//
	// Both [Option.Short] and [Option.Long] will be set as keys for the
	// [OptionResult] for a given [Option].
	// Don't prepend the hyphens in either case (ie. use `opt` as a key,
	// rather than `--opt`).
	Options map[string]*OptionResult

	// Args is a slice of the positional arguments.
	//
	// In the case of too many arguments being supplied,
	// `len(Args)` won't be more than [Args.Count] for the given [Command].
	// In other words, the extraneous args will be dropped.
	Args []string
}

type TooManyArgsError struct {
	Args []string // the extraneous arguments
}