0xFF | thinking is a momentary dismissal of irrelevancies
posted by Andreas Bernhard Wagner on Jul 15, 2016

Unfortunately, a lot of Forth written today has C inspired formatting.

The classic, and (I feel) clearest way to format Forth is to align corresponding or related things.

When corresponding fragments are aligned the code is easier to walk through and may expose some common factors that can be pulled out into their own word.

samples

From forth-crypt:

\ RSA Digital Signature ( Notice the spacing )
 : signat (   c-addr u -- s )  hash      pub-key N rsa   ;
 : verify ( s c-addr u -- f )  hash swap prv-key N rsa = ;

From my Winbond SPI Flash driver:

: buf>spi ( buf-addr -- ) block-size bounds ?do       i c@ c!spi loop ;
: spi>buf ( buf-addr -- ) block-size bounds ?do c@spi i c!       loop ;
: write +write $02 cmd ; : writing sector!spi buf>spi     ;
: read   ready $03 cmd ; : reading sector!spi     spi>buf ;

: wrote_page  ( buf-addr u -- ) write writing finished ;
: read_page   ( buf-addr u -- ) read  reading finished ;

In buf>spi it’s easy to see that something is being stored to SPI but nothing is being received…in clear contrast to spi>buf

Now check these out:

                           : READY    ( -- 0|1)
       CENTERS { 1 0 0 0 } ;
                           : STIMULUS ( -- 0|1)
SSUM { 0 0 1 0 0 0 0 0 0 } ;
                           : BRIAN'S-BRAIN
  STIMULUS READY AND >PLN0 ;

Definitions are conceptually all definitions, so they are aligned. : and ; go together too and names are also all names.

Another approach worth mentioning is left-aligning words that were CREATEd using lookahead and right aligning words that take from the stack.

: INCR                PH# 3 XOR TO PH# 1 0 SNUM 2@ D+ SNUM 2! ;
: PULL                              <PD P@REL DROP -1 LEVL +! ;
: ?PULL                                LEVL @ 0> IF PULL THEN ;

EDIT: The last two examples do violate the aforementioned formatting scheme of aligning identical segments and cannot be automated with a pretty printer, therefore I don’t endorse them.

Thanks /u/phalp for bringing these to my attention.

Now, you may be thinking that all this spacing wastes a lot of flash space. It’s also tedious add spacing here and there every time you add some words. That’s why Chuck Moore has lately been known to use no formatting at all.

auto-formatting in a block editor

To save space and expose factors, I’d like a block editor to do the above as I type or just something similar to the LIST, using sequence alignment – maybe with Hirschberg’s algorithm.

But that’s for another day.