ishell

README

ishell

ishell is an interactive shell library for creating interactive cli applications.

Usage

import "github.com/abiosoft/ishell"

func main(){
    // create new shell.
    // by default, new shell includes 'exit', 'help' and 'clear' commands.
    shell := ishell.NewShell()

	// display welcome info.
	shell.Println("Sample Interactive Shell")

	// register a function for "greet" command.
    shell.Register("greet", func(args ...string) (string, error) {
        name := "Stranger"
        if len(args) > 0 {
            name = strings.Join(args, " ")
        }
		return "Hello "+name, nil
	})

	// start shell
	shell.Start()
}

Execution

Sample Interactive Shell
>> help
Commands:
exit help greet
>> greet Someone Somewhere
Hello Someone Somewhere
>> exit
$

Reading input.

// simulate an authentication
shell.Register("login", func(args ...string) (string, error) {
	// disable the '>>' for cleaner same line input.
	shell.ShowPrompt(false)
	defer shell.ShowPrompt(true) // yes, revert after login.

    // get username
	shell.Print("Username: ")
	username := shell.ReadLine()

    // get password. Does not echo characters.
	shell.Print("Password: ")
	password := shell.ReadPassword(false)

	... // do something with username and password

    return "Authentication Successful.", nil
})

Execution

>> login
Username: someusername
Password:
Authentication Successful.

How about multiline input.

shell.Register("multi", func(args ...string) (string, error) {
	shell.Println("Input some lines:")
	// read until a semicolon ';' is found
	lines := shell.ReadMultiLines(";")
	shell.Println("You wrote:")
	return lines, nil
})

Execution

>> multi
Input some lines:
>> this is a sample 
>> of multiline input;
You wrote:
this is a sample
of multiline input;

Check example code for more.

Note

ishell is in active development and can still change significantly.

Roadmap (in no particular order)

• Support multiline inputs.
• Handle ^C interrupts.
• Support coloured outputs.
• Command history.
• Tab completion.
• Testing, testing, testing.

Contribution

1. Create an issue to discuss it.
2. Send in Pull Request.

License

MIT

Credits

Library	Use
github.com/flynn/go-shlex	splitting input into command and args.
github.com/howeyc/gopass	reading passwords.

Documentation

Overview

Package ishell implements an interactive shell.

Index

• func ExitErr(err string) error
• func NewErr(err string, level ErrLevel) error
• func PanicErr(err string) error
• func StopErr(err string) error
• func WarnErr(err string) error
• type CmdFunc
• type ErrLevel
• type Shell
  • func NewShell() *Shell
  • func (s *Shell) Active() bool
  • func (s *Shell) ClearScreen() error
  • func (s *Shell) Commands() []string
  • func (s *Shell) IgnoreCase(ignore bool)
  • func (s *Shell) Print(val ...interface{})
  • func (s *Shell) PrintCommands()
  • func (s *Shell) Println(val ...interface{})
  • func (s *Shell) ReadLine() string
  • func (s *Shell) ReadMultiLines(terminator string) string
  • func (s *Shell) ReadMultiLinesFunc(f func(string) bool) string
  • func (s *Shell) ReadPassword(mask bool) string
  • func (s *Shell) Register(command string, function CmdFunc)
  • func (s *Shell) RegisterGeneric(function CmdFunc)
  • func (s *Shell) SetOut(writer io.Writer)
  • func (s *Shell) SetPrompt(prompt string)
  • func (s *Shell) ShowPrompt(show bool)
  • func (s *Shell) Start()
  • func (s *Shell) Stop()
  • func (s *Shell) Unregister(command string)

Functions

func ExitErr

func ExitErr(err string) error

ExitErr creates a Exit level error. Program terminates if encountered.

func NewErr

func NewErr(err string, level ErrLevel) error

NewErr creates a new error with specified level

func PanicErr

func PanicErr(err string) error

PanicErr creates a Panic level error. Program panics if encountered.

func StopErr

func StopErr(err string) error

StopErr creates a Stop level error. Shell stops if encountered.

func WarnErr

func WarnErr(err string) error

WarnErr creates a Warn level error

Types

type CmdFunc

type CmdFunc func(args ...string) (output string, err error)

CmdFunc represents a command function that is called after an input to the shell. The shell input is split into command and arguments like cli args and the arguments are passed to this function. The shell will print output if output != "".

type ErrLevel

type ErrLevel int

ErrLevel is the severity of an error.

const (
	LevelWarn ErrLevel = iota + 1
	LevelStop
	LevelExit
	LevelPanic
)

type Shell

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

func NewShell

func NewShell() *Shell

NewShell creates a new shell with default settings. Uses standard output and default prompt ">>".

func (*Shell) Active

func (s *Shell) Active() bool

Active tells if the shell is active. i.e. Start is previously called.

func (*Shell) ClearScreen

func (s *Shell) ClearScreen() error

ClearScreen clears the screen. Same behaviour as running 'clear' in unix terminal or 'cls' in windows cmd.

func (*Shell) Commands

func (s *Shell) Commands() []string

Commands returns a sorted list of all registered commands.

func (*Shell) IgnoreCase

func (s *Shell) IgnoreCase(ignore bool)

IgnoreCase specifies whether commands should not be case sensitive. Defaults to false i.e. commands are case sensitive. If true, commands must be registered in lower cases. e.g. shell.Register("cmd", ...)

func (*Shell) Print

func (s *Shell) Print(val ...interface{})

Print prints to output.

func (*Shell) PrintCommands

func (s *Shell) PrintCommands()

PrintCommands prints a space separated list of registered commands to the shell.

func (*Shell) Println

func (s *Shell) Println(val ...interface{})

Println prints to output and ends with newline character.

func (*Shell) ReadLine

func (s *Shell) ReadLine() string

ReadLine reads a line from standard input.

func (*Shell) ReadMultiLines

func (s *Shell) ReadMultiLines(terminator string) string

ReadMultiLines reads multiple lines from standard input. It stops reading when terminator is encountered at the end of the line. It returns the lines read including terminator. For more control, use ReadMultiLinesFunc.

func (*Shell) ReadMultiLinesFunc

func (s *Shell) ReadMultiLinesFunc(f func(string) bool) string

ReadMultiLinesFunc reads multiple lines from standard input. It passes each read line to f and stops reading when f returns false.

func (*Shell) ReadPassword

func (s *Shell) ReadPassword(mask bool) string

ReadPassword reads password from standard input without echoing the characters. If mask is true, each character will be represented with asterisks '*'. Note that this only works as expected when the standard input is a terminal.

func (*Shell) Register

func (s *Shell) Register(command string, function CmdFunc)

Register registers a function for command. It overwrites existing function, if any.

func (*Shell) RegisterGeneric

func (s *Shell) RegisterGeneric(function CmdFunc)

RegisterGeneric registers a generic function for all inputs. It is called if the shell input could not be handled by any of the registered functions. Unlike Register, the entire line is passed as first argument to CmdFunc.

func (*Shell) SetOut

func (s *Shell) SetOut(writer io.Writer)

SetOut sets the writer to write outputs to.

func (*Shell) SetPrompt

func (s *Shell) SetPrompt(prompt string)

SetPrompt sets the prompt string. The string to be displayed before the cursor.

func (*Shell) ShowPrompt

func (s *Shell) ShowPrompt(show bool)

ShowPrompt sets whether prompt should show when requesting input for ReadLine and ReadPassword. Defaults to true.

func (*Shell) Start

func (s *Shell) Start()

Start starts the shell. It reads inputs from standard input and calls registered functions accordingly. This function blocks until the shell is stopped.

func (*Shell) Stop

func (s *Shell) Stop()

Stop stops the shell. This will stop the shell from auto reading inputs and calling registered functions. A stopped shell is only inactive but totally functional. Its functions can still be called.

func (*Shell) Unregister

func (s *Shell) Unregister(command string)

Unregister unregisters a function for a command