Fleet Forth design considerations

[JimBoyd]

SamCoVT wrote:

This is part of the ANS-2012 standard (I checked the 94 and 83 versions and didn't see it mentioned there) in section 3.4.1.3. ANS-2012 also specifies the form 'c' which is for constant characters (rather than using CHAR or [CHAR]).

Fleet Forth conforms to the Forth-83 Standard, which seems more appropriate considering when the C64 came out, and I like the Forth-83 Standard better. Since Fleet Forth conforms to the Forth-83 Standard, I didn't include the form 'c'. I didn't want to add that much extra code. I use ASCII , the immediate state smart word replaced by CHAR and [CHAR] in the new standard.
Since Fleet Forth conforms to the Forth-83 Standard, there are some differences in how numeric strings are handled. The leading count is ignored and the numeric string must have a trailing space.

Quote:

Seeing as I might be the one to write it, I'm curious where you ended up temporarily putting the BASE value (return stack?) and how you signaled that BASE needed to be restored at the end?

Yes, I put the value of BASE on the return stack, or rather, I used a word that did. Fleet Forth has the word RB (restore base). When RB is used in a word, whatever the base was prior to executing RB is restored when that word exits, unless it aborts. -NUMBER never aborts. It passes a flag, FALSE for successful conversion, TRUE if it failed.
RB uses the word CO (coroutine).

Code: Select all

// COROUTINES
: CO   2R> SWAP 2>R ;
// RESTORE BASE AT END OF WORD
// CALLING RB
: RB  ( -- )
   BASE @ R> 2>R  CO
   R> BASE ! ;

Here is the original version of -NUMBER

Code: Select all

: -NUMBER  ( ADR -- D FLAG )
   DPL ON  0 0 ROT
   DUP 1+ C@ ASCII - =
   DUP>R -  DUP>R
   BEGIN
      CONVERT DUP C@ VALID?
   WHILE
      DUP 1+ C@ VALID? 0=
   WHILE
      DPL OFF
   REPEAT
   THEN
   DUP C@ BL <> SWAP
   2-  DPL @ 0< - R> = OR
   R>  0EXIT  >R DNEGATE R> ;

Here is the modified version of -NUMBER

Code: Select all

HEX
NH
CREATE BASE.TABLE
   0A C, 10 C, 2 C,

: -NUMBER  ( ADR -- D FLAG )
   RB
   DUP 1+ C@ ASCII # - DUP 3 U<
   IF
      BASE.TABLE + C@ BASE !
      1+ DUP
   THEN
   DROP
   DPL ON  0 0 ROT
   DUP 1+ C@ ASCII - =
   DUP>R -  DUP>R
   BEGIN
      CONVERT DUP C@ VALID?
   WHILE
      DUP 1+ C@ VALID? 0=
   WHILE
      DPL OFF
   REPEAT
   THEN
   DUP C@ BL <> SWAP
   2-  DPL @ 0< - R> = OR
   R>  0EXIT  >R DNEGATE R> ;

NH is a metacompiler word that causes the following word to be compiled without a header.
VALID? is a word that takes a character and returns a true flag if it is valid punctuation for a number. It is a deferred word and the default is to only accept a period as valid.
For completeness, here is the source for CONVERT

Code: Select all

: CONVERT  ( D1 ADR1 -- D2 ADR2 )
   1+
   BEGIN
      COUNT BASE @ DIGIT
   WHILE
      2SWAP BASE @ *
      SWAP BASE @ UM* D+
      ROT
      DPL @ 0< 1+ DPL +!
   REPEAT
   1- ;

DIGIT takes the character to be converted and the number base to use. It returns the digit as a single cell number and a true flag or just a false flag if the character is not a digit in the specified base.
( CHR #BASE -- N TF )
( CHR #BASE -- FF )

[SamCoVT]

JimBoyd wrote:

Fleet Forth conforms to the Forth-83 Standard, which seems more appropriate considering when the C64 came out, and I like the Forth-83 Standard better. Since Fleet Forth conforms to the Forth-83 Standard, I didn't include the form 'c'.

Are the # $ and % forms in the 83 standard? I couldn't find them. I guess what I meant to say is that I've only seen those forms mentioned in the 2012 standard. It does seem useful to me, though, to be able to specify constants in regular Forth code without having to switch the base. I've definitely been bit several times when my 10 was 16 and #10 could have been useful!

JimBoyd wrote:

Yes, I put the value of BASE on the return stack, or rather, I used a word that did. Fleet Forth has the word RB (restore base). When RB is used in a word, whatever the base was prior to executing RB is restored when that word exits, unless it aborts. -NUMBER never aborts. It passes a flag, FALSE for successful conversion, TRUE if it failed.
RB uses the word CO (coroutine).

Code: Select all

// COROUTINES
: CO   2R> SWAP 2>R ;
// RESTORE BASE AT END OF WORD
// CALLING RB
: RB  ( -- )
   BASE @ R> 2>R  CO
   R> BASE ! ;

... because of course your forth has coroutines! That's pretty nifty, and I may have to play around with that.

I will probably just toss the BASE on the return stack because the number processing is written in assembly in Tali2. I think your method of just always tossing the original BASE on the return stack and restoring it regardless of what happened is the way to go. That way I won't need a flag to remember if I need to restore it later or not.

Your trick with the BASE.TABLE is pretty slick. I did not notice before that #, $, and % are all right next to each other in the ASCII table. I was looking through your code trying to see where you compared to those characters and I only saw #. Then I saw you looking up in the table with an index and I had to go pull up an ASCII table. Very nice.

Thanks for the detailed response. It's neat to see how other people tackle a problem. The other neat thing (for me) is that I was able to read/understand your Forth code. When I first starting playing around with Forth, reading other people's code was quite difficult for me. I'll also give a shout out to Garth's suggestions for making things visually clear with indentation and spacing.

[JimBoyd]

SamCoVT wrote:

Are the # $ and % forms in the 83 standard?

No. I guess you could say I added them as a non standard extension.

Quote:

It does seem useful to me, though, to be able to specify constants in regular Forth code without having to switch the base. I've definitely been bit several times when my 10 was 16 and #10 could have been useful!

Exactly. It's a convenience that shouldn't have much impact on portability with, in my case, other Forth-83 systems.

Quote:

Your trick with the BASE.TABLE is pretty slick. I did not notice before that #, $, and % are all right next to each other in the ASCII table. I was looking through your code trying to see where you compared to those characters and I only saw #. Then I saw you looking up in the table with an index and I had to go pull up an ASCII table. Very nice.

Thank you. I didn't notice that #, $, and % are next to each other either, until I looked at their values in binary. I was trying to find a way to manipulate the numbers that would yield a small solution before settling on using the table.

Quote:

Thanks for the detailed response. It's neat to see how other people tackle a problem. The other neat thing (for me) is that I was able to read/understand your Forth code. When I first starting playing around with Forth, reading other people's code was quite difficult for me. I'll also give a shout out to Garth's suggestions for making things visually clear with indentation and spacing.

Poorly formatted source only contributes to Forth's write only reputation. The following is a sample of source code for another Forth for the C64. It's not for the multitasker (this Forth didn't have one), it does the same thing as Fleet Forth's DONE? .

Code: Select all

: PAUSE   ?KEY ?DUP IF 3 <> IF KEY 3 = ELSE TRUE THEN
                    ELSE FALSE THEN ;

?KEY returns a zero if no key was pressed or the value of the key that was pressed.
KEY waits for a keypress and returns the value of that press. It calls ?KEY in a loop.
I don't care that this was from source that was in Forth blocks, it's not worth saving blocks if the control flow is difficult to follow.

Code: Select all

: PAUSE  ( -- F )
   ?KEY ?DUP
   IF
      3 <>
      IF  KEY 3 =  ELSE  TRUE  THEN
   ELSE
      FALSE
   THEN ;

This version of formatting is easier to follow and, I think, easier to improve (hint: TRUE , FALSE , and both ELSEs are not needed in the improved version).

[GARTHWILSON]

JimBoyd wrote:

No. I guess you could say I added them as a non standard extension.

As long as things don't conflict, it's nice when you can accommodate multiple standards. The only drawback is that it takes more memory.

Quote:

Your trick with the BASE.TABLE is pretty slick. I did not notice before that #, $, and % are all right next to each other in the ASCII table.

I hadn't noticed that either.

Quote:

The other neat thing (for me) is that I was able to read/understand your Forth code. When I first starting playing around with Forth, reading other people's code was quite difficult for me. I'll also give a shout out to Garth's suggestions for making things visually clear with indentation and spacing.

Forth has been called a write-only language, ie, that it's unreadable. I blame that on the programmer though, not the language. I had an article in Forth dimensions in the early 90's on making Forth more readable. Hopefully my own programming has further improved since then. My article-writing definitely has. To be frank, most people's assembly language on 6502.org is also very difficult to read, and I often have to copy it to my text editor and massage it some to figure out what they're trying to do.

Quote:

The following is a sample <snip>

The first sample follows what so many Forthers are dogmatic about, that definitions should be limited to two lines. This kind of dogma hurts readability. It tends to result in over-factoring too, taking more memory for all the unnecessary headers for factors that are only used once, more time to run because of the extra nesting, and it can be hard sometimes to come up with a descriptive name for the factor that is any shorter than the code it replaces! There was a regular contributor to Forth Dimensions magazine who defended this strongly, and said screens should be viewed as 3x5 cards. He kept pushing this as a plus, yet I just saw it as inadequate room to make things clear and add adequate comments. Then in a private mail exchange (which today we would do by email, but back then it was on paper), he sent me his code for something we were discussing, and he had a definition that was over 100 lines long! I didn't call out his hypocrisy.

Quote:

(hint: TRUE , FALSE , and both ELSEs are not needed in the improved version).

In the two-line version it's particularly easy to miss the fact that those could be eliminated to improve both readability and efficiency.

[barrym95838]

Here's my clumsy stab at it:

Code: Select all

: PAUSE  ( -- F )
   ?KEY DUP IF
      DUP 3 <> IF
         DROP KEY THEN
      3 = THEN
;

Am I in the right ballpark?
[Edited to try to balance the stack, probably while Garth was reading my first attempt ...]

P.S. eFORTH has the stack comment for ?KEY as ( -- c T | F ) , so in that case I would get rid of my second DUP ... at least I think that's what I'd try ... eh, I'm all messed up! I'll try again when my head's screwed on the right way!

P.P.S. I think I would have to DROP the T, like so:

Code: Select all

: PAUSE  ( -- F )
   ?KEY DUP IF
      DROP DUP 3 <> IF
         DROP KEY THEN
      3 = THEN
;

... but that doesn't seem any better than the original! Back to the drawing board!

[JimBoyd]

barrym95838 wrote:

Here's my clumsy stab at it:

Code: Select all

: PAUSE  ( -- F )
   ?KEY DUP IF
      DUP 3 <> IF
         DROP KEY THEN
      3 = THEN
;

Am I in the right ballpark?

Yes, but I like the factoring where both THEN's are one after the other followed by the semicolon. I'll show why.

Quote:

P.S. eFORTH has the stack comment for ?KEY as ( -- c T | F )

In Fleet Forth it's ( -- c | 0 ) because that is what the C64 kernal supports.
PAUSE is the name of Fleet Forth's task switcher (which is set to a no-op when not multitasking), so I'm just going to call this word DONE? , which is what it is called in Fleet Forth.

Code: Select all

: DONE?  ( -- F )
   ?KEY ?DUP
   IF
      3 <>
      IF  KEY 3 =  ELSE  TRUE  THEN
   ELSE
      FALSE
   THEN ;

Notice the ELSE clause at the end of the word?

Code: Select all

ELSE
   FALSE
THEN ;

If ?DUP is replaced with DUP , that clause is no longer needed.

Code: Select all

: DONE?  ( -- F )
   ?KEY DUP
   IF
      3 <>
      IF  KEY 3 =  ELSE  TRUE  THEN
   THEN ;

In my ITC Forth, this saves 3 cells.
The next improvement is a little harder to see.
3 <> is equivalent to 3 = 0=
At first glance, this doesn't seem to save memory. if ?DUP is inserted between = and 0= the final ELSE clause is no longer needed.

Code: Select all

: DONE?  ( -- F )
   ?KEY DUP
   IF
      3 = ?DUP 0=
      IF  KEY 3 =  THEN
   THEN ;

A savings of another cell.
Fleet Forth also has the primitives ?EXIT and 0EXIT .
Both consume the top stack item.
?EXIT exits the word if the top stack item is TRUE (any non-zero value).
0EXIT exits the word if the top stack item is zero.
Using these two words, some more memory savings can be had, as well as a performance boost. Both IF's branch to the exit at the end of the word. They can both be replaced with 0EXIT and the THEN's removed.

Code: Select all

: DONE?  ( -- F )
   ?KEY DUP
   0EXIT
      3 = ?DUP 0=
      0EXIT  KEY 3 = ;

A little reformatting.

Code: Select all

: DONE?  ( -- F )
   ?KEY DUP 0EXIT
   3 = ?DUP 0= 0EXIT
   KEY 3 = ;

Finally, 0= 0EXIT can be replaced with ?EXIT

Code: Select all

: DONE?  ( -- F )
   ?KEY DUP 0EXIT
   3 = ?DUP ?EXIT
   KEY 3 = ;

[barrym95838]

My way of thinking FORTH is brutally incomplete, but I did think of ?EXIT briefly. It's kind of like a conditionally executed RTS in the middle of a subroutine, efficient but a bit lacking in what I perceive to be "structured" technique. Come to think of it, I often break those techniques when I'm doing my own thing, so ...

My (probably flawed) reasoning on the subject of where to place my IFs and ELSEs and THENs is that I feel weird needlessly inserting line breaks between the data or code and the word immediately responsible for consuming or executing it. In my example, the 3 <> is immediately consumed by the following IF, and the DROP KEY is within the execution scope of the following THEN ... kind of an "object verb verb" "noun noun verb" thing, like Yoda tends to use in his sentences. As my understanding hopefully improves, I may start to see things more the way you and Garth format your code, but many miles to go still have I ...

[GARTHWILSON]

Nothin' wrong with ?EXIT, as there's nothing pending on either stack like there would be with DO...LOOP (where you can remove the exit address, loop limit, and loop index with UNLOOP). Any of the structures will have stuff on the stack during compilation, but not necessarily at run time.

Putting the condition and flow-control words this way makes if very clear, and there's no visual searching:

Code: Select all

: FOOBAR    ( n1 -- n2 f )
   <do stuff>
   <condition?>
   IF    ┌─────────────────┐
         │ <do this stuff> │
         └─────────────────┘
   ELSE  ┌─────────────────┐
         │ <do this stuff> │
         └─────────────────┘
   THEN
   <do more stuff>    ;

But if you want the IF on the same line with the condition so the line is more stack-autonomous, you can re-arrange it this way:

Code: Select all

: FOOBAR    ( n1 -- n2 f )
   <do stuff>
   <condition?>          IF
   ┌─────────────────┐
   │ <do this stuff> │
   └─────────────────┘   ELSE
   ┌─────────────────┐
   │ <do this stuff> │
   └─────────────────┘   THEN
   <do more stuff>     ;

The latter works out really well if you have a lot of nested IF's, and no visual searching is necessary. (Color syntax highlighting is not only unnecessary when you do this, but totally undesirable, IMO.) Then you can put them one above the other instead of indenting and indenting and indenting way over to ridiculous extremes. You might end with a line of

Code: Select all

   THEN  THEN  THEN  THEN  THEN

Some may turn up their nose at this and say if you're having to do that, then you're taking the wrong approach; but then their "fix" usually ends up overfactoring or doing something else that's just as undesirable.

[GARTHWILSON]

I seem to remember the humorous book "Starting Forth" had the following logic example as part of a getting-dressed word, to show Forth's differing approach.

Are you lacking socks?
IF so, socks-install
THEN shoes-install

(The "shoes install" object-noun word order is natural for native Korean speakers.) The THEN is not part of the IF, but instead meas "After you've taken care of that, do this." It makes perfect sense this way, even though it's different from other programming languages which would take the approach,

process dress_feet:
IF your are lacking socks, THEN put on socks. ENDIF
Now put on shoes.

[JimBoyd]

GARTHWILSON wrote:

The first sample follows what so many Forthers are dogmatic about, that definitions should be limited to two lines. This kind of dogma hurts readability. It tends to result in over-factoring too, taking more memory for all the unnecessary headers for factors that are only used once, more time to run because of the extra nesting, and it can be hard sometimes to come up with a descriptive name for the factor that is any shorter than the code it replaces! There was a regular contributor to Forth Dimensions magazine who defended this strongly, and said screens should be viewed as 3x5 cards. He kept pushing this as a plus, yet I just saw it as inadequate room to make things clear and add adequate comments. Then in a private mail exchange (which today we would do by email, but back then it was on paper), he sent me his code for something we were discussing, and he had a definition that was over 100 lines long! I didn't call out his hypocrisy.

I tend to view screens as a consequence of the limitations of the technology of the day, although blocks on the C64 can also be used as a form of virtual memory. On my Linux box, I use plain text files for source.
If I have a definition on the C64 that will not fit on a single block, I just let it span however many I need. -NUMBER takes two blocks but I load something like that with THRU rather than LOAD , so it's not a problem.
I think some of the over zealous factoring came about because some Forth programmers tried to minimize what they perceived as wasted space in a source screen. I hope this example makes it evident that the "wasted space" in a source screen is not so valuable a resource as the understanding that comes from well formatted source.
I made a copy of the source for -NUMBER and reformatted it to pack it into as few lines as possible. The only rules where:
1) Three space indentation for every line in a definition after the name.
2) two spaces around each control flow word unless it is the first or last word on a line.
To say it is highly unreadable is an understatement. When I deleted the white space, I may have accidentally deleted a word or two. From the compacted form it is not easy to tell.

Code: Select all

: -NUMBER  ( ADR -- D FLAG )  RB DUP 1+ C@ ASCII # - DUP 3 U<
   IF  BASE.TABLE + C@ BASE ! 1+ DUP  THEN  DROP DPL ON  0 0 ROT
   DUP 1+ C@ ASCII - = DUP>R - DUP>R  BEGIN  CONVERT DUP C@
   VALID?  WHILE  DUP 1+ C@ VALID? 0=  WHILE  DPL OFF  REPEAT
   THEN  DUP C@ BL <> SWAP 2- DPL @ 0< - R> = OR R> 0EXIT >R
   DNEGATE R> ;

If this was somebody's ideal, I can see why they would want to aggressively factor it (over factor it). Personally, this form looks like software that went through a virtual trash compactor.
In this case, there is no need to refactor this word, just don't format the source like this.
Even if there are any useful factors in the definition of -NUMBER , it is not easy to find them in this mess.

[JimBoyd]

I was just reading "Real Time Forth" by Dr. Tim Hendtlass and becoming reacquainted with some of F-PC's words. I had forgotten that F-PC has a word called NUMBER? which is similar to Fleet Forth's -NUMBER . The only apparent difference is NUMBER? returns a TRUE flag if successful. I use the word 'apparent' because without a copy of F-PC (which I had at one time, but it's been a while) I do not know what F-PC's NUMBER? rejects as an invalid number. Fleet Forth's -NUMBER requires a numeric string to:
1) Have at least one valid digit in the current base (or the temporary base specified by a leading # , $ , or % )
2) Have no more than one occurrence of valid punctuation in a row.
3) Have a trailing blank. When interpreting, this is automatically supplied by WORD .
For example, the following are valid numbers:
1.2
1.
.1
.1.
.1.2.3.4.
-1.
$-FF
$-DEAD.BEEF
the following are not:
1..2
.
..
...
.1..2
..1
123...
-.
-
Since there is already a word that does what -NUMBER does, but with a different return flag and a slightly different name, I changed -NUMBER to NUMBER? and changed the return flag.
-NUMBER had the following test to determine if the result was valid:

Code: Select all

   DUP C@ BL <> SWAP
   2-  DPL @ 0< - R> = OR

FALSE = valid
Thanks to De Morgan’s laws, I know I can change this test to reverse the flag without just tacking a 0= on the end to flip the flag.

Code: Select all

   DUP C@ BL = SWAP
   2-  DPL @ 0< - R> <> AND

TRUE = valid
I also had to change a few (very few) things in the kernel and saved two bytes overall.

[JimBoyd]

GARTHWILSON wrote:

As long as things don't conflict, it's nice when you can accommodate multiple standards. The only drawback is that it takes more memory.

I wasn't trying to accommodate multiple standards. I thought it would be useful if I could specify a number as hexadecimal, decimal, or binary regardless of the current number base. The Ansi Forth Standard specified that behaviour so I appropriated that part of it.
It's still early days, but for 44 extra bytes in the kernel, I think it will be worth it.

[JimBoyd]

Fleet Forth has a word, ?MEM , to check if the amount of memory to ALLOT is available. At one point I defined ?MEM like this:

Code: Select all

: ?MEM  ( N -- N )
   MRU OVER PAD + U< 0EXIT
   ABORT" NO MEMORY" ;

0EXIT was used to exit the word immediately, if there was no error, to avoid the overhead of (ABORT") .
This was the source for (ABORT")

Code: Select all

: (ABORT")  ( F -- )
   IF
      WHERE CR R@ S?
      ABORT
   THEN
   R> COUNT + >R ;

Including docolon, that is seven passes through NEXT just to check for an error and keep going. Rather than using code like the above code for ?MEM to avoid that overhead in some places, I decided to make (ABORT") faster. Here is the source for the new (ABORT") .

Code: Select all

CODE (ABORT")  ( F -- )
   0 ,X LDA,  1 ,X ORA,
   0= IF,
      IP )Y LDA,  SEC,
      IP ADC,  IP STA,
      CS IF,  IP 1+ INC,  THEN,
      POP JMP,
   THEN,
   >FORTH
   WHERE CR R@ S?
   ABORT ;
   -2 ALLOT

The new version of (ABORT") is only nine bytes larger than the older version.

[GARTHWILSON]

UNUSED is pretty standard for your ?MEM, and is even in ANS Forth. It can be defined as:

Code: Select all

: UNUSED        ( -- #bytes )   \                                   ANS_CORE_EXT
   LIMIT  HERE  -       ;       \ Leaves room for a max-length comment line from
                                \ TIB , HLD , and a max-length string in PAD .

I did it as a primitive in my '816 Forth, this way:

Code: Select all

        HEADER "UNUSED", NOT_IMMEDIATE   ; ( -- bytes )
UNUSED: PRIMITIVE           ; Tells how much RAM is left to expand the dictionary
        LDA     #LIMITdata  ; I omitted CLC since 1 byte either way won't matter.
        SBC     DPdata
        JMP     PUSH

[JimBoyd]

?MEM is different. It does not return the amount of bytes free. Given a number of bytes, it performs the test to see if there is enough memory available. It takes the number of bytes and if that number is available, it returns that same number. This is why, in a previous post, I called it "transparent".
For example, here is the source for Fleet Forth's ALLOT .

Code: Select all

: ALLOT  ( N -- )
   ?MEM  DP +! ;

ALLOT was previously defined without memory checking:

Code: Select all

: ALLOT  ( N -- )
   DP +! ;

This seems more convenient to me than picking a "reasonable" amount of memory that needs to be available in CREATE or the need to check memory if I need to ALLOT some. If there is not enough memory, HERE does not change and the system aborts.
So far ?MEM is only used in two other places:
" places a string at PAD while interpreting or compiles (") and inlines the string while compiling.
FBUF in the editor.
The new and improved version of (ABORT") wasn't just to remove 0EXIT from ?MEM , but to make all uses of (ABORT") faster when there is no error to report.