Document the API
This commit is contained in:
parent
d74b6ab594
commit
316e839804
|
@ -20,12 +20,13 @@ Gir supports following optimizations:
|
||||||
|
|
||||||
TODO
|
TODO
|
||||||
----
|
----
|
||||||
|
### gir.js
|
||||||
|
* Move `ircbotRun()` into its own file
|
||||||
|
|
||||||
### gir.html
|
### gir.html
|
||||||
* Implement a UI
|
* Implement a UI
|
||||||
|
|
||||||
### Documentation
|
### Documentation
|
||||||
* Document the VM
|
|
||||||
* Document the user-facing API
|
|
||||||
* Document the overall architecture
|
* Document the overall architecture
|
||||||
|
|
||||||
### General
|
### General
|
||||||
|
|
|
@ -0,0 +1,98 @@
|
||||||
|
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);`
|
14
gir.js
14
gir.js
|
@ -187,14 +187,14 @@ function parse(program, enableExtensions = true) {
|
||||||
return parsed;
|
return parsed;
|
||||||
}
|
}
|
||||||
|
|
||||||
// ([commandObjects/offsetCommandObjects]) → str
|
// ([commandObjects/offsetCommandObjects/flatCommandObjects]) → str
|
||||||
function prettifyIR(parsed) {
|
function prettifyIR(ir) {
|
||||||
// ([commandObjects/offsetCommandObjects], string) → str
|
// ([commandObjects/offsetCommandObjectsflatCommandObjects], string) → str
|
||||||
function worker(parsed, indent = '') {
|
function worker(ir, indent = '') {
|
||||||
let lines = [];
|
let lines = [];
|
||||||
|
|
||||||
for(let i = 0; i < parsed.length; i++) {
|
for(let i = 0; i < ir.length; i++) {
|
||||||
let command = parsed[i];
|
let command = ir[i];
|
||||||
|
|
||||||
let line = `${indent}${i} `;
|
let line = `${indent}${i} `;
|
||||||
if(command.type == add) {
|
if(command.type == add) {
|
||||||
|
@ -267,7 +267,7 @@ function prettifyIR(parsed) {
|
||||||
|
|
||||||
return lines
|
return lines
|
||||||
}
|
}
|
||||||
return worker(parsed).join('\n');
|
return worker(ir).join('\n');
|
||||||
}
|
}
|
||||||
|
|
||||||
// ------------------------------------------------------------------
|
// ------------------------------------------------------------------
|
||||||
|
|
Loading…
Reference in New Issue