forth

Documentation

Overview

Package forth implements Forth parsing, which allows programs to use forth-like syntax to manipulate a stack of Cells. It is designed for use by programs needing to evaluate command-line arguments or simple expressions to set program variables. It is designed to map host names to numbers. We use it to easily convert host names and IP addresses into parameters. The language is a Forth-like postfix notation. Elements are either commands or strings. Strings are immediately pushed. Commands consume stack variables and produce new ones. Simple examples: push hostname, strip alpha characters to produce a number. If your hostname is sb47, top of stack will be left with 47. hostname hostbase Get the hostbase, if it is 0 mod 20, return the hostbase / 20, else return hostbase mod 20

hostname hostbase dup 20 / swap 20 % dup ifelse

At the end of the evaluation the stack should have one element left; that element is popped and returned. It is an error (currently) to return with a non-empty stack. This package was used for real work at Sandia National Labs from 2010 to 2012 and possibly later. Some of the use of error may seem a bit weird but the creation of this package predates the creation of the error type (it was still an os thing back then).

Index

• Variables
• func Eval(f Forth, cells ...Cell) (err error)
• func EvalString(f Forth, s string) (err error)
• func NewWord(f Forth, name string, cell Cell, cells ...Cell)
• func Ops() map[string]Op
• func Putop(n string, op Op)
• func String(f Forth) string
• type Cell
  • func EvalPop(f Forth, s string) (ret Cell, err error)
• type Forth
  • func New() Forth
• type Op
  • func Getop(n string) Op

Variables

var (
	// Debug is an empty function that can be set to, e.g.,
	// fmt.Printf or log.Printf for debugging.
	Debug = func(string, ...interface{}) {}
)

Functions

func Eval

func Eval(f Forth, cells ...Cell) (err error)

Eval takes a Forth and []Cell, pushing each element on the stack or invoking the operator if it is found in the opmap.

func EvalString

func EvalString(f Forth, s string) (err error)

EvalString takes a Forth and string and splits the string on space characters, calling Eval for each one.

func NewWord

func NewWord(f Forth, name string, cell Cell, cells ...Cell)

NewWord allows for definition of new operators from strings. For example, should you wish to create a word which adds a number to itself twice, you can call: NewWord(f, "d3d", "dup dup + +") which does two dups, and two adds.

func Ops

func Ops() map[string]Op

Ops returns the operator map.

func Putop

func Putop(n string, op Op)

Putop creates a new operation. We considered having an opmap per stack but don't feel the package requires it

func String

func String(f Forth) string

String returns the Top Of Stack if it is a string or panics.

Types

type Cell

type Cell interface{}

Cell is a stack element.

func EvalPop

func EvalPop(f Forth, s string) (ret Cell, err error)

EvalPop takes a Forth and string, calls EvalString, and returns TOS and an error, if any. For EvalPop it is an error to leave the stack non-Empty. EvalPop is typically used for programs that want to parse forth contained in, e.g., flag.Args(), and return a result. In most use cases, we want the stack to be empty.

type Forth

type Forth interface {
	Push(Cell)
	Pop() Cell
	Length() int
	Empty() bool
	Reset()
	Stack() []Cell
}

Forth is an interface used by the package. The interface requires definition of Push, Pop, Length, Empty (convenience function meaning Length is 0), Newop (insert a new or replacement operator), and Reset (clear the stack, mainly diagnostic)

func New

func New() Forth

New creates a new stack

type Op

type Op func(f Forth)

Op is an opcode type. It does not return an error value, instead using panic when parsing issues occur, to ease the programming annoyance of propagating errors up the stack (following common Go practice for parsers). If you write an op it can use panic as well. Lest you get upset about the use of panic, be aware I've talked to the folks in Go core about this and they feel it's fine for parsers.

func Getop

func Getop(n string) Op

Getop gets an op from the map.