shell

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 New(options ...Option) (*Instance, error)
  • 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

• Instance.AddCommand
• New

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

func New(options ...Option) (*Instance, error)

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()

func (*Instance) AddCommand

func (sh *Instance) AddCommand(cmd *Command)

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()

func (*Instance) Clear

func (sh *Instance) Clear()

Clear the console screen.

func (*Instance) Print

func (sh *Instance) Print(line string)

Print will add content to the shell's main output.

func (*Instance) ReadSecret

func (sh *Instance) ReadSecret(prompt string) ([]byte, error)

ReadSecret allows the user to securely and interactively provide a sensitive value. The entered data won't be displayed.

func (*Instance) ReadSlice

func (sh *Instance) ReadSlice(params []string) (list []string, err error)

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

func (sh *Instance) ReadString(prompt string) (string, error)

ReadString allows the user to interactively provide a value.

func (*Instance) Reset

func (sh *Instance) Reset()

Reset the shell internal state.

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) SetPrompt

func (sh *Instance) SetPrompt(prompt string)

SetPrompt update the command prompt used by the shell.

func (*Instance) SetResetHook

func (sh *Instance) SetResetHook(hk Hook)

SetResetHook update the reset-hook currently registered on the shell.

func (*Instance) SetStartHook

func (sh *Instance) SetStartHook(hk Hook)

SetStartHook update the start-hook currently registered on the shell.

func (*Instance) SetStopHook

func (sh *Instance) SetStopHook(hk Hook)

SetStopHook update the stop-hook currently registered on the shell.

func (*Instance) Start

func (sh *Instance) Start()

Start the interactive shell processing.

type Option

type Option func(*Instance) error

Option provides a functional method to adjust the settings on a shell instance.

func WithExitCommands

func WithExitCommands(list []string) Option

WithExitCommands provides a list of reserved keywords to let the user close a running shell instance.

func WithExitMessage

func WithExitMessage(msg string) Option

WithExitMessage set a message to be printed just before the shell is closed.

func WithHelpCommands

func WithHelpCommands(list []string) Option

WithHelpCommands provides a list of reserved keywords to present a list of available top commands to the user.

func WithHelpMessage

func WithHelpMessage(msg string) Option

WithHelpMessage set a message to be printed along the command list for the user.

func WithHistoryFile

func WithHistoryFile(hf string) Option

WithHistoryFile adjust the location to store a log of tasks executed in the shell.

func WithHistoryLimit

func WithHistoryLimit(limit int) Option

WithHistoryLimit set the maximum number of items to store in the shell history, set to 0 to disable it.

func WithPrompt

func WithPrompt(p string) Option

WithPrompt set the CLI prompt value used by the shell.

func WithResetHook

func WithResetHook(hook Hook) Option

WithResetHook set a custom behavior to run just after the shell state is reset.

func WithStartHook

func WithStartHook(hook Hook) Option

WithStartHook set a custom behavior to run before the shell instance is started.

func WithStartMessage

func WithStartMessage(msg string) Option

WithStartMessage set a message to be printed just after the shell is started.

func WithStopHook

func WithStopHook(hook Hook) Option

WithStopHook set a custom behavior to run before the shell instance is closed.