Projects

JSyn - modular synthesis API for Java.
JMSL - Java Music Specification Language
PortAudio - cross platform audio I/O API for 'C'

pForth  : GitHub  | Tutorial  | Reference  | Links

pForth Reference Manual

pForth - a Portable ANSI style Forth written in ANSI 'C'.

Last updated: July 21, 2016 V23

by Phil Burk with Larry Polansky, David Rosenboom. Special thanks to contributors Darren Gibbs, Herb Maeder, Gary Arakaki, Mike Haas.

Back to pForth Home Page

LEGAL NOTICE

The pForth software code is dedicated to the public domain, and any third party may reproduce, distribute and modify the pForth software code or any derivative works thereof without any compensation or license. The pForth software code is provided on an "as is" basis without any warranty of any kind, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose and their equivalents under the laws of any jurisdiction.

Table of Contents

What is pForth?

PForth is an ANSI style Forth designed to be portable across many platforms. The 'P' in pForth stands for "Portable". PForth is based on a Forth kernel written in ANSI standard 'C'.

What is Forth?

Forth is a stack based language invented by astronomer Charles Moore for controlling telescopes. Forth is an interactive language. You can enter commands at the keyboard and have them be immediately executed, similar to BASIC or LISP. Forth has a dictionary of words that can be executed or used to construct new words that are then added to the dictionary. Forth words operate on a data stack that contains numbers and addresses.

To learn more about Forth, see the Forth Tutorial.

The Origins of pForth

PForth began as a JSR threaded 68000 Forth called HForth that was used to support HMSL, the Hierarchical Music Specification Language. HMSL was a music experimentation language developed by Phil Burk, Larry Polansky and David Rosenboom while working at the Mills College Center for Contemporary Music. Phil moved from Mills to the 3DO Company where he ported the Forth kernel to 'C'. It was used extensively at 3DO as a tool for verifying ASIC design and for bringing up new hardware platforms. At 3DO, the Forth had to run on many systems including SUN, SGI, Macintosh, PC, Amiga, the 3DO ARM based Opera system, and the 3DO PowerPC based M2 system.

pForth Design Goals

PForth has been designed with portability as the primary design goal. As a result, pForth avoids any fancy UNIX calls. pForth also avoids using any clever and original ways of constructing the Forth dictionary. It just compiles its kernel from ANSI compatible 'C' code then loads ANS compatible Forth code to build the dictionary. Very boring but very likely to work on almost any platform.

The dictionary files that can be saved from pForth are almost host independent. They can be compiled on one processor, and then run on another processor. as long as the endian-ness is the same. In other words, dictionaries built on a PC will only work on a PC. Dictionaries built on almost any other computer will work on almost any other computer.

PForth can be used to bring up minimal hardware systems that have very few system services implemented. It is possible to compile pForth for systems that only support routines to send and receive a single character. If malloc() and free() are not available, equivalent functions are available in standard 'C' code. If file I/O is not available, the dictionary can be saved as a static data array in 'C' source format on a host system. The dictionary in 'C' source form is then compiled with a custom pForth kernel to avoid having to read the dictionary from disk.

Compiling pForth for your System

Up-to-date instructions on compiling, possibly with comments from the community, may be found at:

https://github.com/philburk/pforth/wiki/Compiling-on-Unix

The process of building pForth involves several steps. This process is typically handled automatically by the Makefile or IDE Project.

  1. Compile the 'C' based pForth kernel called "pforth" or "pforth.exe".
  2. Execute "pforth" with the -i option to build the dictionary from scratch. Compile the "system.fth" file which will add all the top level Forth words. This can be done in one command by entering "pforth -i system.fth".
  3. Save the compiled dictionary as "pforth.dic".
  4. The next time you run pforth, the precompiled pforth.dic file will be loaded automatically.

Unix and Max OS X

A Makefile has been provided that should work on most Unix based platforms.

  1. cd to "platforms/unix" folder.
  2. Enter: make all
  3. Enter: ./pforth

Note that the platforms folder used to be called build.

Description of Source Files

Forth Source in /fth/

ansilocs.fth    = support for ANSI (LOCAL) word
c_struct.fth    = 'C' like data structures
case.fth        = CASE OF ENDOF ENDCASE
catch.fth       = CATCH and THROW
condcomp.fth    = [IF] [ELSE] [THEN] conditional compiler
filefind.fth    = FILE?
floats.fth      = floating point support
forget.fth      = FORGET [FORGET] IF.FORGOTTEN
loadp4th.fth    = loads basic dictionary
locals.fth      = { } style locals using (LOCAL)
math.fth        = misc math words
member.fth      = additional 'C' like data structure support
misc1.fth       = miscellaneous words
misc2.fth       = miscellaneous words
numberio.fth    = formatted numeric input/output
private.fth     = hide low level words
quit.fth        = QUIT EVALUATE INTERPRET in high level
smart_if.fth    = allows conditionals outside colon definition
see.fth         = Forth "disassembler".  Eg.  SEE SPACES
strings.fth     = string support
system.fth      = bootstraps pForth dictionary
trace.fth       = single step trace for debugging

'C' Source in /csrc/

pfcompil.c  = pForth compiler support
pfcustom.c  = example of 'C' functions callable from pForth
pfinnrfp.h  = float extensions to interpreter
pforth.h    = include this in app that embeds pForth
pf_cglue.c  = glue for pForth calling 'C'
pf_clib.c   = replacement routines for 'C' stdlib
pf_core.c   = primary words called from 'C' app that embeds pForth
pf_float.h  = defines PF_FLOAT, and the floating point math functions such as fp_sin
pf_inner.c  = inner interpreter
pf_guts.h   = primary include file, define structures
pf_io.c     = input/output
pf_main.c   = basic application for standalone pForth
pf_mem.c    = optional malloc() implementation
pf_save.c   = save and load dictionaries
pf_text.c   = string tools, error message text
pf_words.c  = miscellaneous pForth words implemented

Running pForth

PForth can be run from a shell or by double clicking on its icon, depending on the system you are using. The execution options for pForth are described assuming that you are running it from a shell.

Usage:

-i
Initialize pForth by building dictionary from scratch. Used when building pForth or when debugging pForth on new systems.
 
-dDictionaryFilename
Specify a custom dictionary to be loaded in place of the default "pforth.dic". For example:
SourceFilename
A Forth source file can be automatically compiled by passing its name to pForth. This is useful when using Forth as an assembler or for automated hardware testing. Remember that the source file can compile code and execute it all in the same file.

Quick Verification of pForth

To verify that PForth is working, enter:

It should print "7 ok". Now enter:

You should see a long list of all the words in the pForth dictionary. Don't worry. You won't need to learn all of these.  More tests are described in the README.txt file.

If you want to learn how to program in Forth, try our tutorial.

ANSI Compliance

This Forth is intended to be ANS compatible. I will not claim that it is compatible until more people bang on it. If you find areas where it deviates from the standard, please let me know.

Word sets supported include:

Here are the areas that I know are not compatible:

The ENVIRONMENT queries are not implemented.

Word sets NOT supported include:

pForth Special Features

These features are not part of the ANS standard for Forth.  They have been added to assist developers.

Compiling from a File

Use INCLUDE to compile source code from a file:

You can nest calls to INCLUDE. INCLUDE simply redirects Forth to takes its input from the file instead of the keyboard so you can place any legal Forth code in the source code file.

Saving Precompiled Dictionaries

Use SAVE-FORTH save your precompiled code to a file. To save the current dictionary to a file called "custom.dic", enter:

You can then leave pForth and use your custom dictionary by entering:

On icon based systems, you may wish to name your custom dictionary "pforth.dic" so that it will be loaded automatically.

Be careful that you do not leave absolute addresses stored in the dictionary because they will not work when you reload pForth at a different address. Use A! to store an address in a variable in a relocatable form and A@ to get it back if you need to.

Creating Turnkey Applications

Use TURNKEY to save a dictionary with a word that will run automatically. The headers (names) will be discarded to save space in the dictionary. Suppose you have defined a word called MYAPP to prints the ASCII code when you press a key on the keyboard.

Save a dictionary named "turnkey.dic" that will run MYAPP. Other names are OK.

Run the app. Press some letters to see the code. Then press 'q' to exit.

Recompiling Code - ANEW INCLUDE?

When you are testing a file full of code, you will probably recompile many times. You will probably want to FORGET the old code before loading the new code. You could put a line at the beginning of your file like this:

This would automatically FORGET for you every time you load. Unfortunately, you must define XXXX-MINE before you can ever load this file. We have a word that will automatically define a word for you the first time, then FORGET and redefine it each time after that. It is called ANEW and can be found at the beginning of most Forth source files. We use a prefix of TASK- followed by the filename just to be consistent. This TASK-name word is handy when working with INCLUDE? as well. Here is an example:

Notice that the INCLUDE? comes before the call to ANEW so that we don't FORGET MYTHING.FTH every time we recompile.

FORGET allows you to get rid of code that you have already compiled. This is an unusual feature in a programming language. It is very convenient in Forth but can cause problems. Most problems with FORGET involve leaving addresses that point to the forgotten code that are not themselves forgotten. This can occur if you set a deferred system word to your word then FORGET your word. The system word which is below your word in the dictionary is pointing up to code that no longer exists. It will probably crash if called. (See discussion of DEFER below.) Another problem is if your code allocates memory, opens files, or opens windows. If your code is forgotten you may have no way to free or close these thing. You could also have a problems if you add addresses from your code to a table that is below your code. This might be a jump table or data table.

Since this is a common problem we have provided a tool for handling it. If you have some code that you know could potentially cause a problem if forgotten, then write a cleanup word that will eliminate the problem. This word could UNdefer words, free memory, etc. Then tell the system to call this word if the code is forgotten. Here is how:

IF.FORGOTTEN creates a linked list node containing your CFA that is checked by FORGET. Any nodes that end up above HERE (the Forth pointer to the top of the dictionary) after FORGET is done are executed.

Customising FORGET with [FORGET]

Sometimes, you may need to extend the way that FORGET works. FORGET is not deferred, however, because that could cause some real problems. Instead, you can define a new version of [FORGET] which is searched for and executed by FORGET. You MUST call [FORGET] from your program or FORGET will not actually FORGET. Here is an example.

This is recommended over redefining FORGET because words like ANEW that call FORGET will now pick up your changes.

Smart Conditionals

In pForth, you can use IF THEN DO LOOP and other conditionals outside of colon definitions. PForth will switch temporarily into the compile state, then automatically execute the conditional code. (Thank you Mitch Bradley) For example, just enter this at the keyboard.

Development Tools

WORDS.LIKE

If you cannot remember the exact name of a word, you can use WORDS.LIKE to search the dictionary for all words that contain a substring. For an example, enter:

FILE?

You can use FILE? to find out what file a word was compiled from. If a word was defined in multiple files then it will list each file. The execution token of each definition of the word is listed on the same line.

SEE

You can use SEE to "disassemble" a word in the pForth dictionary. SEE will attempt to print out Forth source in a form that is similar to the source code. SEE will give you some idea of how the word was defined but is not perfect. Certain compiler words, like BEGIN and LITERAL, are difficult to disassemble and may not print properly. For an example, enter:

Single Step Trace and Debug

It is often useful to proceed step by step through your code when debugging.  PForth provides a simple single step trace facility for this purpose.  Here is an example of using TRACE to debug a simple program.  Enter the following program:
 

Even though this program should work, let's pretend it doesn't and try to debug it.  Enter:

You should see:

The "TSQ +0" means that you are about to execute code at an offset of "+0" from the beginning of TSQ.  The <10:1> means that we are in base 10, and that there is 1 item on the stack, which is shown to be "7". The (.") is the word that is about to be executed.  (.") is the word that is compiled when use use .".  Now to single step, enter:

You should see:

The "Square os" was printed by (."). We can step multiple times using the "sm" command. Enter:

You should see:

The "7" after the ">>" was printed by the . word. If we entered "s", we would step over the SQUARE word. If we want to dive down into SQUARE, we can enter:

You should see:

To step once in SQUARE, enter:

You should see:

To go to the end of the current word, enter:

You should see:

EXIT is compiled at the end of every Forth word. For more information on TRACE, enter TRACE.HELP:

Conditional Compilation [IF] [ELSE] [THEN]

PForth supports conditional compilation words similar to 'C''s #if, #else, and #endif.

[IF] ( flag -- , if true, skip to [ELSE] or [THEN] )
[ELSE] ( -- , skip to [THEN] )
[THEN] ( -- , noop, used to terminate [IF] and [ELSE] section )

For example:

Here is how to conditionally compile within a colon definition by using [ and ].

Miscellaneous Handy Words

.HEX ( n -- , print N as hex number )
CHOOSE ( n -- rand , select random number between 0 and N-1 )
MAP ( -- , print dictionary information )

Local Variables { foo --}

In a complicated Forth word it is sometimes hard to keep track of where things are on the stack. If you find you are doing a lot of stack operations like DUP SWAP ROT PICK etc. then you may want to use local variables. They can greatly simplify your code. You can declare local variables for a word using a syntax similar to the stack diagram. These variables will only be accessible within that word. Thus they are "local" as opposed to "global" like regular variables. Local variables are self-fetching. They automatically put their values on the stack when you give their name. You don't need to @ the contents. Local variables do not take up space in the dictionary. They reside on the return stack where space is made for them as needed. Words written with them can be reentrant and recursive.

Consider a word that calculates the difference of two squares, Here are two ways of writing the same word.

In the second definition of DIFF.SQUARES the curly bracket '{' told the compiler to start declaring local variables. Two locals were defined, A and B. The names could be as long as regular Forth words if desired. The "--" marked the end of the local variable list. When the word is executed, the values will automatically be pulled from the stack and placed in the local variables. When a local variable is executed it places its value on the stack instead of its address. This is called self-fetching. Since there is no address, you may wonder how you can store into a local variable. There is a special operator for local variables that does a store. It looks like -> and is pronounced "to".

Local variables need not be passed on the stack. You can declare a local variable by placing it after a "vertical bar" ( | )character. These are automatically set to zero when created. Here is a simple example that uses -> and | in a word:

Since local variable often used as counters or accumulators, we have a special operator for adding to a local variable It is +-> which is pronounced "plus to". These next two lines are functionally equivalent but the second line is faster and smaller:

If you name a local variable the same as a Forth word in the dictionary, eg. INDEX or COUNT, you will be given a warning message. The local variable will still work but one could easily get confused so we warn you about this. Other errors that can occur include, missing a closing '}', missing '--', or having too many local variables.

'C' like Structures. :STRUCT

You can define 'C' like data structures in pForth using :STRUCT. For example:

See the file "c_struct.fth" for more information.

Vectorred Execution - DEFER

Using DEFER for vectored words. In Forth and other languages you can save the address of a function in a variable. You can later fetch from that variable and execute the function it points to.This is called vectored execution. PForth provides a tool that simplifies this process. You can define a word using DEFER. This word will contain the execution token of another Forth function. When you execute the deferred word, it will execute the function it points to. By changing the contents of this deferred word, you can change what it will do. There are several words that support this process.

DEFER ( <name> -- , define a deferred word )
IS ( CFA <name> -- , set the function for a deferred word )
WHAT'S ( <name> -- CFA , return the CFA set by IS )

Simple way to see the name of what's in a deferred word:

should print name of current word that's in EMIT.

Here is an example that uses a deferred word.

Many words in the system have been defined using DEFER which means that we can change how they work without recompiling the entire system. Here is a partial list of those words

Potential Problems with Defer

Deferred words are very handy to use, however, you must be careful with them. One problem that can occur is if you initialize a deferred system more than once. In the below example, suppose we called STUTTER twice. The first time we would save the original EMIT vector in OLD-EMIT and put in a new one. The second time we called it we would take our new function from EMIT and save it in OLD-EMIT overwriting what we had saved previously. Thus we would lose the original vector for EMIT . You can avoid this if you check to see whether you have already done the defer. Here's an example of this technique.

In the above example, we could call STUTTER or STOP-IT! as many times as we want and still be safe.

Suppose you forget your word that EMIT now calls. As you compile new code you will overwrite the code that EMIT calls and it will crash miserably. You must reset any deferred words that call your code before you FORGET your code. The easiest way to do this is to use the word IF.FORGOTTEN to specify a cleanup word to be called if you ever FORGET the code in question. In the above example using EMIT , we could have said:

Floating Point

PForth supports the FLOAT word set and much of the FLOATEXT word set as a compile time option.  You can select single or double precision as the default by changing the typedef of PF_FLOAT.

PForth has several options for floating point output.

FS. ( r -f- , prints in scientific/exponential format )
FE. ( r -f- , prints in engineering format, exponent if multiple of 3  )
FG. ( r -f- , prints in normal or exponential format depending on size )
F. ( r -f- , as defined by the standard )
 
Here is an example of output from each word for a number ranging from large to very small.
     FS.             FE.            FG.           F.
1.234000e+12     1.234000e+12     1.234e+12     1234000000000. 
1.234000e+11     123.4000e+09     1.234e+11     123400000000. 
1.234000e+10     12.34000e+09     1.234e+10     12340000000. 
1.234000e+09     1.234000e+09     1.234e+09     1234000000. 
1.234000e+08     123.4000e+06     1.234e+08     123400000. 
1.234000e+07     12.34000e+06     1.234e+07     12340000. 
1.234000e+06     1.234000e+06     1234000.     1234000. 
1.234000e+05     123.4000e+03     123400.     123400.0 
1.234000e+04     12.34000e+03     12340.     12340.00 
1.234000e+03     1.234000e+03     1234.     1234.000 
1.234000e+02     123.4000e+00     123.4     123.4000 
1.234000e+01     12.34000e+00     12.34     12.34000 
1.234000e+00     1.234000e+00     1.234     1.234000 
1.234000e-01     123.4000e-03     0.1234     0.1234000 
1.234000e-02     12.34000e-03     0.01234     0.0123400 
1.234000e-03     1.234000e-03     0.001234     0.0012340 
1.234000e-04     123.4000e-06     0.0001234     0.0001234 
1.234000e-05     12.34000e-06     1.234e-05     0.0000123 
1.234000e-06     1.234000e-06     1.234e-06     0.0000012 
1.234000e-07     123.4000e-09     1.234e-07     0.0000001 
1.234000e-08     12.34000e-09     1.234e-08     0.0000000 
1.234000e-09     1.234000e-09     1.234e-09     0.0000000 
1.234000e-10     123.4000e-12     1.234e-10     0.0000000 
1.234000e-11     12.34000e-12     1.234e-11     0.0000000

1.234568e+12     1.234568e+12     1.234568e+12     1234567890000. 
1.234568e+11     123.4568e+09     1.234568e+11     123456789000. 
1.234568e+10     12.34568e+09     1.234568e+10     12345678900. 
1.234568e+09     1.234568e+09     1.234568e+09     1234567890. 
1.234568e+08     123.4568e+06     1.234568e+08     123456789. 
1.234568e+07     12.34568e+06     1.234568e+07     12345679. 
1.234568e+06     1.234568e+06     1234568.     1234568. 
1.234568e+05     123.4568e+03     123456.8     123456.8 
1.234568e+04     12.34568e+03     12345.68     12345.68 
1.234568e+03     1.234568e+03     1234.568     1234.568 
1.234568e+02     123.4568e+00     123.4568     123.4568 
1.234568e+01     12.34568e+00     12.34568     12.34568 
1.234568e+00     1.234568e+00     1.234568     1.234568 
1.234568e-01     123.4568e-03     0.1234568     0.1234568 
1.234568e-02     12.34568e-03     0.01234568     0.0123456 
1.234568e-03     1.234568e-03     0.001234568     0.0012345 
1.234568e-04     123.4568e-06     0.0001234568     0.0001234 
1.234568e-05     12.34568e-06     1.234568e-05     0.0000123 
1.234568e-06     1.234568e-06     1.234568e-06     0.0000012 
1.234568e-07     123.4568e-09     1.234568e-07     0.0000001 
1.234568e-08     12.34568e-09     1.234568e-08     0.0000000 
1.234568e-09     1.234568e-09     1.234568e-09     0.0000000 
1.234568e-10     123.4568e-12     1.234568e-10     0.0000000 
1.234568e-11     12.34568e-12     1.234568e-11     0.0000000

pForth Design

'C' kernel

The pForth kernel is written in 'C' for portability. The inner interpreter is implemented in the function ExecuteToken() which is in pf_inner.c.

It is passed an execution token the same as EXECUTE would accept. It handles threading of secondaries and also has a large switch() case statement to interpret primitives. It is in one huge routine to take advantage of register variables, and to reduce calling overhead. Hopefully, your compiler will optimise the switch() statement into a jump table so it will run fast.

Dictionary Structures

This Forth supports multiple dictionaries. Each dictionary consists of a header segment and a seperate code segment. The header segment contains link fields and names. The code segment contains tokens and data. The headers, as well as some entire dictionaries such as the compiler support words, can be discarded when creating a stand-alone app.

[NOT IMPLEMENTED] Dictionaries can be split so that the compile time words can be placed above the main dictionary. Thus they can use the same relative addressing but be discarded when turnkeying.

Execution tokens are either an index of a primitive ( n < NUM_PRIMITIVES), or the offset of a secondary in the code segment. ( n >= NUM_PRIMITIVES )

The NAME HEADER portion of the dictionary contains a structure for each named word in the dictionary. It contains the following fields:

The CODE portion of the dictionary consists of the following structures:

Primitive

No Forth code. 'C' code in "pf_inner.c".

Secondary

CREATE DOES>

Deferred Word

Call to custom 'C' function.

Compiling pForth

A makefile is supplied that will help you compile pForth for your environment. You can customize the build by setting various compiler options.

Compiler Options

There are several versions of PForth that can be built. By default, the full kernel will be built. For custom builds, define the following options in the Makefile before compiling the 'C' code:

PF_DEFAULT_DICTIONARY="filename"

Specify a dictionary to use in place of the default "pforth.dic", for example "/usr/lib/pforth/pforth.dic".
PF_NO_INIT PF_NO_SHELL PF_NO_MALLOC PF_USER_MALLOC='"filename.h"' PF_MEM_POOL_SIZE=numbytes PF_NO_GLOBAL_INIT PF_USER_INC1='"filename.h"' PF_USER_INC2='"filename.h"' PF_NO_CLIB PF_USER_CLIB='"filename.h"' PF_NO_FILEIO PF_USER_CHARIO='"filename.h"' PF_USER_FILEIO='"filename.h"' PF_USER_FLOAT='"filename.h"' PF_USER_INIT=MyInit() PF_USER_TERM=MyTerm() PF_STATIC_DIC PF_SUPPORT_FP

Building pForth on Supported Hosts

To build on UNIX, do nothing, system will default to "pf_unix.h".

To build on Macintosh:

To build on PCs:

To build a system that only runs turnkey or cloned binaries:

Compiling for Embedded Systems

You may want to create a version of pForth that can be run on a small system that does not support file I/O. This is useful when bringing up new computer systems. On UNIX systems, you can use the supplied gmake target. Simply enter:

For other systems, here are the steps to create an embedded pForth.
  1. Determine whether your target system has a different endian-ness than your host system.  If the address of a long word is the address of the most significant byte, then it is "big endian". Examples of big endian processors are Sparc, Motorola 680x0 and PowerPC60x.  If the address of a long word is the address of the least significant byte, then it is "Little Endian". Examples of little endian processors are Intel 8088 and derivatives such as the Intel Pentium, X86. ARM processors can be configured as either big or little endian.
  2. If your target system has a different endian-ness than your host system, then you must compile a version of pForth for your host that matches the target.  Rebuild pForth with either PF_BIG_ENDIAN_DIC or PF_LITTLE_ENDIAN_DIC defined.  You will need to rebuild pforth.dic as well as the executable Forth.  If you do not specify one of these variables, then the dictionary will match the native endian-ness of the host processor.
  3. Execute pForth. Notice the message regarding the endian-ness of the dictionary.
  4. Compile your custom Forth words on the host development system.
  5. Compile the pForth utulity "utils/savedicd.fth".
  6. Enter in pForth: SDAD
  7. SDAD will generate a file called "pfdicdat.h" that contains your dictionary in source code form.
  8. Rewrite the character primitives sdTerminalOut(), sdTerminalIn() and sdTerminalFlush() defined in pf_io.h to use your new computers communications port.
  9. Write a "user_chario.h" file based on the API defined in "pf_io.h".
  10. Compile a new version of pForth for your target machine with the following options:
      11. -DPF_NO_INIT -DPF_NO_MALLOC -DPF_NO_FILEIO \
-DPF_USER_CHARIO="user_chario.h" \
-DPF_NO_CLIB -DPF_STATIC_DIC
  11. The file "pfdicdat.h" will be compiled into this executable and your dictionary will thus be included in the pForth executable as a static array.
  12. Burn a ROM with your new pForth and run it on your target machine.
  13. If you compiled a version of pForth with different endian-ness than your host system, do not use it for daily operation because it will be much slower than a native version.

Linking with Custom 'C' Functions

You can call the pForth interpreter as an embedded tool in a 'C' application. For an example of this, see the file pf_main.c. This application does nothing but load the dictionary and call the pForth interpreter.

You can call 'C' from pForth by adding your own custom 'C' functions to a dispatch table, and then adding Forth words to the dictionary that call those functions. See the file "pfcustom.c" for more information.

Testing your Compiled pForth

Once you have compiled pForth, you can test it using the small verification suite we provide.  The first test you should run was written by John Hayes at John Hopkins University.  Enter:

The output will be self explanatory.  There are also a number of tests that I have added that print the number of successes and failures. Enter:

Note that t_corex.fth reveals an expected error because SAVE-INPUT is not fully implemented. (FIXME)


PForth source code is freely available and is in the public domain.

Back to pForth Home Page