spec.go

package cli

// Spec is implemented by the generated by the `cli` code generator.
type Spec interface {
	Cmd() *Cmd
	Run()
}

// Cmd holds metadata related to a CLI command.
//
// Usually generated by the `cli` code generator.
type Cmd struct {
	// RawName is the raw, unprocessed  name of the function.
	RawName string
	// RawDoc is the raw, unprocessed doc string attached to the function.
	RawDoc string
	// Args describes metadata about the function arguments.
	Args []*Arg
	// Opts describes metadata about the function options
	// (the `opt` argument, by convention).
	Opts []*Opt

	// The fields below are normally set by Enrich.

	// Name is the command name,
	// normally determined by parsing the raw function name and/or doc.
	Name string
	// Path is the path to this subcommand,
	// normally determined by parsing the raw function name and/or docs.
	Path []string
	// Doc is the function doc after processing,
	// where annotations such as  "Deprecated" and "Hidden" are removed.
	Doc string
	// Synopsis is a short description of the command.
	Synopsis string
	// Example describes an example of how to use the command.
	Example string
	// Deprecated marks this command as deprecated and contains
	// a message describing why.
	Deprecated string
	// Hidden marks this command as hidden.
	Hidden bool
	// Aliases contains aliases for this command.
	Aliases []string
}

// Opt holds metadata related to an option of a Cmd.
//
// Usually generated by the `cli` code generator.
type Opt struct {
	// Key is the path of struct fields names from the root to this option.
	// e.g. ["Server", "TLS", "KeyPath"]
	Key []string
	// RawDoc is the raw, unprocessed doc string attached to this field.
	RawDoc string

	// The fields below are normally set by Enrich.

	// Doc is the field doc after processing,
	// where annotations such as  "Deprecated" and "Hidden" are removed.
	Doc string
	// Synopsis is a short description of this option.
	Synopsis string
	// Hidden marks this option as hidden.
	Hidden bool
	// Deprecated marks this option as deprecated and contains
	// a message describing why.
	Deprecated string
	// Type contains a string describing the type of this field,
	// e.g. "[]string".
	Type string
	// Short is the name of the short version of a flag for this option.
	Short string
	// Value contains a pointer to the value for this option.
	// Used by Loader machinery to set the value of this option.
	Value interface{}
	// DefaultValue contains the default value of this option.
	DefaultValue interface{}
	// DefaultString contains a more human-friendly description
	// of the default value, e.g. os.Stderr instead of io.Writer.
	DefaultString string
	// IsSet is true if this value has been set.
	// Used by Loader machinery.
	// TODO ugly.
	IsSet bool
}

// Arg defines a positional argument of a Cmd.
//
// Usually generated by the `cli` code generator.
type Arg struct {
	// Name is the name of this argument.
	Name string
	// Type contains a string describing the type of this field,
	// e.g. "[]string".
	Type string
	// Variadic is true if this function argument is variadic,
	// e.g. func example(a string, b ...string)
	// "b" is variadic.
	Variadic bool
	// Value contains a pointer to the value for this argument.
	// Used by `cli` machinery to set the value of this argument.
	Value interface{}
}