Go to Triangle Digital Support Home Page TDS2020F TECHNICAL MANUAL
Introduction
Converting Fig-Forth to ANS Forth
Live website search
Enter key words
 

CONVERTING FIG-FORTH TO ANS FORTH

If your program is on TDS9092 or is for a TDS2020 Forth before version 3.00, you will need to convert from the Fig-Forth implementation to American National Standard Forth. Follow these steps:

SUMMARY PROCEDURE

 

q       Do the EASY SUBSTITUTIONS below using a word-processor's search-and-replace facility.

q       Work slowly down the list of POINTS TO WATCH below using a word-processor's find facility to locate all occurrences of each item. Understand the software's action before deciding if a replacement is needed.

q       Use only library programs starting with # . For example change $SHELTER.TDS to #SHELTER.TDS.

q       Change interrupt vectors defined with +ORIGIN . Add +62 to each number used for the earlier Fig-Forth version of TDS2020, except the internal watchdog ( 1 +ORIGIN ) which remains unchanged. For example the A to D interrupt changes from -65 +ORIGIN to -3 +ORIGIN

 

Add another word at the end of your program to take care of error conditions. If you omit it, the program will abort to interactive Forth if it fails due to electrical noise or other error. With the extra layer it will restart or do anything else you want on an error. The simplest recommended structure for the highest level of your program is as follows. It is further explained in ERROR HANDLING, page 144. (Note: If your program uses the serial port arrange some other escape to Forth, for instance when a key on a parallel input is pressed.)

 

Example of program top-level structure:

 

: INITIALISE ( - )     \ Set direction of I/O ports,

   \ zero all variables, including

   \ any multitasker locks.

      . initialisations . ;

: TRY ( - ) \ One pass through the main program loop

   KEY? IF START THEN . rest of program . ;

: MAIN ( - ) \ Indefinite application loop

   INITIALISE BEGIN TRY AGAIN ;

: WORK ( - ) \ Word executed at power-up

   BEGIN ['] MAIN CATCH ERROR AGAIN ;

 

If there is anything not clear about ANS Forth, or you want assistance with part of your program, remember that we can advise you.

EASY SUBSTITUTIONS

This is a table of principal exact equivalents. Here xxx represents any Forth word and '.' replaces a section of Forth code:

 

 

Fig-Forth

ANS Forth

 

TDS9092 Version 1.10A

TDS2020F Version 4

 

or TDS2020 Version 2.13

 

 

 

 

 

" This is a string"

S" This is a string"

 

(not Fig-Forth)

 

 

 

 

compiling:

' xxx

['] xxx >BODY

executing:

' xxx

' xxx >BODY

 

 

 

compiling:

' xxx CFA

['] xxx

executing:

' xxx CFA

' xxx

 

 

 

 

(KEY) (not Fig-Forth)

KEY

 

(NUMBER)

>NUMBER (not exactly the same)

 

XOR

INVERT

 

DUP

?DUP

 

 

 

compiling:

."

."

executing:

."

.(

 

 

 

 

0. 2VARIABLE xxx

2VARIABLE xxx

 

0 VARIABLE xxx

VARIABLE xxx

 

3 PICK

2 PICK

 

4 ROLL

3 ROLL

 

;S

EXIT

 

<BUILDS . DOES>

CREATE . DOES>

 

?1DATA (not Fig-Forth)

KEY?

 

?TERMINAL

KEY? (any key, not just ctrl+C)

 

ABORT

START (not ANS)

 

ALLOT

RAM ALLOT ROM

 

BELL

$07 EMIT

 

BETWEEN

1+ WITHIN

 

BLANKS

BLANK

 

CFA

BODY> (not ANS)

 

COMPILE

POSTPONE

 

CREATE xxx SMUDGE

CREATE xxx

 

D*/ (not Fig-Forth)

M*/

 

DLITERAL

2LITERAL

 

DMINUS

DNEGATE

 

DOWN

$0A EMIT

 

END

UNTIL

 

ENDIF

THEN

 

HERE

ROM HERE

 

HOME

$0B EMIT

 

ID.

.ID

 

IN

>IN

 

LEFT

$08 EMIT

 

LFA

BODY> >NAME N>LINK

 

MINUS

NEGATE

 

NFA

BODY> >NAME

 

NOT

0=

 

PFA

N>LINK LINK> >BODY

 

R

R@

 

RIGHT

$1C EMIT

 

RTE, SMUDGE

RTE,

 

RTS, SMUDGE

RTS,

 

S->D

S>D

 

U*

UM*

 

U/

UM/MOD

 

UP

$1E EMIT

 

VLIST

WORDS

 

WORD HERE ALIGNED

WORD

 

[COMPILE]

POSTPONE (usually, but see #ANS.TDS)

POINTS TO WATCH

Updating a program to ANS Forth is a process that can be partially automatic. Some words just have new names but identical functions. Such replacement can be done easily in a word-processor with the search-and-replace mechanism. On the other hand, some differences will require a close look at how the original program achieves its function.

Here we consider only essential changes. Although some words such as [COMPILE] and EXPECT still exist in ANS Forth, their use is discouraged in favour of newer words, in this case POSTPONE and ACCEPT . In updating a program you can choose to ignore such advice if you wish. In the case of DOES> the use and function is unchanged but under ANS Forth the word is immediate during compilation and the internal operation is completely different, resulting in much faster execution times for defining words.

 

q       J must only be used to access the index of an outer DO . LOOP structure from within a second DO . LOOP . It can not be used to get at an item left on the return stack before a DO . LOOP started:
correct use:
: TEST ( - ) \ Displays the row
   \ 0 1 2 3 4 5 6 7 8 9 ten times
   CR 10 0 DO 30 20 DO J . LOOP CR LOOP ;

incorrect use:
: TEST ( - ) \ Fig-Forth would display
   \ 12345 ten times
   12345 >R 10 0 DO J . LOOP R> DROP ;

q       R@ replaces R but is not the same as I . Use R@ to get a copy of the top of the return stack and I to get the index of the current innermost loop.

q       DO in Fig-Forth should normally be replaced by ?DO in the conversion to ANS Forth because, given two equal parameters, the ANS Forth version of DO will loop 65536 times, not 0 times as the Fig-Forth version.

q       The structure DO . -1 +LOOP will loop one more time in ANS Forth than in Fig-Forth. Search the Fig-Forth source code for all occurrences of +LOOP and make any adjustment necessary.

q       LEAVE is still used in a DO . LOOP to get out of the loop prematurely but under ANS Forth you jump directly from the LEAVE to after the following LOOP or +LOOP without executing the intervening code. For example:
: TEST 10 0 DO I 5 = IF LEAVE THEN I . LOOP ;
Under Fig-Forth this displays 0 1 2 3 4 5 but under ANS Forth it displays 0 1 2 3 4 .

q       The true Boolean flag returned by operations like = is -1 but in Fig-Forth it is +1. No change is necessary provided you have really used this as a flag, to be consumed by IF or WHILE for example. However if you have mixed types by using it as a numerical value, the program will need adjustment. ANS Forth, like Fig-Forth, will accept any value other than zero as a Boolean true flag. It is only the value provided from operations returning a flag that changes. New words TRUE and FALSE exist which are equivalent to -1 and 0 respectively.
TDS9092 or TDS2020 (ver 2.13 & earlier):
 : ?CARD ( - n ) Test for Card Memory
   $3F GET 4 AND 0= $3E GET 4 AND
   0= 2* + ;
ANS Forth (TDS2020 ver 3.00 and later):
: ?CARD ( - n ) Test for Card Memory
   $3F GET 4 AND 0= ABS $3E GET 4 AND
   0= ABS 2* + ;
In this example the -1 returned by 0= in ANS Forth is turned into +1 by the ABS ready for the arithmetic operation

q       The word ' returns a code field address in ANS Forth, now renamed an execution token, and not the parameter field address. In addition you need to use ['] instead of ' when compiling (see EASY SUBSTITUTIONS above). For example, in an assembler definition when you want the address of a subroutine xxx change ' xxx to  ' xxx >BODY .

q       CREATE and <BUILDS are two words with separate functions in Fig-Forth. The former is normally used to make look-up tables and the latter for defining words. In ANS Forth the two jobs are combined and given to CREATE . See 'Forth Programmer's Handbook' for examples.

q       Look-up tables change. In the table itself omit the SMUDGE which was used with Fig-Forth. In the place where the table is used omit the('tick') which found the address of the table. The SMUDGE is not needed because ANS Forth's CREATE does not make the table name unfindable, and the 'tick' is not used because ANS Forth's CREATE makes a name which automatically returns its own address when executed.
TDS9092 and TDS2020 (ver 2.13 & earlier):
CREATE CODES \ Look-up tables
   34 C, 65 C, 2C C, 78 C, BA C, 43 C, 4F C,
   7E C, 36 C, A2 C, 4D C, 69 C, SMUDGE
: TRANSLATE ( n1 - n2) \ n1 is 1 to 12
  
' CODES + 1- C@ ;
ANS Forth (TDS2020 ver 3.00 and later):
 CREATE CODES Look-up tables
   34 C, 65 C, 2C C, 78 C, BA C, 43 C, 4F C,
   7E C, 36 C, A2 C, 4D C, 69 C,
: TRANSLATE ( n1 - n2) \ n1 is 1 to 12
   CODES + 1- C@ ;

q       When using words , ALIGN ALIGNED ALLOT C, CREATE HERE UNUSED (see EASY SUBSTITUTIONS above) make sure the intended data-space is active. Note however that VARIABLE and 2VARIABLE always address the RAM. For example:
   DECIMAL
   VARIABLE READINGS
   RAM 98 ALLOT ROM
Now the word READINGS will return the address of the first byte of an area of 100 bytes in RAM, two bytes from the VARIABLE declaration, 98 from ALLOT .

q       PICK and ROLL take arguments one less than in Fig-Forth. For example, 1 PICK is the same as OVER in ANS Forth, but equal to DUP in Fig-Forth. Arguments to these words will need reducing
TDS9092 and TDS2020 (ver 2.13 & earlier):
   3 PICK 4 PICK   5 PICK etc.
ANS Forth (TDS2020 ver 3.00 and later):
   2 PICK 3 PICK   4 PICK etc.

q       Millisecond delays using MS in ANS Forth can be longer but not shorter than nominal. In TDS2020F ANS Forth MS is accurate to within -0/+5% when running from the H8/532 microprocessor (unless using the multitasker or interrupts). It is about twice as slow when running from the TDS2020DV development piggyback. Add file #TIMING.TDS to get accurate MS in all circumstances.

q       CASE is not Fig-Forth but earlier TDS2020s and TDS9092 have it. Unlike these, ANS Forth does not keep the value being tested on the return stack during the various OF . ENDOF clauses. Because it remains on the parameter stack you have to be careful to keep it in the right place. Note the difference between these two examples:

TDS9092 and TDS2020 (ver 2.13 & earlier)
: TEST ( n1 n2 - ) \ If n has only one bit set
   \ return the bit number,
   \ otherwise return 0
   CASE 1 OF 1 ENDOF
        2 OF 2 ENDOF
        4 OF 3 ENDOF
        8 OF 4 ENDOF
       16 OF 5 ENDOF
       32 OF 6 ENDOF
       64 OF 7 ENDOF
      128 OF 8 ENDOF
             0 \ default if input not power of 2
   ENDCASE ;

ANS Forth (TDS2020 ver 3.00 and later):
: TEST ( n1 n2 - ) \ If n has only one bit set
   \ return the bit number,
   \ otherwise return 0
   CASE 1 OF 1 ENDOF
        2 OF 2 ENDOF
        4 OF 3 ENDOF
        8 OF 4 ENDOF
       16 OF 5 ENDOF
       32 OF 6 ENDOF
       64 OF 7 ENDOF
      128 OF 8 ENDOF
             0 \ default if input not power of 2
      SWAP     \ bring selector back to top
   ENDCASE ;

Go to Triangle Digital Support Home Page Go to top   Next page