ws

package
v0.0.0-...-99d40e0 Latest Latest
Warning

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

Go to latest
Published: Aug 30, 2020 License: MIT Imports: 11 Imported by: 4

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

Constants

This section is empty.

Variables

This section is empty.

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.

Jump to

Keyboard shortcuts

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