Forth in Javascript

Why?

I hear you ask why, which is hardly surprising.

• Forth was the first language I got good at
• Javascript is the language I like to play in now
• You can run it in any browser, and on a server, and on some embedded devices
• Its modular enough that I could replace the JS with C, C++, Wasm or Assembler.
• Much of the Forth I've seen has been really antiquated, or over-complex, needs a fresh approach

Installation

The only prerequisite is node and npm (or yarn).

npm install webforth

Installs webforth, note there are intentionally no dependencies in the browser versions, and the only dependency in the node version is to the builtin fs

If you only want to host the web version, then cloning the git repo should be sufficient.

Running

const {Forth, ForthNodeExtensions} = require('webforth');

Or alternatively

import {Forth, ForthNodeExtensions} from 'webforth';

Then ...

const foo = new Forth({extensions: ForthNodeExtensions);
foo.compileForthInForth()
  .then(() => foo.interpret('1 2 3 ROT .S')) // Pass forth to interpret
  .then(() => foo.console()) // Interactive console
  .catch((err) => console.log('Error',err));

This ...

• loads a bootstrap JS interpreter;
• loads forth into it;
• switches to the forth interpreter
• Starts a full forth console.

Try 1 2 3 ROT .S A simple forth command and output the stack

This is an experimental API - it might change,

• see any discussion in: issue#23.

In particular, we will be adding ability to load forth files into an instance.

Note, it should be possible to run multiple instances, but this isn't tested fully yet. e.g.

import {Forth, ForthNodeExtensions} from webforth;
const foo1 = new Forth({extensions: ForthNodeExtensions});
const foo2 = new Forth({extensions: ForthNodeExtensions});
foo2.compileForthInForth().then(() => foo2.console());
foo1.compileForthInForth().then(() => foo1.interpret('1 2 .S'));

Running in a browser

You should be able to run this at https://mitra.biz/forth/console.html

To make your own copy, clone the repo,

Start a simple http server such as that included in Node

cd webforth # Or wherever you cloned it
http-server &

Open http://localhost:8080/console.html in a browser.

The HTML uses Web Components and TextEncoders, so they should work in any modern browsers such as: Firefox, Chrome, Opera, Edge, Android, iOS. It runs in Safari on OSX but slowly.

The phone experience of console.html is suboptimal, I might get around to doing a mobile friendly version eventually, but if someone else does then I'll be happy to apply a PR.

It should compile Forth (you can verify in the web console) and present a console and entry box in which you can type any Forth.

Everything is happening locally i.e. this is forth running in your browser.

Debugging

For the browser version open the Console. The process of building the dictionary puts errors and progress there.

Feel free to open a new issue on the git repo but the first thing I'm going to ask for is a copy of whatever appeared in the Console, or in Node.

There are two useful Forth words you can insert in either a definition, or the code to help debug.

• testFlags is a Forth variable allowing different levels of debugging. Its binary:
  • 0x01 trace the interpreter as it loads lines
  • 0x02 trace threading (slows it down a lot!)
  • 0x04 enable any safety checks (currently there are not any)
  • 0x08 run incremental tests during bootstrapping - good for catching bugs.
• testDepthOffset can be set to change the number of levels deep that threading is traced
• Fbreak: Just calls a short routine that generates a console log, when working in my IDE I set a breakpoint here.

TODO - document how to run ANS tests from separate repo

Arduino Support

See [docs/Cross Compiling.md](docs/Cross Compiling.md)

File support

It supports the Forth2012 file extension words REQUIRE INCLUDE etc

Because browsers don't have access to fs it uses a separate class that imports fs.

cd scripts
node /forth_console_with_fs_via_node.js
...
webFORTH V0.00.15
REQUIRE ../sandbox/tester.f
\ This will load the forth in tester.f and anything that file INCLUDEs

File support is in its early days and I want to extend it to be web-aware.

Standard support

This is intended to be standards compliant, but then Forth has multiple standards!

Its status, and progress to passing the FORTH2012 test suite is visible in issue#83, as of now (Aug 2023):

• it implements and passes: core, coreplus, coreext
• The following are in theory fully implemented but fail at least one test: files;
• The following extensions are partially implemented so fail on unimplemented words: strings; double;
• there has been no attempt to implement so the following Hayes tests fail: block; Vocabularies so searchordertest;
• Unclear on the status of: locals; memory allocation; tools; facilitytest
• exceptions
  • fails one test (ABORT"), but the standard for THROW has problems.

In addition it does not implement (not tested by Hayes) the Forth2012 word: ENVIRONMENT?

Contributing

Yes please !

Please introduce yourself on issue#1

Pull requests are welcome, and even quite significant changes at this stage, but let us discuss first (open a new issue in GIT).

Cutting a release

• Run a code inspection - surprising how many bugs this ESLint, or most IDE's catch !
• Update CHANGELOG.md
• Check README.md reflects any changes
• Update VER in index.js and version in package.json to next even number
• npm publish
• push to git on master branch
• Update VER in index.js and version in package.json to next odd number
• npm update; npm install
• Check how to update on mitra.biz so Console runs new one ....