guava/README.md -rw-r--r-- 5.0 KiB
446de4d1eli_oat Updated COOKBOOK 2 months ago


Guava is a stack-based, concatenative language and editor for the browser intended to be used for scripting and as a DSL for small web projects.

Guava is born from Ripen, by Felix with ample influence from RetroForth.

It is a toy for exploring concatenative language design, and the DOM. It could also easily be used as a scripting interface for a larger project. I use it instead of building out input forms to interact with REST APIs.

Guava supports arithmetic, control structures, basic DOM manipulation, object parsing and very simple HTTP requests (GET and POST).

Guava is an unusual language inspired by other unusual languages. While not strictly necessary, being loosely familiar with Forth is helpful when playing with Guava. Guava isn't a Forth, but it is closer to a Forth than it is to something like JavaScript, C, or Lua.

Here is a good place to start with learning Forth. Or here, and for fun, here, too!


A major goal of Guava is keeping the entire language tiny and easily learnable. With this as a goal, the dictionary is kept relatively limited.

The dictionary is broken into 2 categories -- words and sigils.

Words are akin to keywords or in-built functions in other languages while sigils are prefixes that guide the interpreter, switching it into different modes (roughly speaking).


#> ( ) * */ + ++ - -- -eq? -if -rot . .s / /* /mod 2dup 
; <# [ ] abs alert and assert assert:false assert:true 
buffer clear confirm cr dec depth drop dup el:a el:append 
el:b el:clear el:h1 el:h2 el:h3 el:html el:i el:p el:root 
emit eq? execute false gt? gteq? http:get http:post if 
inc kv:get kv:remove kv:set lt? lteq? max min mod negate 
not obj:parse or over pokedex prompt repeat rot sigils 
space swap times true until while words { }


! ' / : ?


Like most stack-based languages, Guava relies on reverse Polish notation and a LIFO, "last in, first out, memory stack."

Most programming languages use infix notation, e.g. 3 + 3. If you've used Lisp or Scheme you may be familiar with prefix notation, e.g. + 3 3. Reverse Polish notation is the opposite of prefix notation -- 3 3 +.

The stack is how data flows through a stack-based language where data is added and removed from the "top," sort of like a stack of dishes. At first blush it seems like stack manipulation is all that a programmer using a stack-based language would be doing all day long, while in reality most folks using stack-based languages tend to keep the stack pretty shallow -- Guava also offers an escape hatch, allowing for easy use of variables outside of the context of the stack...which some may say is cheating, but we don't need that kinda gate keeping.

For more info on how to use Guava, see the cookbook.


A lot of programming languages are pretty similar to one another -- once you learn the core constructs of programming (control flow, data handling and storage, etc.) it becomes relatively easy to pick up new languages...the hiccup, I find, comes from needing to learn new tooling. Tooling can be inscrutable, and it is often assumed that you just sort of know it...but it is rarely really taught. For this reason an editor is provided for Guava.

The editor is comprised for 2 parts, an area to display output and an area to collect input. Full disclosure, the area to display output (e.g. console) has a few quirks to it that I'm still trying to work out. If these are a hindrance, you can open up the console of your browser for a more direct view of what is going down.

Screenshot of the Guava editor in action

Code can be input into the lower textarea, clicking the "run" button will interpret the code. Any text entered into the textarea is saved to the browser's local storage with each keystroke.

The "clean" button empties the stack and clears the data from the output area.

The "destroy" button completely clears all inputted code and resets the environment.

Clicking "export" prompts to save input code to disk.

At the far right is a "choose file" button -- this allows you to load data from disk. NOTE the data is read in from the disk, but any edits aren't saved back to the disk unless you click the "export" button.

An instance of Guava is currently accessible at https://txt.eli.li/pb/guava.


Ripen was originally released under the ARTISTIC LICENSE 2.0. With permission from Felix, Guava is licensed under the MIT LICENSE.