ns

README

nilshell

Command shell for golang which provides a minimal line editor and command processing loop. Here's what you get with NilShell:

• Line editor (type, insert, delete)
• Command history (up/down to navigate, load/export)
• Reverse search (simple pattern match, most recent history first)
• Tab completion hook
• Handling of terminal resize

What it doesn't do

• Any sort of argument parsing / tokenization

For a full CLI parser implementation using nilshell, check out Artillery

Usage

import "github.com/hashibuto/nilshell"

ns := NewNilShell(
    "» ", 
    func(beforeCursor, afterCursor string, full string) []*ns.AutoComplete {
        // Autocompletion happens here, perhaps tokenization, and the last token before the cursor is
        // fed to a lookup to find potential matches
        return nil
    },
    func(ns *ns.NilShell, cmd string) {
        // Perform tokenization, command lookup, and execution
    },
)

// Attach saved command history
ns.History = NewHistory(myLoadedHistory)

ns.ReadUntilTerm()

// Save command history
myHistory := ns.History.Export()
// write myHistory it to disk

Documentation

Index

• Constants
• Variables
• func CalculateColumnWidth(allText []string, screenWidth int, minColumns int, gutterWidth int) (int, int)
• type AutoComplete
• type Completer
• type Executor
• type History
  • func NewHistory(maxKeep int, commands ...string) *History
  • func (h *History) Any() bool
  • func (h *History) Append(command string)
  • func (h *History) Export() []string
  • func (h *History) FindMostRecentMatch(subString string) string
  • func (h *History) Newer() string
  • func (h *History) Older() string
• type LineReader
  • func NewLineReader(completer Completer, resizeChan chan os.Signal, nilShell *NilShell) *LineReader
  • func (lr *LineReader) Read() (string, bool, error)
• type NilShell
  • func NewShell(prompt string, onComplete Completer, onExecute Executor) *NilShell
  • func (n *NilShell) Clear()
  • func (n *NilShell) ReadUntilTerm() error
  • func (n *NilShell) Shutdown()
• type ProcessingCode

Constants

const (
	KEY_CTRL_C      = "\x03"
	KEY_CTRL_D      = "\x04"
	KEY_CTRL_L      = "\x0C"
	KEY_TAB         = "\x09"
	KEY_ENTER       = "\x0D"
	KEY_CTRL_R      = "\x12"
	KEY_CTRL_T      = "\x14"
	KEY_ESCAPE      = "\x1B"
	KEY_BACKSPACE   = "\x7F"
	KEY_DEL         = "\x1B[3~"
	KEY_END         = "\x1B[F"
	KEY_HOME        = "\x1B[H"
	KEY_UP_ARROW    = "\x1B[A"
	KEY_DOWN_ARROW  = "\x1B[B"
	KEY_RIGHT_ARROW = "\x1B[C"
	KEY_LEFT_ARROW  = "\x1B[D"
)

Variables

var CODE_RESET = "\x1b[0m"

var EscapeFinder = regexp.MustCompile("\x1b\\[[^a-zA-Z]+[a-zA-Z]")

Functions

func CalculateColumnWidth

func CalculateColumnWidth(allText []string, screenWidth int, minColumns int, gutterWidth int) (int, int)

CalculateColumnWidth returns the column width and number of columns per row

Types

type AutoComplete

type AutoComplete struct {
	Value   string
	Display string
}

type Completer

type Completer func(beforeCursor string, afterCursor string, full string) []*AutoComplete

Completer receives a string of everything before the cursor, after the cursor, and the entire command string. It returns a list of potential suggestions according to the available command set. Completers are invoked when the user presses <tab>, the completion key.

type Executor

type Executor func(ns *NilShell, cmd string)

Executor is called when the <enter> key is pressed after inputting a command

type History

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

func NewHistory

func NewHistory(maxKeep int, commands ...string) *History

NewHistory creates a new history object with optional pre-loaded history

func (*History) Any

func (h *History) Any() bool

Any returns true if there are any commands in the history

func (*History) Append

func (h *History) Append(command string)

Append appends another command to the history

func (*History) Export

func (h *History) Export() []string

Export returns the command history

func (*History) FindMostRecentMatch

func (h *History) FindMostRecentMatch(subString string) string

FindMostRecentMatch returns the most recent command that contains subString, or an empty string

func (*History) Newer

func (h *History) Newer() string

Newer returns the next newest command in the history

func (*History) Older

func (h *History) Older() string

Older returns the next oldest command in the history

type LineReader

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

func NewLineReader

func NewLineReader(completer Completer, resizeChan chan os.Signal, nilShell *NilShell) *LineReader

NewLineReader creates a new LineReader object

func (*LineReader) Read

func (lr *LineReader) Read() (string, bool, error)

Read will read a single command from the command line and can be interrupted by pressing <enter>, <ctrl+c>, or <ctrl+d>. Read responds to changes in the terminal window size.

type NilShell

type NilShell struct {
	Prompt            string
	History           *History
	AutoCompleteLimit int // Maximum number of autocompletes to display
	Debug             bool

	AutoCompleteSuggestStyle string
	AutoCompleteTooMuchStyle string
	// contains filtered or unexported fields
}

func NewShell

func NewShell(prompt string, onComplete Completer, onExecute Executor) *NilShell

NewShell constructs a NilShell

func (*NilShell) Clear

func (n *NilShell) Clear()

Clear will clear the terminal - this can be safely invoked in an OnExecute method to implement a clear command

func (*NilShell) ReadUntilTerm

func (n *NilShell) ReadUntilTerm() error

ReadUntilTerm blocks, receiving commands until the user requests termination. Commands are processed via the executor callback provided at initialization time. Likewise for command completion.

func (*NilShell) Shutdown

func (n *NilShell) Shutdown()

Exit instructs the shell to gracefully exit - this can be safely invoked in an OnExecute method to implement a exit command

type ProcessingCode

type ProcessingCode int8

const (
	CodeContinue ProcessingCode = iota
	CodeComplete
	CodeCancel
	CodeTerminate
)