kommandant

README

Kommandant README
=================

== Fetching from the repository ==

go get gitlab.com/ianbruene/Kommandant

== Purpose ==

Kommandant exists to ease the creation of command line interfaces for Go
programs. It is a near-port of Python's cmd module, with the caveat that
Go is a compiled language and cannot do introspection as easily. Despite
this mismatch the useful concepts are still useful after translation, and
the user-visible behavior will be the same.

== How To ==

link:kommandant-HOWTO.adoc[How To]

== Example Code ==

Example code can be found in the demos/ directory. It can be run with:

go run path/to/kommandant/demos/demo-readline.go

== Related projects ==

People who need an emulation of Python cmd are also likely
to find these useful:

https://github.com/ianbruene/go-difflib[go-difflib]::
	Much of Python's difflib ported to Go.

https://gitlab.com/esr/gogetopt::
	Python getopt ported to Go.

https://gitlab.com/esr/pytogo[pytogo]::
	A fast, rough, incomplete, but useful Python to Go translator.

https://github.com/chzyer/readline::
	Readline workalike that can be used to translate Python raw_input().

// end

Documentation

Index

• Constants
• func PcItemDynamicRecursive(callback readline.DynamicCompleteFunc) readline.PrefixCompleterInterface
• func ReadToDelimiter(r io.Reader, delimiter byte) (s string, err error)
• type Kmdt
  • func NewKommandant(handlers KmdtClient) *Kmdt
  • func NewKommandantDebug(handlers KmdtClient, debug uint) *Kmdt
  • func (k *Kmdt) CmdLoop(ctx context.Context, intro string)
  • func (k *Kmdt) Default(ctx context.Context, lineIn string) (stopOut bool)
  • func (k *Kmdt) DoHelp(ctx context.Context, argIn string) (stopOut bool)
  • func (k *Kmdt) EmptyLine(ctx context.Context) (stopOut bool)
  • func (k *Kmdt) EnableReadline(enable bool) (err error)
  • func (k *Kmdt) GetPrompt() (prompt string)
  • func (k *Kmdt) GetStdin() (stdin io.ReadCloser)
  • func (k *Kmdt) GetStdout() (stdout io.Writer)
  • func (k *Kmdt) OneCmd(ctx context.Context, lineIn string) (stopOut bool)
  • func (k *Kmdt) OneCmd_core(ctx context.Context, lineIn string) (stopOut bool)
  • func (k *Kmdt) ParseLine(lineIn string) (cmd string, arg string, lineOut string)
  • func (k *Kmdt) PostCmd(ctx context.Context, stopIn bool, lineIn string) (stopOut bool)
  • func (k *Kmdt) PostLoop(ctx context.Context)
  • func (k *Kmdt) PreCmd(ctx context.Context, lineIn string) (lineOut string)
  • func (k *Kmdt) PreLoop(ctx context.Context)
  • func (k *Kmdt) Readline() (line string, err error)
  • func (k *Kmdt) ReadlineEnabled() (enabled bool)
  • func (k *Kmdt) SetPrompt(prompt string)
  • func (k *Kmdt) SetStdin(stdin io.ReadCloser)
  • func (k *Kmdt) SetStdout(stdout io.Writer)
  • func (k *Kmdt) Write(data []byte)
  • func (k *Kmdt) WriteString(data string)
• type KmdtClient
• type RecursiveCompleter
  • func (r *RecursiveCompleter) Do(line []rune, pos int) (newLine [][]rune, length int)
  • func (r *RecursiveCompleter) GetChildren() []readline.PrefixCompleterInterface
  • func (r *RecursiveCompleter) GetDynamicNames(line []rune) [][]rune
  • func (r *RecursiveCompleter) GetName() []rune
  • func (r *RecursiveCompleter) IsDynamic() bool
  • func (r *RecursiveCompleter) Print(prefix string, level int, buf *bytes.Buffer)
  • func (r *RecursiveCompleter) SetChildren(children []readline.PrefixCompleterInterface)

Constants

const (
	NODEBUG = iota
	ERROR
	INFO
	DEBUG
	DEEPDEBUG
)

Debug levels

Functions

func PcItemDynamicRecursive

func PcItemDynamicRecursive(callback readline.DynamicCompleteFunc) readline.PrefixCompleterInterface

func ReadToDelimiter

func ReadToDelimiter(r io.Reader, delimiter byte) (s string, err error)

Performs the same function as bufio's ReadString without the gluttony

Types

type Kmdt

type Kmdt struct {
	Debug        uint
	Sub          KmdtClient // The struct which will have all the handlers
	CommandQueue []string
	Intro        string
	LastCmd      string
	Ruler        string
	DocLeader    string
	DocHeader    string
	UnDocHeader  string
	MiscHeader   string
	NoHelp       string

	// Characters used in command names
	IdentChars string
	// Special hooks
	// =============
	// Hook run in place of OneCmd if present
	OneCmdHook func(ctx context.Context, lineIn string) (stopOut bool)
	// Hook executed once when the cmdloop() method is called.
	PreLoopHook func(ctx context.Context)
	// Hook executed once when the cmdloop() method is about to return.
	PostLoopHook func(ctx context.Context)
	// Hook executed just before the command line is interpreted, but after
	// the input prompt is generated and issued.
	PreCmdHook func(ctx context.Context, lineIn string) (lineOut string)
	// Hook executed just after a command dispatch is finished.
	PostCmdHook func(ctx context.Context, stopIn bool, lineIn string) (stopOut bool)
	// Called when an empty line is entered in response to the prompt.
	// If this is not set, the last nonempty command entered will be repeated.
	EmptyLineHook func(ctx context.Context) (stopOut bool)
	// Called on an input line when the command prefix is not recognized.
	// If this is not set, an error message is printed and it and returns.
	DefaultHook func(ctx context.Context, lineIn string) (stopOut bool)
	// Function called to complete an input line when no command-specific
	// complete function is available. By default, it returns an empty list.
	CompleteDefaultHook func(line string) (options []string)
	// contains filtered or unexported fields
}

func NewKommandant

func NewKommandant(handlers KmdtClient) *Kmdt

func NewKommandantDebug

func NewKommandantDebug(handlers KmdtClient, debug uint) *Kmdt

func (*Kmdt) CmdLoop

func (k *Kmdt) CmdLoop(ctx context.Context, intro string)

Repeatedly issue a prompt, accept input, parse an initial prefix off the received input, and dispatch to action methods, passing them the remainder of the line as argument.

func (*Kmdt) Default

func (k *Kmdt) Default(ctx context.Context, lineIn string) (stopOut bool)

func (*Kmdt) DoHelp

func (k *Kmdt) DoHelp(ctx context.Context, argIn string) (stopOut bool)

func (*Kmdt) EmptyLine

func (k *Kmdt) EmptyLine(ctx context.Context) (stopOut bool)

func (*Kmdt) EnableReadline

func (k *Kmdt) EnableReadline(enable bool) (err error)

func (*Kmdt) GetPrompt

func (k *Kmdt) GetPrompt() (prompt string)

func (*Kmdt) GetStdin

func (k *Kmdt) GetStdin() (stdin io.ReadCloser)

func (*Kmdt) GetStdout

func (k *Kmdt) GetStdout() (stdout io.Writer)

func (*Kmdt) OneCmd

func (k *Kmdt) OneCmd(ctx context.Context, lineIn string) (stopOut bool)

func (*Kmdt) OneCmd_core

func (k *Kmdt) OneCmd_core(ctx context.Context, lineIn string) (stopOut bool)

Interpret the argument as though it had been typed in response to the prompt.

func (*Kmdt) ParseLine

func (k *Kmdt) ParseLine(lineIn string) (cmd string, arg string, lineOut string)

Parse the line into a command name and a string containing the arguments. Returns a tuple containing (command, args, line). 'command' and 'args' may be None if the line couldn't be parsed.

func (*Kmdt) PostCmd

func (k *Kmdt) PostCmd(ctx context.Context, stopIn bool, lineIn string) (stopOut bool)

func (*Kmdt) PostLoop

func (k *Kmdt) PostLoop(ctx context.Context)

func (*Kmdt) PreCmd

func (k *Kmdt) PreCmd(ctx context.Context, lineIn string) (lineOut string)

func (*Kmdt) PreLoop

func (k *Kmdt) PreLoop(ctx context.Context)

func (*Kmdt) Readline

func (k *Kmdt) Readline() (line string, err error)

func (*Kmdt) ReadlineEnabled

func (k *Kmdt) ReadlineEnabled() (enabled bool)

func (*Kmdt) SetPrompt

func (k *Kmdt) SetPrompt(prompt string)

func (*Kmdt) SetStdin

func (k *Kmdt) SetStdin(stdin io.ReadCloser)

func (*Kmdt) SetStdout

func (k *Kmdt) SetStdout(stdout io.Writer)

func (*Kmdt) Write

func (k *Kmdt) Write(data []byte)

func (*Kmdt) WriteString

func (k *Kmdt) WriteString(data string)

type KmdtClient

type KmdtClient interface {
	SetCore(k *Kmdt)
}

type RecursiveCompleter

type RecursiveCompleter struct {
	Completer      readline.PrefixCompleter
	MaxRecurse     int
	CurrentRecurse int
}

The normal readline completion handling requires a seperate dynamic callback for each layer of the completion. This allows the same callback to handle multiple arguments on a single command.

func (*RecursiveCompleter) Do

func (r *RecursiveCompleter) Do(line []rune, pos int) (newLine [][]rune, length int)

func (*RecursiveCompleter) GetChildren

func (r *RecursiveCompleter) GetChildren() []readline.PrefixCompleterInterface

func (*RecursiveCompleter) GetDynamicNames

func (r *RecursiveCompleter) GetDynamicNames(line []rune) [][]rune

func (*RecursiveCompleter) GetName

func (r *RecursiveCompleter) GetName() []rune

func (*RecursiveCompleter) IsDynamic

func (r *RecursiveCompleter) IsDynamic() bool

func (*RecursiveCompleter) Print

func (r *RecursiveCompleter) Print(prefix string, level int, buf *bytes.Buffer)

func (*RecursiveCompleter) SetChildren

func (r *RecursiveCompleter) SetChildren(children []readline.PrefixCompleterInterface)