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)
• func PadRight(text string, width int, gutter int) string
• 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 = "\033[0m"

var EscapeFinder = regexp.MustCompile("\033\\[[^m]+m")

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

func PadRight

func PadRight(text string, width int, gutter int) string

PadRight will pad text with blank space on the right, leaving up to gutter characters unused. If text is longer than width - gutter, it will be terminated with an ellipsis, up to the gutter line.

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
)