cli

README

go-cli

A Go based line editor and command line interface.

The line editing code is a port of the C based linenoise library.

See: http://github.com/antirez/linenoise

The line editor can be used standalone. The CLI makes use of the line editor.

Line Editing Features

• single line editing
• multiline editing
• input from files/pipes
• input from unsupported terminals
• history
• completions
• hints
• line buffer initialization: Set an initial buffer string for editing.
• hot keys: Set a special hot key for exiting line editing.
• loop functions: Call a function in a loop until an exit key is pressed.

CLI Features

• hierarchical menus
• command tab completion
• command history
• context sensitive help
• command editing

Examples

./examples/line/main.go

Matches the example code in the C version of the linenoise library.

./examples/cli/main.go

Implements an example of a heirarchical command line interface.

Documentation

Index

• Constants
• Variables
• func CheckArgc(args []string, valid []int) error
• func IntArg(arg string, limits [2]int, base int) (int, error)
• func TableString(rows [][]string, csize []int, cmargin int) string
• func UintArg(arg string, limits [2]uint, base int) (uint, error)
• type CLI
  • func NewCLI(user USER) *CLI
  • func (c *CLI) DisplayHistory(args []string) string
  • func (c *CLI) Exit()
  • func (c *CLI) GeneralHelp()
  • func (c *CLI) HistoryLoad(path string)
  • func (c *CLI) HistorySave(path string)
  • func (c *CLI) Loop(fn func() bool, exitKey rune) bool
  • func (c *CLI) Put(s string)
  • func (c *CLI) Run()
  • func (c *CLI) Running() bool
  • func (c *CLI) SetLine(line string)
  • func (c *CLI) SetPrompt(prompt string)
  • func (c *CLI) SetRoot(root []MenuItem)
• type Help
• type Hint
• type Leaf
• type Linenoise
  • func NewLineNoise() *Linenoise
  • func (l *Linenoise) HistoryAdd(line string)
  • func (l *Linenoise) HistoryLoad(fname string)
  • func (l *Linenoise) HistorySave(fname string)
  • func (l *Linenoise) HistorySetMaxlen(n int)
  • func (l *Linenoise) Loop(fn func() bool, exitKey rune) bool
  • func (l *Linenoise) PrintKeycodes()
  • func (l *Linenoise) Read(prompt, init string) (string, error)
  • func (l *Linenoise) SetCompletionCallback(fn func(string) []string)
  • func (l *Linenoise) SetHintsCallback(fn func(string) *Hint)
  • func (l *Linenoise) SetHotkey(key rune)
  • func (l *Linenoise) SetMultiline(mode bool)
• type Menu
• type MenuItem
• type USER

Constants

const (
	KeycodeNull  = 0
	KeycodeCtrlA = 1
	KeycodeCtrlB = 2
	KeycodeCtrlC = 3
	KeycodeCtrlD = 4
	KeycodeCtrlE = 5
	KeycodeCtrlF = 6
	KeycodeCtrlH = 8
	KeycodeTAB   = 9
	KeycodeLF    = 10
	KeycodeCtrlK = 11
	KeycodeCtrlL = 12
	KeycodeCR    = 13
	KeycodeCtrlN = 14
	KeycodeCtrlP = 16
	KeycodeCtrlT = 20
	KeycodeCtrlU = 21
	KeycodeCtrlW = 23
	KeycodeESC   = 27
	KeycodeBS    = 127
)

Keycodes

Variables

var ErrQuit = errors.New("quit")

ErrQuit is returned when the user has quit line editing.

var HistoryHelp = []Help{
	{"<cr>", "display all history"},
	{"<index>", "recall history entry <index>"},
}

HistoryHelp is help for the history command.

Functions

func CheckArgc

func CheckArgc(args []string, valid []int) error

CheckArgc returns an error if the argument count is not in the valid set.

func IntArg

func IntArg(arg string, limits [2]int, base int) (int, error)

IntArg converts a number string to an integer.

func TableString

func TableString(
	rows [][]string,
	csize []int,
	cmargin int,
) string

TableString returns a string for a table of row by column strings. Each column string will be left justified and aligned.

func UintArg

func UintArg(arg string, limits [2]uint, base int) (uint, error)

UintArg converts a number string to an unsigned integer.

Types

type CLI

type CLI struct {
	User USER // user provided object
	// contains filtered or unexported fields
}

CLI stores the CLI state.

func NewCLI

func NewCLI(user USER) *CLI

NewCLI returns a new CLI object.

func (*CLI) DisplayHistory

func (c *CLI) DisplayHistory(args []string) string

DisplayHistory displays the command history.

func (*CLI) Exit

func (c *CLI) Exit()

Exit the CLI.

func (*CLI) GeneralHelp

func (c *CLI) GeneralHelp()

GeneralHelp displays general help.

func (*CLI) HistoryLoad

func (c *CLI) HistoryLoad(path string)

HistoryLoad loads command history from a file.

func (*CLI) HistorySave

func (c *CLI) HistorySave(path string)

HistorySave saves command history to a file.

func (*CLI) Loop

func (c *CLI) Loop(fn func() bool, exitKey rune) bool

Loop is a passthrough to the wait for hotkey Loop().

func (*CLI) Put

func (c *CLI) Put(s string)

Put is a passthrough to the user provided Put().

func (*CLI) Run

func (c *CLI) Run()

Run gets and processes a CLI command.

func (*CLI) Running

func (c *CLI) Running() bool

Running returns true if the CLI is running.

func (*CLI) SetLine

func (c *CLI) SetLine(line string)

SetLine sets the next command line.

func (*CLI) SetPrompt

func (c *CLI) SetPrompt(prompt string)

SetPrompt sets the command prompt.

func (*CLI) SetRoot

func (c *CLI) SetRoot(root []MenuItem)

SetRoot sets the menu root.

type Help

type Help struct {
	Parm  string // parameter
	Descr string // description
}

Help is a parameter help element.

type Hint

type Hint struct {
	Hint  string
	Color int
	Bold  bool
}

Hint is used to provide hint information to the line editor.

type Leaf

type Leaf struct {
	Descr string               // description
	F     func(*CLI, []string) // leaf function
}

Leaf is a leaf function within menu hierarchy.

type Linenoise

type Linenoise struct {
	// contains filtered or unexported fields
}

Linenoise stores line editor state.

func NewLineNoise

func NewLineNoise() *Linenoise

NewLineNoise returns a new line editor.

func (*Linenoise) HistoryAdd

func (l *Linenoise) HistoryAdd(line string)

HistoryAdd adds a new entry to the history.

func (*Linenoise) HistoryLoad

func (l *Linenoise) HistoryLoad(fname string)

HistoryLoad loads history from a file.

func (*Linenoise) HistorySave

func (l *Linenoise) HistorySave(fname string)

HistorySave saves the history to a file.

func (*Linenoise) HistorySetMaxlen

func (l *Linenoise) HistorySetMaxlen(n int)

HistorySetMaxlen sets the maximum length for the history. Truncate the current history if needed.

func (*Linenoise) Loop

func (l *Linenoise) Loop(fn func() bool, exitKey rune) bool

Loop calls the provided function in a loop. Exit when the function returns true or when the exit key is pressed. Returns true when the loop function completes, false for early exit.

func (*Linenoise) PrintKeycodes

func (l *Linenoise) PrintKeycodes()

PrintKeycodes prints scan codes on the screen for debugging/development purposes.

func (*Linenoise) Read

func (l *Linenoise) Read(prompt, init string) (string, error)

Read a line. Return nil on EOF/quit.

func (*Linenoise) SetCompletionCallback

func (l *Linenoise) SetCompletionCallback(fn func(string) []string)

SetCompletionCallback sets the completion callback function.

func (*Linenoise) SetHintsCallback

func (l *Linenoise) SetHintsCallback(fn func(string) *Hint)

SetHintsCallback sets the hints callback function.

func (*Linenoise) SetHotkey

func (l *Linenoise) SetHotkey(key rune)

SetHotkey sets the hotkey that causes line editing to exit. The hotkey will be appended to the line buffer but not displayed.

func (*Linenoise) SetMultiline

func (l *Linenoise) SetMultiline(mode bool)

SetMultiline sets multiline editing mode.

type Menu

type Menu []MenuItem

Menu is a set of menu items.

type MenuItem

type MenuItem []interface{}

MenuItem has 3 forms: {name string, submenu Menu, description string}: reference to submenu {name string, leaf func}: leaf command with generic <cr> help {name string, leaf func, help []Help}: leaf command with specific argument help

type USER

type USER interface {
	Put(s string)
}

USER is an interface for low-level UI operations. A user provide object with this interface is passed to each leaf function.