Browse Source

aight i think that's all the docs

feature/exceptions
mark 8 months ago
parent
commit
e0fc67df3a
4 changed files with 136 additions and 105 deletions
  1. +110
    -87
      REFERENCE.md
  2. +5
    -4
      dictionary.js
  3. +20
    -14
      memeforth.js
  4. +1
    -0
      test/memeforth.test.js

+ 110
- 87
REFERENCE.md View File

@@ -69,35 +69,40 @@
- [strSlice][65]
- [Parameters][66]
- [dictionary][67]
- [InterpreterResult][68]
- [Properties][69]
- [interpret][70]
- [ifword][68]
- [Parameters][69]
- [doLoop][70]
- [Parameters][71]
- [runMemeForth][72]
- [interpret][72]
- [Parameters][73]
- [Stack][74]
- [runMemeForth][74]
- [Parameters][75]
- [pop][76]
- [push][77]
- [Parameters][78]
- [Stack][76]
- [Parameters][77]
- [pop][78]
- [push][79]
- [Parameters][80]

## InterpreterState

Type: [Object][79]
Type: [Object][81]

### Properties

- `stack` **[Array][80]<any>** The current stack
- `tokens` **[Array][80]<any>** The current tokenized program
- `words` **[Object][79]** The current set of defined words
- `stack` **[Array][82]<any>** The current stack
- `tokens` **[Array][82]<any>** The current tokenized program
- `words` **[Object][81]** The current set of defined words
- `memory` **[Array][82]<any>** The current interpreter "memory".
- `currentWord` **[string][83]** The current word being defined.
- `output` **[string][83]** The output from printing commands.

## hacker

Converts the top of the stack to :hacker_X: emojis.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `stack` **[Array][80]<[string][82]>** The Forth stack.
Converts the top of the stack to :hacker_X: emojis.
- `state` **[InterpreterState][84]** The current interpreter state.

## sm64

@@ -105,13 +110,15 @@ Converts the top of the stack to :sm64_X: emojis.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## concat

Concatenates the top two elements on the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## drop

@@ -119,7 +126,7 @@ Drops the top element of the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## dup

@@ -127,7 +134,7 @@ Duplicate the top element of the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## swap

@@ -135,7 +142,7 @@ Swap the top two elements of the stack

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## rot

@@ -143,7 +150,7 @@ Rotate the top three elements of the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## litstring

@@ -151,10 +158,10 @@ Parse a literal string until we find a string ending with "

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.


- Throws **[SyntaxError][83]** Throws an exception if the string isn't closed.
- Throws **[SyntaxError][85]** Throws an exception if the string isn't closed.

## add

@@ -163,7 +170,7 @@ Adds two values on the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state
- `state` **[InterpreterState][84]** The current interpreter state

## sub

@@ -172,7 +179,7 @@ Subtracts two values on the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state
- `state` **[InterpreterState][84]** The current interpreter state

## mul

@@ -181,7 +188,7 @@ Multiplies two values on the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state
- `state` **[InterpreterState][84]** The current interpreter state

## divmod

@@ -190,7 +197,7 @@ Divides two values on the stack, and pushes the quotient and its remainder.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state
- `state` **[InterpreterState][84]** The current interpreter state

## len

@@ -198,10 +205,10 @@ Replaces a string on the stack with its length. Replaces integers or other value

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state
- `state` **[InterpreterState][84]** The current interpreter state


- Throws **[TypeError][84]** Throws an exception if run on a non-string value.
- Throws **[TypeError][86]** Throws an exception if run on a non-string value.

## print

@@ -209,7 +216,7 @@ Return the first element in the stack, staging it for output.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## printStack

@@ -218,7 +225,7 @@ This does not affect the Forth stack at all - it merely shows it.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## store

@@ -226,7 +233,7 @@ Store a stack element into memory.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## fetch

@@ -234,7 +241,7 @@ Load from memory and push to the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## defvar

@@ -243,10 +250,10 @@ the variable will be stored.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.


- Throws **[TypeError][84]** Throws an exception if a non-string variable name is given.
- Throws **[TypeError][86]** Throws an exception if a non-string variable name is given.

## gt

@@ -254,7 +261,7 @@ Greater than comparison

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## lt

@@ -262,7 +269,7 @@ Less than comparison

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## ge

@@ -270,7 +277,7 @@ Greater than or equal comparison

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## le

@@ -278,7 +285,7 @@ Less than or equal comparison

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## eq

@@ -286,7 +293,7 @@ Equals comparison

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## ne

@@ -294,7 +301,7 @@ Not equals comparison

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## and

@@ -302,10 +309,10 @@ Logical AND

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.


- Throws **[TypeError][84]** Throws an exception if run with non-boolean values.
- Throws **[TypeError][86]** Throws an exception if run with non-boolean values.

## or

@@ -313,10 +320,10 @@ Logical OR

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.


- Throws **[TypeError][84]** Throws an exception if run with non-boolean values.
- Throws **[TypeError][86]** Throws an exception if run with non-boolean values.

## not

@@ -324,10 +331,10 @@ Logical NOT

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.


- Throws **[TypeError][84]** Throws an exception if run with non-boolean values.
- Throws **[TypeError][86]** Throws an exception if run with non-boolean values.

## rand

@@ -335,7 +342,7 @@ Generate a random number between a min and a max

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## litTrue

@@ -343,7 +350,7 @@ Push a literal `true` boolean onto the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## litFalse

@@ -351,7 +358,7 @@ Push a literal `false` boolean onto the stack.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.

## colon

@@ -359,10 +366,10 @@ Defines a word until a ;

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.


- Throws **[SyntaxError][83]** Throws an exception if no closing ; is found.
- Throws **[SyntaxError][85]** Throws an exception if no closing ; is found.

## strSlice

@@ -370,24 +377,36 @@ Slice a string based on substring indices.

### Parameters

- `state` **[InterpreterState][81]** The current interpreter state.
- `state` **[InterpreterState][84]** The current interpreter state.


- Throws **[TypeError][84]** Throws an exception if invalid types are given for indicies or the string to slice.
- Throws **[TypeError][86]** Throws an exception if invalid types are given for indicies or the string to slice.

## dictionary

The base dictionary of supported MemeForth tokens.

## InterpreterResult
## ifword

Type: [Object][79]
Parse an IF block.

### Properties
### Parameters

- `state` **[InterpreterState][84]** The current interpreter state.


- Throws **[SyntaxError][85]** Throws an exception if no closing THEN is found.

## doLoop

- `output` **[String][82]** The output as a result of TYPE/./.S commands.
- `stack` **[Array][80]<any>** The final stack when the program finished.
- `words` **[Object][79]** The set of words after the program executed, including any that were defined during execution.
Parse a DO loop.

### Parameters

- `state` **[InterpreterState][84]** The current interpreter state.


- Throws **[SyntaxError][85]** Throws an exception if no closing LOOP is found.

## interpret

@@ -395,22 +414,22 @@ Interprets a Forth token list.

### Parameters

- `state`
- `tokens` **[Array][80]<[string][82]>** The tokens to interpret, in order.
- `stack` **[Array][80]<any>** The initial Forth stack to use. Empty by default.
- `words` **[Object][79]** The initial set of words to use. Defaults to `dictionary`.
- `state` **[InterpreterState][84]** The initial state of the interpreter.

Returns **[InterpreterResult][85]** The result of the program execution
Returns **[InterpreterState][84]** The final state of the interpreter after execution.

## runMemeForth

Runs a Forth program and returns the stack.

### Parameters

- `program` **[string][82]** A Forth program, in string form.
- `stack` **[Array][80]<any>** The initial stack to use (optional, default `new Stack()`)
- `program` **[string][83]** A Forth program, in string form.
- `stack` **[Stack][87]** The initial stack. (optional, default `new Stack()`)
- `mem` (optional, default `[]`)
- `memory` **[Array][82]<any>** The intial memory.

Returns **[InterpreterResult][85]** The result of the program execution
Returns **[InterpreterState][84]** The result of the program execution

## Stack

@@ -418,7 +437,7 @@ The Memeforth program stack.

### Parameters

- `arr` **[Array][80]<any>?** The initial stack to use, as an array.
- `arr` **[Array][82]<any>?** The initial stack to use, as an array.

### pop

@@ -568,38 +587,42 @@ Push a value onto the top of the stack.

[67]: #dictionary

[68]: #interpreterresult
[68]: #ifword

[69]: #parameters-32

[70]: #doloop

[69]: #properties-1
[71]: #parameters-33

[70]: #interpret
[72]: #interpret

[71]: #parameters-32
[73]: #parameters-34

[72]: #runmemeforth
[74]: #runmemeforth

[73]: #parameters-33
[75]: #parameters-35

[74]: #stack
[76]: #stack

[75]: #parameters-34
[77]: #parameters-36

[76]: #pop
[78]: #pop

[77]: #push
[79]: #push

[78]: #parameters-35
[80]: #parameters-37

[79]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[81]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[80]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[82]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[81]: #interpreterstate
[83]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[82]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[84]: #interpreterstate

[83]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError
[85]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError

[84]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError
[86]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError

[85]: #interpreterresult
[87]: #stack

+ 5
- 4
dictionary.js View File

@@ -3,11 +3,12 @@
* @property {Array<any>} stack The current stack
* @property {Array<any>} tokens The current tokenized program
* @property {Object} words The current set of defined words
* @property {Array<any>} memory The current interpreter "memory".
* @property {string} currentWord The current word being defined.
* @property {string} output The output from printing commands.
*/

/**
* @summary Converts the top of the stack to :hacker_X: emojis.
* @param {Array<string>} stack The Forth stack.
/**
* Converts the top of the stack to :hacker_X: emojis.
* @param {InterpreterState} state The current interpreter state.
*/
@@ -49,7 +50,7 @@ const sm64 = state => {
};

/**
* @summary Concatenates the top two elements on the stack.
* Concatenates the top two elements on the stack.
* @param {InterpreterState} state The current interpreter state.
*/
const concat = state => {


+ 20
- 14
memeforth.js View File

@@ -3,6 +3,13 @@
const dictionary = require("./dictionary");
const Stack = require("./stack");

/**
* Parse an IF block.
*
* @param {InterpreterState} state The current interpreter state.
*
* @throws {SyntaxError} Throws an exception if no closing THEN is found.
*/
const ifword = state => {
const condition = state.stack.pop();
let ifBody = [];
@@ -43,6 +50,13 @@ const ifword = state => {
return state;
};

/**
* Parse a DO loop.
*
* @param {InterpreterState} state The current interpreter state.
*
* @throws {SyntaxError} Throws an exception if no closing LOOP is found.
*/
const doLoop = state => {
const endTokenIdx = state.tokens.indexOf("LOOP");

@@ -86,19 +100,10 @@ const doLoop = state => {
return state;
};

/**
* @typedef {Object} InterpreterResult
* @property {String} output The output as a result of TYPE/./.S commands.
* @property {Array<any>} stack The final stack when the program finished.
* @property {Object} words The set of words after the program executed, including any that were defined during execution.
*/

/**
* Interprets a Forth token list.
* @param {Array<string>} tokens The tokens to interpret, in order.
* @param {Array<any>} stack The initial Forth stack to use. Empty by default.
* @param {Object} words The initial set of words to use. Defaults to `dictionary`.
* @return {InterpreterResult} The result of the program execution
* @param {InterpreterState} state The initial state of the interpreter.
* @return {InterpreterState} The final state of the interpreter after execution.
*/
const interpret = state => {
if (!state.words) state.words = dictionary;
@@ -149,10 +154,11 @@ const interpret = state => {
};

/**
* @summary Runs a Forth program and returns the stack.
* Runs a Forth program and returns the stack.
* @param {string} program A Forth program, in string form.
* @param {Array<any>} stack The initial stack to use
* @return {InterpreterResult} The result of the program execution
* @param {Stack} stack The initial stack.
* @param {Array<any>} memory The intial memory.
* @return {InterpreterState} The result of the program execution
*/
const runMemeForth = (program, stack = new Stack(), mem = []) => {
const initState = {


+ 1
- 0
test/memeforth.test.js View File

@@ -31,6 +31,7 @@ describe("interpreter", () => {

expect(() => mf.run(program)).to.throwException(e => {
expect(e).to.be.a(SyntaxError);
expect(e.message).to.match(/Unclosed string/);
});
});



Loading…
Cancel
Save