Here, you can find documentation for ScratchForth, excluding how each individual block is represented.

Since ScratchForth directly maps to SBF, you can also use this to learn more about SBF itself.

As is mentioned in SBF documentation, you have an option of pushs and pushc to push to the stack.

In ScratchForth, these are represented respectively by double and single quotes (think like how C-family languages use double-quotes as string literals and single-quotes as char literals).

For instance, to push "Hello world!" to the stack, you'd just use this:

"Hello world!"

Additionally, to push the number 2 to the stack, since it is one character, you'd use this:

'2'

To add comments to your code, just start the line with a #. Note that this must be the start of the line, though. If anywhere else, your code will likely not compile correctly.

Like how in C/C++, you use # to signify compiler instructions, you do the same in ScratchForth with $.

To import a module, you use this format:

$include path/to/module.sfth

The path is relative to the file location.

In the future, you will be able to import from the standard library using this format:

$include <lists>

However, the standard library has not been created yet, so this is not a feature currently.

Macros allow you to repeat code without having to write it. It is best to use labels/functions where possible to prevent the binary output from being too long, but macros can be useful, for example in the call instruction.

To create a macro, you enclose the macro in %s and start the string with the name of the macro.

For example:

% callFunction LABEL:FN_LABEL call %

You use the macro by simply typing the name of the macro where needed.

Labels allow control structures to be used.

To use labels, you need to know how to define them and how to push them to the stack.

To define a label, you just put a : and the label name.

For example, :LABEL1 is a valid label definition.

The label stores its location in the binary output, so you can jump to it later on.

To push a label to the stack, you just put LABEL: and the label name.

For example, LABEL:LABEL1.

Jumps allow you to jump to various points in the code. These are where you use labels.

These jumps can be conditional as well, meaning that it will jump to a position if something else is true.

These jumps can also be calls or gotos. Calls return to where they were called with the ret instruction, while gotos don't add anything to the call stack and just modify the current location pointer.

Calls are ideal for functions while gotos are ideal for loops and conditionals.

Jumps can be either call, callif, goto, or gotoif.

The label to jump to is always the latest on the stack.

For conditional jumps, you use either the callif or gotoif instructions.

In these cases, before the label, you put a condition.

For example, see this from the example code:

'1' getvar "10" <
LABEL:LBL1
gotoif

Here, it first checks if the first variable is less than 10. If true, it adds 1 to the stack (booleans are represented by integer counterparts in ScratchForth). Then, it adds the position of the label, LBL1. Then, it runs gotoif which will go to LBL1 if variable 1 is less than 10.