conq

type Cmd ¶

type Cmd struct {
	Name     string
	Commands []*Cmd
	Run      func(Ctx) error
	Opts     Opts
	Args     Opts
	Env      Opts
	Version  string
}

Cmd is a node in a rooted node tree describing a command-hierarchy.

type CmdHelp ¶

type CmdHelp struct {
	// Filter for the subjects that will considered in help-generation.
	// An interesting usecase could be to skip non-runnable commands or select for
	// a certain depth in the tree.
	Select HelpSelector
	// Articles contains templates for generating helptexts using cmdhelp.HelpContext.
	Articles fs.FS
}

CmdHelp details how this command is to be treated by help/assistance commands

type Commander ¶

type Commander interface {
	ResolveCmd(root *Cmd, ctx Ctx) Ctx
	Execute(root *Cmd, ctx Ctx) error
	Optioner() Optioner
}

type Ctx ¶

type Ctx struct {
	In       io.Reader
	Out, Err io.Writer
	Args     []string
	Values   map[string]any
	Strings  map[string]string
	Printer  *message.Printer
	Path     Pth
	Com      Commander
}

Ctx is the context in which a command (Cmd) runs. It contains the std-streams, arguments (options extracted before calling Cmd.Run), option-values, the path within the command-tree this invocation is located in and a locale-aware message-printer.

func OSContext(args ...string) Ctx

type HelpSelector ¶

type HelpSelector func(*Cmd, HelpSubject, Helper, string) (accept, recurse bool)

HelpSelector is a func that is used when walking the command-tree to assemble only the subjects the selector accepts into the helptext.

package main

import (
	"github.com/patroclos/go-conq"
)

func main() {

	var _ conq.HelpSelector = func(c *conq.Cmd, hs conq.HelpSubject, h conq.Helper, s string) (accept bool, recurse bool) {
		return true, false
	}
}

Output:

type HelpSubject ¶

type HelpSubject struct {
	Cmd *Cmd
	Opt *O
	Ctx *Ctx
}

HelpSubject represents a command&option-tree node that is subject to a help query.

type Helper ¶

type Helper interface {
	Help(HelpSubject) string
}

Helper provides a helptexts for nodes in the command&options tree.

type O ¶

type O struct {
	// a comma-separated list of at least one name followed by aliases
	Name string
	// should invoking a command fail, if this option isn't set?
	Require bool
	// a parser for the string extracted from the shell arguments
	Parse func(string) (any, error)
	// describes the type of results returned by Parse
	Type reflect.Type
	// shell-completion
	Predict complete.Predictor
}

O is a descriptor for command-parameters (options, positional arguments or environment variables)

func (o O) WithName(name string) O

type Opt ¶

type Opt[T any] O

Opt[T any] wraps a base-option (usually only containing a name) in an Opter interface, which will apply defaults to O.Parse and O.Type values. The default O.Parse implementation will use the github.com/alexflint/go-scalar package to parse a (value T) from a string. The default implementations supports the encoding.TextUnmarshaler interface. Opt[T] is meant both as the definition for the option and as the access-hatch for it's values, so it provides `Get(Ctx)(T,error)` and `Getp(Ctx)(*T, error)` to access the options value or pointer to it from the Ctx.Values map.

func (o Opt[T]) Get(c Ctx) (val T, err error)

func (o Opt[T]) Getp(c Ctx) (val *T, err error)

func (o Opt[T]) Opt() O

type Opter ¶

type Opter interface {
	Opt() O
}

This interface exists to facilitate the Opt[T] and ReqOpt[T] types with filter effects

type Optioner ¶

type Optioner interface {
	ExtractOptions(Ctx, ...Opter) (Ctx, error)
	CompleteOptions(completion.Context, ...Opter) []string
}

Optioner provides extraction and completion of CLI options.

type Opts ¶

type Opts []Opter

type Pth ¶

type Pth []*Cmd

type ReqOpt ¶

type ReqOpt[T any] O

ReqOpt[T any] is a simple wrapper for Opt[T]. It's Opter implementation sets the O.Require to true. Assuming the Cmd has been setup correctly we can now know for sure that the Ctx is going to have a value for this option. That's why the `Get(Ctx)T` and `Getp(Ctx)*T` have been simplified from their counterparts in Opt[T]

func (o ReqOpt[T]) Get(c Ctx) (val T)

func (o ReqOpt[T]) Getp(c Ctx) (val *T)

func (o ReqOpt[T]) Opt() O