goprogram

type AfterParseCommand[E any, P any, F any, R Requirement[F]] interface {
	Command[E, P, F, R]

	// AfterParse is called after arguments have been parsed, but before the command is being run.
	// It may perform additional argument checking and should return an error if needed.
	//
	// It is called only once and must return either nil or an error of type Error.
	AfterParse() error
}

type Alias struct {
	// Name is the name of this alias
	Name string

	// Command to invoke along with arguments
	Command string
	Args    []string

	// Description for the usage page
	Description string
}

type Arguments[F any] struct {
	Universals Universals `group:"universals"`
	Flags      F          `group:"flags"`

	Command string // command to run
	// contains filtered or unexported fields
}

type Command[E any, P any, F any, R Requirement[F]] interface {
	// Run runs this command in the given context.
	//
	// It is called only once and must return either nil or an error of type Error.
	Run(context Context[E, P, F, R]) error

	// Description returns a description of this command.
	// It may be called multiple times.
	Description() Description[F, R]
}

type Context[E any, P any, F any, R Requirement[F]] struct {
	stream.IOStream // IOStream describes the input and output the command reads from and writes to.
	Context         context.Context

	// Args holds arguments passed to this command.
	Args Arguments[F]

	// Description is the description of the command being invoked
	Description Description[F, R]
	// Environment holds the environment for this command.
	Environment E

	// Program is the current program this command is executing under
	Program Program[E, P, F, R]
	// contains filtered or unexported fields
}

type ContextCleanupFunc[E any, P any, F any, R Requirement[F]] func(context *Context[E, P, F, R])

type Description[F any, R Requirement[F]] struct {
	// Command and Description the name and human-readable description of this command.
	// Command must not be taken by any other command registered with the corresponding program.
	Command     string
	Description string

	ParserConfig parser.Config // information about how to configure a parser for this command

	// Requirements on the environment to be able to run the command
	Requirements R
}

type EmptyRequirement[F any] struct{}

type Keyword[F any] func(args *Arguments[F], pos *[]string) error

type Program[E any, P any, F any, R Requirement[F]] struct {
	// Meta-information about the current program
	// Used to generate help and version pages
	Info meta.Info

	// The NewContext function is called to create a new context for a command.
	// It may optionally return a ContextCleanupFunc.
	//
	// It is passed the parameters as well as a parent context.
	// The parameters are only passed when Main() is invoked; otherwise they are the zero value.
	//
	// The parent context is either a new context, or the context from the parent command this command was invoked from.
	//
	// To access the full context object within the NewContext function, use GetContext.
	//
	// When NewContext is nil, the parent context is used.
	//
	// If the context is closed before a command would be invoked, then the command is not invoked.
	//
	// See also [env.NewOSContext].
	NewContext func(params *P, parent context.Context) (context.Context, ContextCleanupFunc[E, P, F, R], error)

	// The NewEnvironment function is used to create a new environment.
	// The returned error must be nil or of type exit.Error.
	//
	// NewEnvironment may be nil, in which case a new environment is assumed to be
	// the zero value of type E.
	NewEnvironment func(params P, context Context[E, P, F, R]) (E, error)

	// BeforeKeyword, BeforeAlias and BeforeCommand (if non-nil) are invoked right before their respective datum is executed.
	// They are intended to act as a guard before executing a particular datum.
	//
	// The returned error must be nil or of type exit.Error.
	// When non-nil, the error is returned to the caller of Main().
	BeforeKeyword func(context Context[E, P, F, R], keyword Keyword[F]) error
	BeforeAlias   func(context Context[E, P, F, R], alias Alias) error
	BeforeCommand func(context Context[E, P, F, R], command Command[E, P, F, R]) error
	// contains filtered or unexported fields
}

type Requirement[F any] interface {
	// AllowsFlag checks if the provided flag may be passed to fullfil this requirement
	// By default it is used only for help page generation, and may be inaccurate.
	AllowsFlag(flag meta.Flag) bool

	// Validate validates if this requirement is fulfilled for the provided global flags.
	// It should return either nil, or an error of type exit.Error.
	//
	// Validate does not take into account AllowsOption, see ValidateAllowedOptions.
	Validate(arguments Arguments[F]) error
}

type Universals struct {
	Help    bool `short:"h" long:"help" description:"print a help message and exit"`
	Version bool `short:"v" long:"version" description:"print a version message and exit"`
}