gir/api.md

Compiling and inspecting programs

compile

compile(program, enableExtensions = true)

• program: String containing the program to compile
• enableExtensions: Whether to recognize :;# or ignore them

Returns: An array holding flat IR

Example: let compiled = compile(',[>+<,]>:');

prettifyIR

prettifyIR(ir)

• ir: An array holding any type of IR used by Gir

Returns: A string suitable for creating IR listings

Example: console.log(prettifyIR(compiled));

Executing programs

Gir executes the flattened IR in a simple virtual machine. runVM() doesn't mutate a state object that is passed to it but rather returns a new one.

VM state object

property	default value	description
program	(set by caller)	compile()d program
ip	0	Instruction pointer
memory	Map {}	Tape
tapeHead	0	Tape head position
input	(set by caller)	encodeUTF8()d input
output	[]	Output (needs to be decodeUTF8()d)
onEof	0 / (set by caller)	What to do in case of EOF¹

¹ If onEof is null the cell will not be changed, but otherwise the cell will be set to the value of onEof

newVM

newVM(program, input, onEof = 0)

• program: An array holding flat IR
• input: An array of integers which is interpreted as a byte stream
• onEof: See description of onEof field of the VM state object

Returns: VM state object

Example: let vm = newVM(compile('.[,[-].]'), encodeUTF('foobar'), null);

runVM

runVM(vm, maxCycles = null)

• vm: VM state object
• maxCycles: Number of cycles the program is allowed to run. null means no limit

Returns: An object like following

property	description
state	VM state object of the state after runVM() has completed
complete	Boolean describing whether the program completed or not
cycles	How many cycles did the program run during this invocation of runVM()
intParseFailed	Boolean describing if runVM() exited because ; failed to parse an int
breakPointReached	Boolean describing if runVM() exited because it hit #
lastIndex	Last cell that was accessed by the VM

Example: let output = decodeUTF8(runVM(vm, 400000).state.output);

Helper functions

encodeUTF8

encodeUTF8(string)

• string: A javascript string

Returns: An array of integers that interpreted as bytes encode that string

Example: let encoded = encodeUTF8(input);

decodeUTF8

decodeUTF8(encoded)

• encoded: An array of integers

Returns: A string encoded by that array

Example: let output = decodeUTF8(result.state.output);