collapseos/doc/usage.txt

# Collapse OS usage guide

If you already know Forth, start here. Otherwise, read primer
first.

We begin with a few oddities in Collapse OS compared to tradi-
tional forths, then cover higher level operations.

# Signed-ness

For simplicity purposes, numbers are generally considered
unsigned. For convenience, decimal parsing and formatting
support the "-" prefix, but under the hood, it's all unsigned.

This leads to some oddities. For example, "-1 0 <" is false.
To compare whether something is negative, use the "0<" word
which is the equivalent to "0x7fff >".

# Branching

Branching in Collapse OS is limited to 8-bit. This represents
64 word references forward or backward. While this might seem
a bit tight at first, having this limit saves us a non-
negligible amount of resource usage.

The reasoning behind this intentional limit is that huge
branches are generally an indicator that a logic ought to be
simplified. So here's one more constraint for you to help you
towards simplicity.

# Interpreter I/O

The INTERPRET loop, the heart of Collapse OS, feeds itself
from the C< word, which yields a character every time it is
called. If no character is available to interpret, it blocks.

During normal operations, C< is simply a buffered layer over
KEY, which has the same behavior (but unbuffered). Before
yielding any character, the C< routine fetches a whole line
from KEY, puts it in a buffer, then yields the buffered line,
one character at a time.

Both C< and KEY can be overridden by setting an alternate
routine at the proper RAM offset (see impl.txt). For example,
C< overrides are used during LOAD so that input comes from disk
blocks instead of keyboard.

KEY overrides can be used to, for example, temporarily give
prompt control to a RS-232 device instead of the keyboard.

Interpreter output is unbuffered and only has EMIT. This
word can also be overriden, mostly as a companion to the
raison d'etre of your KEY override.

# Addressed devices

A@ and A! are the indirect versions of C@ and C!. Their target
word is controlled through A@* and A!* and by default point to
C@ and C*. There is also a AMOVE word that is the same as MOVE
but using A@ and A!.

# Disk blocks

Disk blocks are Collapse OS' main access to permanent storage.
The system is exceedingly simple: blocks are contiguous 
chunks of 1024 bytes each living on some permanent media such
as floppy disks or SD cards. They are mostly used for text,
either informational or source code, which is organized into
16 lines of 64 characters each.

Blocks are referred to by number, 0-indexed. They are read
through BLK@ and written through BLK!. When a block is read,
its 1024 bytes content is copied to an in-memory buffer
starting at BLK( and ending at BLK). Those read/write
operations are often implicit. For example, LIST calls BLK@.

When a word modifies the buffer, it sets the buffer as dirty
by calling BLK!!. BLK@ checks, before it reads its buffer,
whether the current buffer is dirty and implicitly calls BLK!
when it is.

The index of the block currently in memory is kept in BLK>.

Many blocks contain code. That code can be interpreted through
LOAD. Programs stored in blocks frequently have "loader blocks"
that take care of loading all blocks relevant to the program.

Blocks spanning multiple disks are tricky. If your media isn't
large enough to hold all Collapse OS blocks in one unit, you'll
have to make it span multiple disks. Block reference in
informational texts aren't a problem: When you swap your disk,
you mentally adjust the block number you fetch.

However, absolute LOAD operations in Collapse OS aren't aware
of disk spanning and will not work properly in your spanned
system.

Although the usage of absolute LOAD calls are minimally used
(relative LOADs are preferred), they are sometimes unavoidable.
When you span Collapse OS over multiple disks, don't forget to
adjust those absolute LOADs.

# How blocks are organized

Organization of contiguous blocks is an ongoing challenge and
Collapse OS' blocks are never as tidy as they should, but we
try to strive towards a few goals:

1. Block 0 contains documentation discovery core keys to the
   uninitiated.
2. B1-B4 are for a master index of blocks.
3. B5-B199 are for runtime usage utilities
4. B200-B599 are for bootstrapping
5. The rest is for recipes.

Blocks are currently not organized neatly. I'm planning the
extraction of recipes into some kind of block "overlays" that
would live in the recipes subfolder so each recipe would build
its own specific blkfs which would contain only its recipe code,
starting at B600.