Documentation
¶
Overview ¶
Package shell provides an interactive client for CLI-based applications.
The main point of interaction is a shell 'Instance'. Specific functionality is registered with the instance in the form of commands. Commands will be executed when the user invokes them as part of an active interactive session.
// Create a new shell instance with basic configuration options
options := []Option{
WithPrompt("sample shell > "),
WithStartMessage("this is just a sample shell"),
WithExitMessage("exiting sample shell..."),
}
sh, err := New(options...)
if err != nil {
panic(err)
}
// Register commands
sh.AddCommand(&Command{
Name: "sample-command",
Description: "this is just a sample command",
Usage: "sample",
Run: func(_ string) string {
// Read secure user input
pass, err := sh.ReadSecret("enter password:")
if err != nil {
return fmt.Sprintf("an error occurred: %s", err)
}
// Return final result, it will be displayed back to the user
return fmt.Sprintf("the password entered is: %s", pass)
},
})
// Start interactive session
sh.Start()
Index ¶
- type Command
- type Hook
- type Instance
- func (sh *Instance) AddCommand(cmd *Command)
- func (sh *Instance) Clear()
- func (sh *Instance) Print(line string)
- func (sh *Instance) ReadSecret(prompt string) ([]byte, error)
- func (sh *Instance) ReadSlice(params []string) (list []string, err error)
- func (sh *Instance) ReadString(prompt string) (string, error)
- func (sh *Instance) Reset()
- func (sh *Instance) ResetCommands()
- func (sh *Instance) SetPrompt(prompt string)
- func (sh *Instance) SetResetHook(hk Hook)
- func (sh *Instance) SetStartHook(hk Hook)
- func (sh *Instance) SetStopHook(hk Hook)
- func (sh *Instance) Start()
- type Option
- func WithExitCommands(list []string) Option
- func WithExitMessage(msg string) Option
- func WithHelpCommands(list []string) Option
- func WithHelpMessage(msg string) Option
- func WithHistoryFile(hf string) Option
- func WithHistoryLimit(limit int) Option
- func WithPrompt(p string) Option
- func WithResetHook(hook Hook) Option
- func WithStartHook(hook Hook) Option
- func WithStartMessage(msg string) Option
- func WithStopHook(hook Hook) Option
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct {
// Short name for the command.
Name string
// Brief but clear description about the command purpose.
Description string
// Information about how to use the command.
Usage string
// Method to execute when the command is invoked.
Run func(arg string) string
// Sub-commands available, if any.
SubCommands []*Command
}
Command provides a mechanism to add functionality to a shell instance.
type Hook ¶
type Hook func()
Hook provides a mechanism to extend the shell functionality during several moments of its lifecycle.
type Instance ¶
type Instance struct {
// contains filtered or unexported fields
}
Instance defines the main interface for an interactive shell.
func New ¶
New ready-to-use interactive shell instance based on the provided configuration options.
Example ¶
Start a sample shell instance using most of the available options.
// Configure shell instance
options := []Option{
WithPrompt("sample shell > "),
WithStartMessage("this is just a sample shell"),
WithExitMessage("exiting sample shell..."),
WithExitCommands([]string{"quit"}),
WithHelpMessage("this is a sample help message"),
WithHelpCommands([]string{"??"}),
WithHistoryFile("shell_history"),
WithHistoryLimit(100),
WithStartHook(func() {
log.Println("about to start")
}),
WithStopHook(func() {
log.Println("about to quit")
}),
WithResetHook(func() {
log.Println("applying reset")
}),
}
sh, err := New(options...)
if err != nil {
panic(err)
}
sh.Start()
Output:
func (*Instance) AddCommand ¶
AddCommand will register a command with the shell instance and update the autocomplete mechanism accordingly.
Example ¶
Start new shell and add a sample command.
// Create a new shell instance with basic configuration options
options := []Option{
WithPrompt("sample shell > "),
WithStartMessage("this is just a sample shell"),
WithExitMessage("exiting sample shell..."),
}
sh, err := New(options...)
if err != nil {
panic(err)
}
// Register commands
sh.AddCommand(&Command{
Name: "sample-command",
Description: "this is just a sample command",
Usage: "sample",
Run: func(_ string) string {
// Read secure user input
pass, err := sh.ReadSecret("enter password:")
if err != nil {
return fmt.Sprintf("an error occurred: %s", err)
}
// Return final result, it will be displayed back to the user
return fmt.Sprintf("the password entered is: %s", pass)
},
})
// Start interactive session
sh.Start()
Output:
func (*Instance) ReadSecret ¶
ReadSecret allows the user to securely and interactively provide a sensitive value. The entered data won't be displayed.
func (*Instance) ReadSlice ¶
ReadSlice is an utility method allowing the user to interactively provide a list of values. Each entry in the provided list will be used as a prompt value. The returned list of values will be ordered as entered. The processing will terminate on the first error encountered.
func (*Instance) ReadString ¶
ReadString allows the user to interactively provide a value.
func (*Instance) ResetCommands ¶
func (sh *Instance) ResetCommands()
ResetCommands remove all available commands in the shell, useful only when reusing an instance with a new command set.
func (*Instance) SetResetHook ¶
SetResetHook update the reset-hook currently registered on the shell.
func (*Instance) SetStartHook ¶
SetStartHook update the start-hook currently registered on the shell.
func (*Instance) SetStopHook ¶
SetStopHook update the stop-hook currently registered on the shell.
type Option ¶
Option provides a functional method to adjust the settings on a shell instance.
func WithExitCommands ¶
WithExitCommands provides a list of reserved keywords to let the user close a running shell instance.
func WithExitMessage ¶
WithExitMessage set a message to be printed just before the shell is closed.
func WithHelpCommands ¶
WithHelpCommands provides a list of reserved keywords to present a list of available top commands to the user.
func WithHelpMessage ¶
WithHelpMessage set a message to be printed along the command list for the user.
func WithHistoryFile ¶
WithHistoryFile adjust the location to store a log of tasks executed in the shell.
func WithHistoryLimit ¶
WithHistoryLimit set the maximum number of items to store in the shell history, set to 0 to disable it.
func WithPrompt ¶
WithPrompt set the CLI prompt value used by the shell.
func WithResetHook ¶
WithResetHook set a custom behavior to run just after the shell state is reset.
func WithStartHook ¶
WithStartHook set a custom behavior to run before the shell instance is started.
func WithStartMessage ¶
WithStartMessage set a message to be printed just after the shell is started.
func WithStopHook ¶
WithStopHook set a custom behavior to run before the shell instance is closed.
Source Files