From 25ecb947f3b832c31ea049ba06187580833c90c2 Mon Sep 17 00:00:00 2001 From: dan Date: Wed, 31 May 2023 22:06:58 -0400 Subject: docs: update readme and rlwrap completions with new commands --- readme.md | 48 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 7 deletions(-) (limited to 'readme.md') diff --git a/readme.md b/readme.md index b5a0a5a..633a562 100644 --- a/readme.md +++ b/readme.md @@ -1,16 +1,50 @@ -Forth-style Stack Language with C and JS implementations. +Forth-style Stack Language in C. Runs natively or, in browser via wasm. -JS implementation can be run by opening index.html in a web browser or running `node forth.js`. +Live demo at [https://danielrholland.codeberg.page/forth-style-stack-lang/](https://danielrholland.codeberg.page/forth-style-stack-lang/) -Assuming you have clang and make installed, the C implementation can be built with `make build`, then run with `./forth`. +Assuming you have clang and make installed, the native executable can be built with `make build`, then run with `./forth`. If you also have rlwrap installed, you can run `make run-rlwrap`, to get completions, history, and more pleasant line-editing. -_Be aware:_ +`make build-wasm` will build the wasm version. Serve `./forthlib.wasm`, `forthlib.js`, `forth.js` and `index.html` from a web server and open `index.html` to use it. - - Neither implementation is finished - - The implementations have some subtle differences - - This is a toy, not intended for serious use +---- + +Current builtin operations: + + - `.` - pop and print val + - `peek` - peek and print val + - `+` - pop top two vals and push second+top + - `-` - pop top two vals and push second-top + - `*` - pop top two vals and push second*top + - `/` - pop top two vals and push second/top + - `negate` - replace top val with 0 - value + - `abs` - replace top val with its absolute + - `mod` - second modulo top + - `max` - largest of top two vals + - `min` - largest of top two vals + - `dup` - duplicate top val + - `not` - if top val is 0 set to 1, else set to 0 + - `=` - pop top two vals + - `swap` - swap order of top two vals + - `drop` - discard top val + - `over` - copy second val and push it + - `rot` - rotate top three vals - top to third, second to top, third to second + - `pick` - pop a val n, then copy the nth value down from the top and push it + - `roll` - pop a val n, then copy the nth value down from the top and push it + - `depth` - push that stack size + - `clearstack` - clear the stack + - `if then ` - an optional section. `if` pops a val, and if that val is 0, skips to then. (Branch if zero) + - `: ;` - a procedure declaration. A new op is added, when it is run, the tokens in the body are evaluated. e.g. `: decr 1 - ; ` will define a new operation `incr`, that increments the valu at the top of the stack. + - `nip` - discards the second val from the top + - `tuck` - copies the top val and inserts it between the second and third + - `incr` - increments the top value + +Literals are pushed. + +At present only integers are supported. + +At present, loops haven't been added, just use recursion. ---- -- cgit v1.2.3