Chapter 26
Using the 4tH API
26.1
Introduction
One of the design requirements of the 4tH library was that it had to be very easy to use.
We’ve seen many APIs that were impossible to use and put most of the burden on the developer.
4tH takes a different direction. We’ve designed an API that almost exactly matches the tasks you want to perform. Want to compile? Compile. Want to decompile? Decompile.
Want to save? Save. Just like that. No difficult to understand datatypes, no initialization, no garbage collection, no checks.
The only error, you, the developer can make is fill up memory. Virtually all other errors are caught by the API. E.g. 4tH will refuse to save or execute a 4tH-program when compilation failed. Of course, if you manipulate 4tHs datastructures directly you can still bring it to its knees, but I assume that is not what you want.
What most people tend to forget is that 4tH is foremost a library. The executables that come with it are just examples: pp4th
4th
4tsh
A development system much like ordinary command line based compilers like gcc .
A development system modeled after early versions of Turbo Pascal.
A multitasking shell that turns 4tH into a kind of operating system.
But a 4tH based C program can be much less elaborate as we will show you in the next chapter.
26.2
A sample program
There are ten API-functions.
That’s really all! So if you want to compile a 4tH source, save it to disk, execute it and finally discard it, you’ve virtually written the program.
H-code is nothing but a pointer to a structure. Even if you thought you never worked with structures before, it’s as easy as working with files. We’ll show you.
When you want to use files you first have to include stdio.h, like:
485
CHAPTER 26. USING THE 4TH API
API F
UNCTION comp_4th() Loads and compiles a 4tH source to an H-code object exec_4th() Executes an H-code object dump_4th() Decompiles an H-code object free_4th() Frees an H-code object from memory save_4th() Saves an H-code object to an HX-file on disk store_4th() Saves an H-code object to an HX-file in memory load_4th() Loads an HX-file from disk and installs H-code fetch_4th() Loads an HX-file from memory and installs H-code open_4th() Creates a small 4tH program that loads a 4tH source cgen_4th() Generates a standalone C source with embedded H-code
Table 26.1: API functions
486
#include <stdio.h>
If you want to use a single file for output, you’ve got to declare a file-pointer like:
FILE* Outfile;
Before you can use a file, you have to open it:
Outfile = fopen ("filename.ext", "w");
If the file cannot be opened, fopen() returns a NULL-pointer. You have to check that before you can safely use the file: if (Outfile == NULL) printf ("Unable to open file"); else fprintf (Outfile, "This is written to disk");
Finally, when you’re done, you have to close the file: fclose (Outfile);
Working with the 4tH library is very similar. When you want to use the 4tH library you write:
#include "4th.h"
When you use an H-code object (which is a compiled 4tH program), you declare a H-code pointer:
Hcode* Program;
Before you can use the H-code pointer, we first got to compile a 4tH source. 4tH source is simply a malloc()ed ASCIIZ string. That means that anything you can convert to a string stored in dynamic memory can be used as 4tH source. That includes constant strings, environment variables, lines read from a file, etc.
In this example we use the strdup() function to convert a constant string. We know that not all runtime-libraries contain such a function, so if you want give it a try, here is the source:
