5.9.8.3 Advanced does> usage example

The MIPS disassembler (arch/mips/disasm.fs) contains many words for disassembling instructions, that follow a very repetetive scheme:

     :noname disasm-operands s" inst-name" type ;
     entry-num cells table + !

Of course, this inspires the idea to factor out the commonalities to allow a definition like

     disasm-operands entry-num table define-inst inst-name

The parameters disasm-operands and table are usually correlated. Moreover, before I wrote the disassembler, there already existed code that defines instructions like this:

     entry-num inst-format inst-name

This code comes from the assembler and resides in arch/mips/insts.fs.

So I had to define the inst-format words that performed the scheme above when executed. At first I chose to use run-time code-generation:

     : inst-format ( entry-num "name" -- ; compiled code: addr w -- )
       :noname Postpone disasm-operands
       name Postpone sliteral Postpone type Postpone ;
       swap cells table + ! ;

Note that this supplies the other two parameters of the scheme above.

An alternative would have been to write this using create/does>:

     : inst-format ( entry-num "name" -- )
       here name string, ( entry-num c-addr ) \ parse and save "name"
       noname create , ( entry-num )
       latestxt swap cells table + !
     does> ( addr w -- )
       \ disassemble instruction w at addr
       @ >r
       disasm-operands
       r> count type ;

Somehow the first solution is simpler, mainly because it's simpler to shift a string from definition-time to use-time with sliteral than with string, and friends.

I wrote a lot of words following this scheme and soon thought about factoring out the commonalities among them. Note that this uses a two-level defining word, i.e., a word that defines ordinary defining words.

This time a solution involving postpone and friends seemed more difficult (try it as an exercise), so I decided to use a create/does> word; since I was already at it, I also used create/does> for the lower level (try using postpone etc. as an exercise), resulting in the following definition:

     : define-format ( disasm-xt table-xt -- )
         \ define an instruction format that uses disasm-xt for
         \ disassembling and enters the defined instructions into table
         \ table-xt
         create 2,
     does> ( u "inst" -- )
         \ defines an anonymous word for disassembling instruction inst,
         \ and enters it as u-th entry into table-xt
         2@ swap here name string, ( u table-xt disasm-xt c-addr ) \ remember string
         noname create 2,      \ define anonymous word
         execute latestxt swap ! \ enter xt of defined word into table-xt
     does> ( addr w -- )
         \ disassemble instruction w at addr
         2@ >r ( addr w disasm-xt R: c-addr )
         execute ( R: c-addr ) \ disassemble operands
         r> count type ; \ print name

Note that the tables here (in contrast to above) do the cells + by themselves (that's why you have to pass an xt). This word is used in the following way:

     ' disasm-operands ' table define-format inst-format

As shown above, the defined instruction format is then used like this:

     entry-num inst-format inst-name

In terms of currying, this kind of two-level defining word provides the parameters in three stages: first disasm-operands and table, then entry-num and inst-name, finally addr w, i.e., the instruction to be disassembled.

Of course this did not quite fit all the instruction format names used in insts.fs, so I had to define a few wrappers that conditioned the parameters into the right form.

If you have trouble following this section, don't worry. First, this is involved and takes time (and probably some playing around) to understand; second, this is the first two-level create/does> word I have written in seventeen years of Forth; and if I did not have insts.fs to start with, I may well have elected to use just a one-level defining word (with some repeating of parameters when using the defining word). So it is not necessary to understand this, but it may improve your understanding of Forth.