sand

package module
Version: v1.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2018 License: MIT Imports: 10 Imported by: 1

README

GoDoc Go Report Card Build Status Code Coverage

sand

sand is for creating interpreters, like the Python interpreter and Haskell interpreter. It can also be used for creating text based games and CLI test environments.

For examples, check out the examples folder.

Design

sand implements a concurrent model. It views an interpreter as two seperate components: the User Interface, sand.UI, and the Command Processor,sand.Engine. The following diagram shows how under the hood sand operates. Every square is a goroutine.

+--------+                            +--------------------------+
|        |              +------------->     Engines Manager      +--------------+
|  Read  <----------+   |             +--------------------------+              |
|        |          |   |                                                       |
+----+---+          |   |                                                       |
     |            +-+---+------+                                        +-------v------+
     |            |            |                                        |              |     +----------+
     +------------>     UI     |                                        |    Engine    |     |  Engine  |
                  |  (usually  +---------------------------------------->    Runner    +---->+   Exec   |
     +------------>    main)   |                                        |              |     |          |
     |            |            |      XXXXXXXXXXXXXXXXXXXXXXXXXXXX      |              |     +----------+
     |            +-+----------+      X   Manager connects UI    X      +--------------+
+----+---+          |                 X   to Engine Runner       X
|        |          |                 XXXXXXXXXXXXXXXXXXXXXXXXXXXX
| Write  <----------+
|        |
+--------+

sand.UI is a struct that is provided for you and is implemented as broad as possible; however there are few features missing, which are commonly found in popular interpreters, namely: Line history and Auto-completion. These features may be added later, but as for now they are not planned for.

sand.Engine is an interface, which must be implemented by the user. Implementations of sand.Engine must have a comparable underlying type, see Go Spec for comparable types in Go.

Documentation

Overview

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.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsRecoverable added in v1.3.0

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:

  • context.Cancelled
  • context.DeadlineExceeded
  • newLineErr (an internal error, which isn't really important)

func Run

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.

Types

type Engine

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

type Option func(*UI)

Option represents setting an option for the interpreter UI.

func WithIO

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

WithIO specifies the Reader and Writer to use for IO.

func WithPrefix

func WithPrefix(prefix string) Option

WithPrefix specifies the prefix

func WithSignalHandlers

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

WithSignalHandlers specifies user provided signal handlers to register.

type SignalHandler

type SignalHandler func(os.Signal) os.Signal

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

type UI

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

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

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

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

SetIO sets the interpreters I/O.

func (*UI) SetPrefix

func (ui *UI) SetPrefix(prefix string)

SetPrefix sets the interpreters line prefix

func (*UI) Write

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.

Source Files

Directories

Path Synopsis
example
cobra
Package main shows using sand for testing environment
Package main shows using sand for testing environment
echo
Package main demonstrates using sand in a basic manner.
Package main demonstrates using sand in a basic manner.
oneoff
Package main demonstrates starting an Engine without starting it from inside a UI.
Package main demonstrates starting an Engine without starting it from inside a UI.
tictactoe
Package main demonstrates using sand for a CLI based game.
Package main demonstrates using sand for a CLI based game.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL