ws

README

Whitespace Introduction

The Whitespace language is defined by Edwin Brady and Chris Morris in the original Haskell interpreter source and the language tutorial.

Grammar

The grammar of the language is very simple, consisting only of the characters space, tab, and line feed. Instructions are denoted with permutations of these characters, resembling a prefix tree. Integers are an arbitrary-length series of binary digits written as spaces and tabs and terminated with a line feed. The grammar is described further in the official tutorial.

As the only recognized characters are invisible, programs are hard to read and write, thus I have only written one program directly with this syntax: hello_world.ws. Many authors instead write in one of various "Whitespace Assembly" dialects that provide a small level of abstraction. I borrow from the syntax used by the Whitelips IDE project.

Architecture

The Whitespace memory model consists of a stack and a heap. In the stack, values are pushed once and accessed once and storage is sequential. The heap is addressed dynamically, allowing for multiple assignments and accesses at the same address.

Control flow consists of labels, unconditional and conditional jumps, call, return, and exit. A control stack is used for call and return, separate from the data stack.

Instruction set

Stack manipulation

Stack operations push, pop, or otherwise modify the data stack. Copy and slide were added in Whitespace 0.3 to facilitate recursion.

Command	Parameters	Stack	Meaning
push	Number	-	Push the number onto the stack
dup	-	-	Duplicate the top item on the stack
copy	Number	-	Copy the nth item on the stack
swap	-	-	Swap the top two items on the stack
drop	-	-	Discard the top item on the stack
slide	Number	-	Slide n items off the stack, keeping the top item

Arithmetic

Arithmetic instructions operate on the top two items on the stack and replace them with the result of the operation. The first item pushed is the left of the operator.

Command	Parameters	Stack	Meaning
add	-	LHS, RHS	Addition
sub	-	LHS, RHS	Subtraction
mul	-	LHS, RHS	Multiplication
div	-	LHS, RHS	Integer Division
mod	-	LHS, RHS	Modulo

Heap access

Heap access commands operate between the stack and heap. Values can be stored in the heap for persistent addressed storage.

Command	Parameters	Stack	Meaning
store	-	Address, Number	Store an item from the stack in the heap
retrieve	-	Address	Retrieve an item from the heap

Control flow

Control flow consists of labels, unconditional and conditional jumps, call, return, and exit. A control stack is used for call and return, separate from the data stack.

Command	Parameters	Stack	Meaning
label	Label	-	Mark a location in the program
call	Label	-	Call a subroutine
jmp	Label	-	Jump unconditionally to a label
jz	Label	Number	Jump to a label if the top of the stack is zero
jn	Label	Number	Jump to a label if the top of the stack is negative
ret	-	-	End a subroutine and transfer control back to the caller
end	-	-	End the program

I/O

I/O commands interact with the user for reading and writing numbers and characters. The reference Haskell interpreter errors on EOF or incorrectly formatted integers.

Command	Parameters	Meaning	Meaning
printc	-	Number	Output the character at the top of the stack
printi	-	Number	Output the number at the top of the stack
readc	-	Address	Read a character and store it at the given address
readi	-	Address	Read a number and store it at the given address

Documentation

Overview

Package ws parses Whitespace source files.

Index

• func ApplyLabelMap(tokens []*Token, labelNames *bigint.Map)
• func Pack(src []byte) []byte
• func ParseLabelMap(r io.Reader) (*bigint.Map, error)
• func Unpack(bits []byte) []byte
• type Program
  • func (p *Program) Dump(indent string) string
  • func (p *Program) DumpCommented(src []byte, indent string) string
  • func (p *Program) DumpPos() string
  • func (p *Program) DumpWS() string
  • func (p *Program) LowerIR() (*ir.Program, []error)
  • func (p *Program) String() string
• type SyntaxError
  • func (err *SyntaxError) Error() string
• type Token
  • func LexTokens(file *token.File, src []byte) ([]*Token, error)
  • func (tok *Token) String() string
  • func (tok *Token) StringWS() string
• type TokenError
  • func (err *TokenError) Error() string
• type Type
  • func (typ Type) HasArg() bool
  • func (typ Type) IsArith() bool
  • func (typ Type) IsControl() bool
  • func (typ Type) IsDebug() bool
  • func (typ Type) IsHeap() bool
  • func (typ Type) IsIO() bool
  • func (typ Type) IsStack() bool
  • func (typ Type) String() string
  • func (typ Type) StringWS() string

Functions

func ApplyLabelMap

func ApplyLabelMap(tokens []*Token, labelNames *bigint.Map)

ApplyLabelMap adds label names from mapping to tokens.

func Pack

func Pack(src []byte) []byte

Pack bit packs a Whitespace source.

func ParseLabelMap

func ParseLabelMap(r io.Reader) (*bigint.Map, error)

ParseLabelMap reads a label source map and parses it into mappings from label name to integer value.

func Unpack

func Unpack(bits []byte) []byte

Unpack expands a bit packed source.

Types

type Program

type Program struct {
	Tokens []*Token
	File   *token.File
}

Program is a sequence of Whitespace tokens with file information.

func (*Program) Dump

func (p *Program) Dump(indent string) string

Dump formats a program as Whitespace assembly.

func (*Program) DumpCommented

func (p *Program) DumpCommented(src []byte, indent string) string

DumpCommented formats a program as Whitesapce assembly with comments interspersed.

func (*Program) DumpPos

func (p *Program) DumpPos() string

DumpPos formats a program as Whitespace assembly with source position information.

func (*Program) DumpWS

func (p *Program) DumpWS() string

DumpWS formats a program as Whitespace.

func (*Program) LowerIR

func (p *Program) LowerIR() (*ir.Program, []error)

LowerIR lowers a Whitespace program to Nebula IR in SSA form.

func (*Program) String

func (p *Program) String() string

type SyntaxError

type SyntaxError struct {
	Err string
	Pos token.Position
	End token.Position // inclusive
}

SyntaxError identifies the location of a syntactic error.

func (*SyntaxError) Error

func (err *SyntaxError) Error() string

type Token

type Token struct {
	Type      Type
	Arg       *big.Int
	ArgString string    // Label string, if exists
	Pos       token.Pos // Start position in source
	End       token.Pos // End position in source (exclusive)
}

Token is a lexical token in Whitespace.

func LexTokens

func LexTokens(file *token.File, src []byte) ([]*Token, error)

LexTokens scans a Whitespace source file into tokens.

func (*Token) String

func (tok *Token) String() string

func (*Token) StringWS

func (tok *Token) StringWS() string

StringWS formats a token as Whitespace.

type TokenError

type TokenError struct {
	Token *Token
	Pos   token.Position
	Err   string
}

TokenError is an error emitted while lowering to SSA form.

func (*TokenError) Error

func (err *TokenError) Error() string

type Type

type Type uint8

Type is the instruction type of a Whitespace token.

const (
	Illegal Type = iota

	// Stack manipulation instructions
	Push
	Dup
	Copy
	Swap
	Drop
	Slide
	Shuffle // non-standard; from Harold Lee's whitespace-0.4

	// Arithmetic instructions
	Add
	Sub
	Mul
	Div
	Mod

	// Heap access instructions
	Store
	Retrieve

	// Control flow instructions
	Label
	Call
	Jmp
	Jz
	Jn
	Ret
	End

	// I/O instructions
	Printc
	Printi
	Readc
	Readi

	// Debug instructions (non-standard)
	Trace     // from Phillip Bradbury's pywhitespace
	DumpStack // from Oliver Burghard's interpreter
	DumpHeap  // from Oliver Burghard's interpreter
)

Instruction types.

func (Type) HasArg

func (typ Type) HasArg() bool

HasArg returns true for instructions that require an argument.

func (Type) IsArith

func (typ Type) IsArith() bool

IsArith returns true for tokens corresponding to arithmetic instructions.

func (Type) IsControl

func (typ Type) IsControl() bool

IsControl returns true for tokens corresponding to control flow instructions.

func (Type) IsDebug

func (typ Type) IsDebug() bool

IsDebug returns true for tokens corresponding to debug instructions.

func (Type) IsHeap

func (typ Type) IsHeap() bool

IsHeap returns true for tokens corresponding to heap access instructions.

func (Type) IsIO

func (typ Type) IsIO() bool

IsIO returns true for tokens corresponding to I/O instructions.

func (Type) IsStack

func (typ Type) IsStack() bool

IsStack returns true for tokens corresponding to stack manipulation instructions.

func (Type) String

func (typ Type) String() string

func (Type) StringWS

func (typ Type) StringWS() string

StringWS formats the instruction type as Whitespace syntax.