README
¶
ishell
ishell is an interactive shell library for creating interactive cli applications.
Usage
import "strings"
import "github.com/abiosoft/ishell"
func main(){
// create new shell.
// by default, new shell includes 'exit', 'help' and 'clear' commands.
shell := ishell.New()
// 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.
shell.Print("Password: ")
password := shell.ReadPassword()
... // do something with username and password
return "Authentication Successful.", nil
})
Execution
>>> login
Username: someusername
Password:
Authentication Successful.
Multiline input.
Builtin support for multiple lines.
>>> This is \
... multi line
>>> Cool that << EOF
... everything here goes
... as a single argument.
... EOF
User defined
shell.Register("multi", func(args ...string) (string, error) {
shell.Println("Input some lines:")
// read until a semicolon ';' is found
// use shell.ReadMultiLinesFunc for more control.
lines := shell.ReadMultiLines(";")
shell.Println("You wrote:")
return lines, nil
})
Execution
>>> multi
Input some lines:
>>> this is user defined
... multiline input;
You wrote:
this is user defined
multiline input;
Keyboard interrupt.
Builtin interrupt handler.
>>> ^C
Input Ctrl-C once more to exit
>>> ^C
Interrupted
exit status 1
Custom
shell.RegisterInterrupt(func(args ...string) (string, error) { ... })
Durable history.
// Read and write history to $HOME/.ishell_history
shell.SetHomeHistoryPath(".ishell_history")
Check example code for more.
Supported Platforms
- Linux
- OSX
- Windows
Note
ishell is in active development and can still change significantly.
Roadmap (in no particular order)
- Support multiline inputs.
- Command history.
- Tab completion.
- Handle ^C interrupts.
- Subcommands and help texts.
- Coloured outputs.
- Testing, testing, testing.
Contribution
- Create an issue to discuss it.
- Send in Pull Request.
License
MIT
Credits
| Library | Use |
|---|---|
| github.com/flynn/go-shlex | splitting input into command and args. |
| gopkg.in/readline.v1 | history, tab completion and reading passwords. |
Documentation
¶
Overview ¶
Package ishell implements an interactive shell.
Index ¶
- func ExitErr(err string) error
- func PanicErr(err string) error
- func StopErr(err string) error
- func WarnErr(err string) error
- type CmdFunc
- type 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() string
- func (s *Shell) Register(command string, function CmdFunc)
- func (s *Shell) RegisterGeneric(function CmdFunc)
- func (s *Shell) RegisterInterrupt(function CmdFunc)
- func (s *Shell) SetHistoryPath(path string) error
- func (s *Shell) SetHomeHistoryPath(path string)
- func (s *Shell) SetMultiPrompt(prompt string)
- 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)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CmdFunc ¶
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 Shell ¶
type Shell struct {
// contains filtered or unexported fields
}
Shell is an interactive cli shell.
func New ¶
func New() *Shell
New creates a new shell with default settings. Uses standard output and default prompt ">> ".
func (*Shell) ClearScreen ¶
ClearScreen clears the screen. Same behaviour as running 'clear' in unix terminal or 'cls' in windows cmd.
func (*Shell) IgnoreCase ¶
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) 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) ReadMultiLines ¶
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 ¶
ReadMultiLinesFunc reads multiple lines from standard input. It passes each read line to f and stops reading when f returns false.
func (*Shell) ReadPassword ¶
ReadPassword reads password from standard input without echoing the characters. Note that this only works as expected when the standard input is a terminal.
func (*Shell) Register ¶
Register registers a function for command. It overwrites existing function, if any.
func (*Shell) RegisterGeneric ¶
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) RegisterInterrupt ¶
RegisterInterrupt registers a function to handle keyboard interrupt.
func (*Shell) SetHistoryPath ¶
SetHistoryPath sets where readlines history file location. Use an empty string to disable history file. It is empty by default.
func (*Shell) SetHomeHistoryPath ¶
SetHomeHistoryPath is a convenience method that sets the history path with a $HOME prepended path.
func (*Shell) SetMultiPrompt ¶
SetMultiPrompt sets the prompt string used for multiple lines. The string to be displayed before the cursor; starting from the second line of input.
func (*Shell) SetPrompt ¶
SetPrompt sets the prompt string. The string to be displayed before the cursor.
func (*Shell) ShowPrompt ¶
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 ¶
Unregister unregisters a function for a command
Source Files
Directories