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

• func NewWord(f Forth, name, command string)
• func Ops() map[string]Op
• func String(f Forth) string
• type Cell
  • func Eval(f Forth, s string) (ret Cell, err error)
• type Forth
  • func New() Forth
• type Op

Functions

func NewWord

func NewWord(f Forth, name, command string)

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 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 Eval

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

Eval takes a Forth and strings and splits the string on space characters, pushing each element on the stack or invoking the operator if it is found in the opmap. It returns TOS when it is done. it is an error to leave the stack non-Empty.

type Forth

type Forth interface {
	Push(Cell)
	Pop() Cell
	Length() int
	Empty() bool
	Newop(string, Op)
	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.