CHAPTER 12. STANDARD LIBRARIES 166
Finally, you sometimes find yourself in a situation where you’re faced with the choice to either make two library files with slightly different code or resort to conditonal compilation. If you choose the latter the question remains how the user of your library can switch between both versions. For those situations 4tH offers ’[PRAGMA]’. ’[PRAGMA]’ simply compiles a constant with a TRUE value. E.g. compare.4th can be compiled in a case sensitive mode by issuing the casesensitive pragma:
[pragma] casesensitive
[needs lib/compare.4th]
In the library file itself you can treat the pragma just like any other constant:
[UNDEFINED] casesensitive [IF] dup [char] A - max-n and 26 < if bl or then
[THEN]
Where you place your library files is up to you. You can add them to the library files that come with 4tH, you can put them in another directory, whatever pleases you.
12.2
Adding templates
When you include a library file you add some words to your program. When you include a template you add some words to an existing program. That is the major difference between a library file and a template file. We’ve included a template with 4tH which allows you to create conversion program pretty quickly. The template is called "convert.4th” and it allows you to create a conversion program by defining just three words.
A standard conversion program takes an input file and creates an output file in a different format. When it can’t open a file it will issue an error message, e.g.
Cant open input.txt
When you don’t supply an input file and an output file, it will issue an error message e.g.:
Usage: myconversion input output
And of course, it will read and process the input file. And that’s all you have to tell 4tH:
• The usage message
• How to read the file
• How to process the file
So, let’s create a program that will convert a block file to a regular text file. How do we do that? First of all we’ve got to issue a usage message, like:
Usage: blk2txt blockfile textfile
Well, that is easy. If it comes to that we’ve got to abort the program, so this will do:
: Usage abort" Usage: blk2txt blockfile textfile" ;
CHAPTER 12. STANDARD LIBRARIES 167
Then we’ve got to read the file. A block file contains lines of 64 characters, always. So, we’ve got to create a buffer and read 64 characters. This will do:
64 string buffer
: Read-file buffer 64 accept ;
Finally, we’ve got to write the output file. Adding a ’CR’ after typing the line will do, but we don’t want any trailing spaces, so we need to strip those trailing spaces:
: Process buffer 64 -trailing type cr ;
Now we need to include the template and we’re done:
[needs lib/convert.4th]
Wow! Do you know how much coding we need to do when we try to do this in C? This source code takes less than 256 bytes! Compile it and we’re done! So how does it work?
Well, the template expects us to define ”Usage” and ”Process”. If you don’t it will abort compilation:
\ Has Usage been defined? If not, abort!
[UNDEFINED] Usage [IF]
[ABORT] [THEN]
\ Has Process been defined?
[UNDEFINED] Process [IF]
[ABORT] [THEN]
If you don’t define ”Read-file” the template assumes that ”Process” is completely selfcontained, which means it will only open the files. Finally, you can optionally define
”PreProcess” and ”PostProcess” if you need any special actions at the beginning or the end:
: ProcessFile
[DEFINED] PreProcess [IF]
PreProcess
[THEN]
\ process the input file line by line
\ do any preprocessing
[DEFINED] Read-file [IF] begin Read-file while Process repeat \ read file and process line or buffer
[ELSE]
Process
[THEN]
\ self contained processing
[DEFINED] PostProcess [IF]
PostProcess
[THEN]
;
\ do any postprocessing
If you don’t define it, it won’t include it. You can use such templates for many different programs, e.g. this will convert a Unix text file to an MS-DOS text file:
: Usage abort" Usage: udc infile outfile " ;
: Read-file refill ;
: Process 0 parse-word type 13 emit 10 emit ;
You can make them as sophisticated or as simple as you like. You can create other words as well, as long as those three words have been defined. Templates can be handled like any other library file. You can place them where you want, they can hold anything you want.
Amaze your collegues by writing programs in a fraction of the time they should need!
