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 Commander

Usage

import (
    ns "github.com/hashibuto/nilshell"
)

config := ns.ReaderConfig{

    CompletionFunction: func(beforeCursor string, afterCursor string, full string) *ns.Suggestions {
        // This is where you would return tab completion suggestions based on the input before the cursor, perhaps after the
        // cursor, or even the entire line buffer.

        return &ns.Suggestions{
            Total: 0
            Items: []*ns.Suggestion{}
        }
    },

    ProcessFunction: func(text string) error {
        // text contains the command to be processed by your own command interpreter
        return nil
    }

    // implement your own history manager if you want to persist history across multiple invocations, or use the default (nil)
	HistoryManager: nil,

    PromptFunction: func() string {
        // Return a prompt with terminal escape chars to add style

        return "$ "
    }
	Debug: false,

    // enable the log file to dump debugging info to a tailable log file
    LogFile: "",
}

r := NewReader(config)

// block until the process captures SIGINT or SIGTERM
r.ReadLoop()

Documentation

Index

• Constants
• Variables
• func CalculateColumnWidth(allText []string, screenWidth int, minColumns int, gutterWidth int) (int, int)
• type BasicHistoryIterator
  • func (bhi *BasicHistoryIterator) Backward() string
  • func (bhi *BasicHistoryIterator) Forward() string
• type BasicHistoryManager
  • func NewBasicHistoryManager(maxKeep int) *BasicHistoryManager
  • func (h *BasicHistoryManager) Exit()
  • func (h *BasicHistoryManager) GetIterator() HistoryIterator
  • func (h *BasicHistoryManager) Push(value string)
  • func (h *BasicHistoryManager) Search(pattern string) []string
• type CompletionFunc
• type FileLock
  • func NewFileLock(filename string) *FileLock
  • func (fl *FileLock) Lock() error
  • func (fl *FileLock) Unlock() error
• type HistoryIterator
• type HistoryManager
• type PersistedHistoryManager
  • func NewPersistedHistoryManager(maxKeep int, filename string) *PersistedHistoryManager
  • func (pm *PersistedHistoryManager) Exit()
  • func (pm *PersistedHistoryManager) Push(value string)
• type Position
• type Reader
  • func NewReader(config ReaderConfig) *Reader
  • func (r *Reader) GetWindowSize() *Size
  • func (r *Reader) MoveCursorToRenderEnd(renderLength int)
  • func (r *Reader) MoveCursorToRenderStart()
  • func (r *Reader) ReadLoop() error
  • func (r *Reader) SetEditCursorPosition(prompt string, offset ...int)
• type ReaderConfig
• type Size
• type Suggestion
• type Suggestions

Constants

const (
	KEY_CTRL_C      = "\x03" // Signal interrupt
	KEY_CTRL_D      = "\x04" // Signal EOF
	KEY_CTRL_L      = "\x0C" // Clear terminal
	KEY_TAB         = "\x09"
	KEY_ENTER       = "\x0D"
	KEY_CTRL_R      = "\x12" // Search backward
	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 (
	ErrInterrupt = errors.New("interrupt")
	ErrEof       = errors.New("eof")
)

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 BasicHistoryIterator

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

func (*BasicHistoryIterator) Backward

func (bhi *BasicHistoryIterator) Backward() string

func (*BasicHistoryIterator) Forward

func (bhi *BasicHistoryIterator) Forward() string

type BasicHistoryManager

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

func NewBasicHistoryManager

func NewBasicHistoryManager(maxKeep int) *BasicHistoryManager

func (*BasicHistoryManager) Exit

func (h *BasicHistoryManager) Exit()

func (*BasicHistoryManager) GetIterator

func (h *BasicHistoryManager) GetIterator() HistoryIterator

func (*BasicHistoryManager) Push

func (h *BasicHistoryManager) Push(value string)

func (*BasicHistoryManager) Search

func (h *BasicHistoryManager) Search(pattern string) []string

type CompletionFunc

type CompletionFunc func(beforeCursor string, afterCursor string, full string) *Suggestions

type FileLock

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

func NewFileLock

func NewFileLock(filename string) *FileLock

func (*FileLock) Lock

func (fl *FileLock) Lock() error

func (*FileLock) Unlock

func (fl *FileLock) Unlock() error

type HistoryIterator

type HistoryIterator interface {
	Backward() string
	Forward() string
}

type HistoryManager

type HistoryManager interface {
	Exit()
	GetIterator() HistoryIterator
	Push(string)
	Search(string) []string
}

type PersistedHistoryManager

type PersistedHistoryManager struct {
	*BasicHistoryManager
	// contains filtered or unexported fields
}

func NewPersistedHistoryManager

func NewPersistedHistoryManager(maxKeep int, filename string) *PersistedHistoryManager

func (*PersistedHistoryManager) Exit

func (pm *PersistedHistoryManager) Exit()

func (*PersistedHistoryManager) Push

func (pm *PersistedHistoryManager) Push(value string)

type Position

type Position struct {
	Row    int
	Column int
}

type Reader

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

func NewReader

func NewReader(config ReaderConfig) *Reader

func (*Reader) GetWindowSize

func (r *Reader) GetWindowSize() *Size

func (*Reader) MoveCursorToRenderEnd

func (r *Reader) MoveCursorToRenderEnd(renderLength int)

func (*Reader) MoveCursorToRenderStart

func (r *Reader) MoveCursorToRenderStart()

func (*Reader) ReadLoop

func (r *Reader) ReadLoop() error

ReadLoop reads commands from the standard input and blocks until exit

func (*Reader) SetEditCursorPosition

func (r *Reader) SetEditCursorPosition(prompt string, offset ...int)

type ReaderConfig

type ReaderConfig struct {
	CompletionFunction CompletionFunc
	ProcessFunction    func(string) error
	HistoryManager     HistoryManager
	PromptFunction     func() string
	Debug              bool
	LogFile            string
}

type Size

type Size struct {
	Rows    int
	Columns int
}

type Suggestion

type Suggestion struct {
	Display string
	Value   string
}

type Suggestions

type Suggestions struct {
	Total int // reflects the total (could be longer than len(.Items)
	Items []*Suggestion
}