notes on forth programming in collapse os

part 01: getting started

how to even go about playing with collapse os

you can try collapse os in your browser (requires javascript), or try it from your computer's terminal:

  1. mkdir collapseos && cd collapseos (make a directory called "collapseos" and go into it)
  2. wget http://collapseos.org/files/collapseos-latest.tar.gz (download the latest source code archive)
  3. tar -xf collapseos-latest.tar.gz (unpack the source code archive)
  4. cd cvm/ && make (go into the c virtual machine directory and build the executable file)
  5. ./cos-serial (start the virtual machine program)

whether in you're using the in-browser or terminal version of the emulator, you should get a message that says "Collapse OS ok", which means it's ready for you to start entering commands.

the stack

basically whenever you type a number in forth, it goes onto the stack, a list of numbers that are available to work with. the most recently entered numbers are "on top" of the stack, and generally must be moved before anything below them can be accessed.

.S [dot s] is a word that displays the stack. in collapse os, its output looks something like this:

SP 02 RS 04 -- 0004 0003  ok

"SP 02" indicates that there are two items currently on the stack, and to the right of the dash, they are listed as "0004" and "0003". the further left an item is in this list, the closer to the top of the stack it is.

comments

( [left paren] is a word that indicates the beginning of a comment. you end a comment with ) [right paren]. in collapse os, right paren is a word, therefore there must be a space between the end of the comment and right paren. (in some other forth dialects, this is not the case.)

a useful type of comment tells readers (such as your future self) what items are expected to be on the stack before using a word, and what will be placed on the stack when it's done. the format is generally something like ( n1 n2 -- sum ), where the items to the left of the dash represent what the word takes off the stack, and items to the right represent what the word leaves on the stack when done.

printing text

if you load block 123 (enter 123 LOAD at the collapse os terminal), you can then use the word clrscr to clear the screen. this is useful if your screen is full of commands that are no longer relevant--or, like starting forth mentions, if you're playing a guessing game with someone and want to hide the number you typed before handing the terminal over to the other person.