opshell

package
v0.0.1-beta.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 20, 2024 License: BSD-3-Clause, BSD-3-Clause Imports: 16 Imported by: 0

README

OpShell

Shell-like interface to an Op.

Documentation

Overview

Package opshell - Operator's interactive shell

Index

Examples

Constants

View Source 
const DefaultPrompt = "> "

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

Variables

View Source 
var DefaultSplitter = simpleshsplit.SplitGoUnquote

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

View Source 
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 Color 

type Color string

Color is used ot select a color from terminal.EscapeCodes. Please see term.EscapeCodes for more information. 

const (
	ColorBlack   Color = "black"
	ColorRed     Color = "red"
	ColorGreen   Color = "green"
	ColorYellow  Color = "yellow"
	ColorBlue    Color = "blue"
	ColorMagenta Color = "magenta"
	ColorCyan    Color = "cyan"
	ColorWhite   Color = "white"
	ColorReset   Color = "reset"
)

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. Use Config.New to create a new shell.

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]) Color 

func (s *Shell[T]) Color(c Color, t string) string

Color wraps t with escape codes to set the color and then reset it after s. if c isn't one of the Color* constants, t is returned.

func (*Shell[T]) ColorCode 

func (s *Shell[T]) ColorCode(c Color) string

ColorCode returns a terminal sequence for the given color. Please see term.EscapeCodes for more information. This is a wraper around s.Escape.<c>. If c doesn't reprsent a known color, ColorCode returns the empty string.

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]) Escape 

func (s *Shell[T]) Escape() *term.EscapeCodes

Escape returns the shell's escape sequences. See term.EscapeCodes for more information.

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.