sand: Index | Files

package sand

import ""

Package sand is for creating interpreters.

This package implements a concurrent model for an interpreter. Which views an interpreter as two separate components, a User Interface (UI) and a Command Processor (Engine). The UI is provided for you, whereas, Engine implementations must be provided.


Package Files

engine.go ui.go

func IsRecoverable Uses

func IsRecoverable(err error) (root error, ok bool)

IsRecoverable guesses if the provided error is considered recoverable from. In the sense that the main function can keep running and not log.Fatal or retry or something of that nature. It will default to true for any unknown error, so the caller still needs to do their own error handling of the root error.

An example of a recoverable error is an io.EOF if a bytes.Buffer/Reader is used as the input Reader for a UI. This error is obviously recoverable to a human but in this case but a computer has no way of determining that itself.

Recoverable Errors:

- err == nil
- context.Cancelled
- context.DeadlineExceeded
- newLineErr (an internal error, which isn't really important)

func Run Uses

func Run(ctx context.Context, eng Engine, opts ...Option) error

Run creates a UI and associates the provided Engine to it. It then starts the UI.

type Engine Uses

type Engine interface {
    // Exec should take the given line and execute the corresponding functionality.
    Exec(ctx context.Context, line string, ui io.ReadWriter) (status int)

Engine represents the command processor for the interpreter. The underlying type of the Engine implementation must be a hashable type (e.g. int, string, struct) in order for the UI to be able to use it. Sadly, this means a type EngineFunc can not be used due to funcs not being hashable.

type Option Uses

type Option func(*UI)

Option represents setting an option for the interpreter UI.

func WithIO Uses

func WithIO(in io.Reader, out io.Writer) Option

WithIO specifies the Reader and Writer to use for IO.

func WithPrefix Uses

func WithPrefix(prefix string) Option

WithPrefix specifies the prefix

func WithSignalHandlers Uses

func WithSignalHandlers(handlers map[os.Signal]SignalHandler) Option

WithSignalHandlers specifies user provided signal handlers to register.

type SignalHandler Uses

type SignalHandler func(os.Signal) os.Signal

SignalHandler is a type that transforms incoming interrupt signals the UI has received.

type UI Uses

type UI struct {
    // contains filtered or unexported fields

UI represents the user interface for the interpreter. UI listens for all signals and handles them as graceful as possible. If signal handlers are provided then the handling of the Interrupt and Kill signal can be overwritten. By default, UI will shutdown on Interrupt and Kill signals.

func (*UI) Read Uses

func (ui *UI) Read(b []byte) (n int, err error)

Read reads from the underlying input Reader. This is a blocking call and handles monitoring the current context. Thus, callers should handle context errors appropriately. See examples for such handling.

func (*UI) Run Uses

func (ui *UI) Run(ctx context.Context, eng Engine, opts ...Option) (err error)

Run starts the user interface with the provided sources for input and output of the interpreter and engine. The prefix will be printed before every line.

func (*UI) SetIO Uses

func (ui *UI) SetIO(in io.Reader, out io.Writer)

SetIO sets the interpreters I/O.

func (*UI) SetPrefix Uses

func (ui *UI) SetPrefix(prefix string)

SetPrefix sets the interpreters line prefix

func (*UI) Write Uses

func (ui *UI) Write(b []byte) (n int, err error)

Write writes the provided bytes to the UIs underlying output along with the prefix characters.

In order to avoid data races due to the UI prefix, any changes to the prefix must be done in a serial pair of SetPrefix and Write calls. This means multiple goroutines cannot call SetPrefix + Write, simultaneously. See example "tictactoe" for a demonstration of changing the prefix.

Package sand imports 10 packages (graph). Updated 2018-12-01. Refresh now. Tools for package owners.