opshell

README

OpShell

Shell-like interface to an Op.

Documentation

Overview

Package opshell - Operator's interactive shell

Index

• Constants
• Variables
• func CutCommand(s string) ([]string, error)
• func DefaultErrorHandler[T any](s *Shell[T], line string, err error) error
• type Config
  • func (c Config[T]) New() (*Shell[T], error)
• type PTYConfig
  • func (i PTYConfig) String() string
• type Shell
  • func (s *Shell[T]) Cdr() *subcom.Cdr[*Shell[T]]
  • func (s *Shell[T]) ErrorLogf(format string, args ...any)
  • func (s *Shell[T]) ErrorWrite(b []byte) (int, error)
  • func (s *Shell[T]) Errorf(format string, args ...any) (int, error)
  • func (s *Shell[T]) HandleCommand(cmd string) error
  • func (s *Shell[T]) HandleCommands() error
  • func (s *Shell[T]) InPTYMode() bool
  • func (s *Shell[T]) Logf(format string, args ...any)
  • func (s *Shell[T]) Printf(format string, args ...any) (int, error)
  • func (s *Shell[T]) ReadLine() (string, error)
  • func (s *Shell[T]) ResetTerm() error
  • func (s *Shell[T]) SetCommandErrorHandler(h func(s *Shell[T], line string, err error) error)
  • func (s *Shell[T]) SetPrompt(prompt string)
  • func (s *Shell[T]) SetSize(width, height int) error
  • func (s *Shell[T]) SetSplitter(f func(string) ([]string, error))
  • func (s *Shell[T]) SetV(v T)
  • func (s *Shell[T]) V() T
  • func (s *Shell[T]) Write(b []byte) (int, error)
• type SplitError
  • func (err SplitError) Error() string
  • func (err SplitError) Unwrap() error

Examples

• CutCommand

Constants

const DefaultPrompt = "> "

DefaultPrompt is the default prompt used if none is specified in a Config.

Variables

var DefaultSplitter = simpleshsplit.SplitGoUnquote

DefaultSplitter is the default function used for splitting commands into arguments.

var ErrQuit = errors.New("quit requested")

ErrQuit may returned by a command handler to cause Shell.HandleCommands to stop handling commands. It is intended to be returned from handler for a quit command.

Functions

func CutCommand

func CutCommand(s string) ([]string, error)

CutCommand is similar to strings.Cut, but returns the first non-whitespace portion and the remainder of the string with leading whitespace removed along with a nil error. The returned slice will have a length of 0 if s was empty or whitespace, 1 if s didn't have two non-whitespace parts separated by whitespace, or 2 in any other case.

Example

parts, err := CutCommand("foo bar tridge")
if nil != err {
	panic(err)
}

for _, v := range parts {
	fmt.Println(v)
}

Output:

foo
bar tridge

func DefaultErrorHandler

func DefaultErrorHandler[T any](s *Shell[T], line string, err error) error

DefaultErrorHandler is the default handler used when nil or no function has been passed to SetSplitErrorHandler or SetUnknownCommandHandler. It simply prints a message via s.Errorf.

Types

type Config

type Config[T any] struct {
	// Reader is from where the shell draws its input.  If unset, os.Stdin
	// will be used.
	Reader io.Reader
	// Writer is to where the shell sends its output.  If unset, os.Stdout
	// will be used.
	Writer io.Writer
	// ErrWriter is where the shell sends error output via Shell.Errorf and
	// friends when not in PTY mode.
	ErrorWriter io.Writer

	// PTYMode determines whether or not shells created with this config
	// use PTY mode, i.e. golang.org/x/term.Terminals under the hood.  If
	// unset or set to PTYDefault, PTY mode is enabled if Reader is
	// a terminal, as determined by golang.org/x/term.IsTerminal.  When in
	// PTY mode, ErrorWriter is ignored and all output goes to Writer.
	PTYMode PTYConfig

	// Prompt sets the initial prompt.  If unset, DefaultPrompt is used.
	Prompt string
}

Config is the configuration needed to create a Shell. See the documentation for Shell for more information. The shell referred to in Config's fields' documentation is a shell created using Config.New.

func (Config[T]) New

func (c Config[T]) New() (*Shell[T], error)

New creates a new shell according to c.

type PTYConfig

type PTYConfig int

PTYConfig is used in Config to indicate whether or not to enable PTY mode. See the documentation for Config.PTY for more details.

const (
	PTYDefault PTYConfig = iota /* Check if Config.Reader is a Terminal. */
	PTYForce                    /* Always enable PTY mode */
	PTYDisable                  /* Never enable PTY mode */
)

func (PTYConfig) String

func (i PTYConfig) String() string

type Shell

type Shell[T any] struct {
	// contains filtered or unexported fields
}

Shell represents the interface between an operator and the rest of the program. See the documentation for Shell.V for more information about T.

func (*Shell[T]) Cdr

func (s *Shell[T]) Cdr() *subcom.Cdr[*Shell[T]]

Cdr returns s's Cdr. This should be used to set command handlers before processing commands via s.HandleCommand or s.HandleCommands.

func (*Shell[T]) ErrorLogf

func (s *Shell[T]) ErrorLogf(format string, args ...any)

ErrorLogf is identical to Logf, but writes to s's ErrorWriter if not in PTY mode.

func (*Shell[T]) ErrorWrite

func (s *Shell[T]) ErrorWrite(b []byte) (int, error)

ErrorWrite is identical to PrintWrite, but writes to s's ErrorWriter if not in PTY mode.

func (*Shell[T]) Errorf

func (s *Shell[T]) Errorf(format string, args ...any) (int, error)

Errorf is identical to Printf, but writes to s's ErrorWriter if not in PTY mode.

func (*Shell[T]) HandleCommand

func (s *Shell[T]) HandleCommand(cmd string) error

HandleCommand handles a single command sent to the shell. If the command fails to split, a SplitError is returned. This is useful for filtering lines returned by s.ReadLine before command processing.

func (*Shell[T]) HandleCommands

func (s *Shell[T]) HandleCommands() error

HandleCommands reads lines from s and uses the configured subcom.Cdr to handle commands. If a command handler returns ErrQuit, command handling will stop and HandleCommands will return ErrQuit.

func (*Shell[T]) InPTYMode

func (s *Shell[T]) InPTYMode() bool

InPTYMode indicates whether or not we're in PTY mode

func (*Shell[T]) Logf

func (s *Shell[T]) Logf(format string, args ...any)

Logf is like Printf, but prepends a timestamp.

func (*Shell[T]) Printf

func (s *Shell[T]) Printf(format string, args ...any) (int, error)

Printf writes to s in the manner of fmt.Printf.

func (*Shell[T]) ReadLine

func (s *Shell[T]) ReadLine() (string, error)

ReadLine reads a line from s.

func (*Shell[T]) ResetTerm

func (s *Shell[T]) ResetTerm() error

ResetTerm resets s's underlying Terminal to its original state if it was put into raw mode due to s being in PTY mode. ResetTerm should be called to prevent stdio being in raw mode on program exit and is safe to call even if s is not in PTY mode.

func (*Shell[T]) SetCommandErrorHandler

func (s *Shell[T]) SetCommandErrorHandler(h func(s *Shell[T], line string, err error) error)

SetCommandErrorHandler sets a handler which s.HandleCommands will call when an error handling a command is encountered. If f is nil, DefaultErrorHandler will be used. If the handler returns an error, it will be returned by s.HandleCommands.

In particular, two types of errors should be expected: SplitError, which indicates that a command was unable to be split into arguments, and subcom.ErrNotFound, which indicates that the underlying subcom.Cdr didn't have a handler for the requested command.

func (*Shell[T]) SetPrompt

func (s *Shell[T]) SetPrompt(prompt string)

SetPrompt sets the prompt s presents to the user if in PTY mode and is a no-op if not in PTY mode.

func (*Shell[T]) SetSize

func (s *Shell[T]) SetSize(width, height int) error

SetSize sets s's size in PTY mode and is a no-op otherwise. In PTY mode, s's size will be automatically changed upon receipt of SIGWINCH.

func (*Shell[T]) SetSplitter

func (s *Shell[T]) SetSplitter(f func(string) ([]string, error))

SetSplitter sets the function s.HandleCommand and s.HandleCommands use to split command lines into arguments. If f is nil, DefaultSplitter will be used.

func (*Shell[T]) SetV

func (s *Shell[T]) SetV(v T)

SetV changes the value returned by s.V. Under the hood, it stores a pointer to v, not v itself.

func (*Shell[T]) V

func (s *Shell[T]) V() T

V returns a value of type T which may be used to store persistent state during the shell's lifetime (e.g. between handled commands). When the Shell is first created V will return a zero value of type T. SetV may be used to change the value V returns.

func (*Shell[T]) Write

func (s *Shell[T]) Write(b []byte) (int, error)

Write writes to s's Writer.

type SplitError

type SplitError struct {
	Err error
}

SplitError is a decorator indicating the string passed to HandleCommand failed to split into arguments; no command was executed.

func (SplitError) Error

func (err SplitError) Error() string

Error implements the error interface.

func (SplitError) Unwrap

func (err SplitError) Unwrap() error

Unwrap returns err.Err.