99 lines
2.8 KiB
Markdown
99 lines
2.8 KiB
Markdown
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);`
|