README
¶
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
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)
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 WithSignalHandlers ¶
func WithSignalHandlers(handlers map[os.Signal]SignalHandler) Option
WithSignalHandlers specifies user provided signal handlers to register.
type SignalHandler ¶
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 ¶
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 ¶
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.
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. |