CHAPTER 21. PORTING GUIDE 391 max-line 2 [+] string line-buffer \ extend by two bytes:
\ ANS Forth requirement!
: scan-file ( addr u -- ) begin \ read a line line-buffer max-line fd-in read-line throw while \ is it identical?
>r 2dup line-buffer r> show compare dup while \ if so, exit loop drop repeat
[undefined] 4th# [if] then [then]
\ clean up
\ ANS requires an extra
\ then after each WHILE drop 2drop
; s" The text I search is here" scan-file
\ now scan the file fd-in close-file throw fd-out close-file throw
\ close input file
\ close output file
Since section 11.3.12 of the ANS-Forth standard clearly states that an I/O exception shall not cause a ’THROW’, we have to mention that ’FILE-SIZE’, ’FILE-STATUS’ and ’REPOSITION-
FILE’ are not entirely ANS-Forth compliant.
21.4
Easy 4tH
4tH programs won’t run on ANS-Forth all by itself. You’ll usually need several definitions to make them work. In collaboration with Wil Baden we have developed an interface between ANS-Forth and 4tH. It consists of two files, easy.4th and ezneeds.4th.
These library files enable you to run most 4tH programs under ANS-Forth. In order to succesfully compile and run a 4tH program under ANS-Forth it must have been written with ANS-Forth in mind. The rest is simple: just add a couple of lines at the beginning of your 4tH program:
[UNDEFINED] 4TH# [IF] s" easy4th.4th" included
[THEN]
That’s all! Most of the 4tH words are now known to your very own ANS-Forth compiler.
If your compiler already supports ’INCLUDE’, you might be tempted to use:
[UNDEFINED] 4TH# [IF] include easy4th.4th
[THEN]
This will actually work but since 4tH recognizes and acts on the ’INCLUDE’ directive, it will load the interface. A slight memory and CPU penalty is the result.
21.4.1
Enabling the String Space
Optionally, you can define a ’CONSTANT’ before including Easy 4tH, which enables support for arrays of string constants:
<size> constant /STRING-SPACE
CHAPTER 21. PORTING GUIDE 392
The parameter "SIZE" represents the size of the String Segment. When you decompile a
4tH program, it will show you exactly how much space is allocated to the String Segment.
In order to port a single 4tH program, this is all the information you need!
4tH message : No errors at word 1105
Object size : 1106 words
String size : 2539 chars
Variables
Strings
Reliable
: 19 cells
: 262 chars
: Yes
In this case the "/STRING-SPACE" must be at least 2539 bytes. So, give or take a few changes, let’s say 3072 bytes. We advise you to allocate a little more memory than is strictly necessary. You can also use Easy 4tH to make ANS-Forth understand 4tH. Just type:
16384 constant /STRING-SPACE s" easy4th.4th" included
Now you can play around with ANS-Forth using the 4tH language. If you use a lot of string constants you might run out of space, but your ANS-Forth compiler will give you a message when that happens.
Note that - depending on the ANS-Forth compiler you’re using - Easy 4tH may redefine some words, although it will try to minimize these redefinitions as much as possible.
21.4.2
The structure of Easy 4tH
Easy 4tH may look like a large program, but it isn’t. It basically tries to figure out what your compiler supports and what is still left to define. It always prefers the native definition to its own. E.g. if your compiler already supports ’PLACE’, Easy 4tH will leave that definition intact and assume it has been defined correctly.
• Easy 4tH will start by defining several defining words like ’STRING’, ’STRUCT’ and ’ARRAY’. Since there is no standard definition for these words, it will overwrite any existing definition.
• After that, Easy 4tH will query the environment and define a ’CONSTANT’ when successful. When not, a warning is issued.
• Several 4tH specific compiling words are defined.
• Easy 4tH checks for the presence of several ANS-Forth and COMUS words. If they are not there, they are defined. Warnings are issued where applicable.
• In the next stage the
PARSING
,
CONVERSION and
TIME subsystems of 4tH are defined. Warnings are issued where applicable.
• All 4tH words that cannot be defined in ANS-Forth are marked as unsupported.
When used, an error message is issued and compilation aborted.
• ezneeds.4th is loaded and ’[NEEDS’ and ’INCLUDE’ are defined if needed.
Note that your own compiler may issue error messages or warnings too, e.g. about redefinitions.
