PFE(1)

NAME
pfe - Portable Forth Environment

SYNOPSIS
pfe [-hlqv] [-bFILE] [-dFILE] [-eEDITOR] [-fN] [-kKB] [-rN] [-sN] [filename] current build requires to redirect stderr to a file (or /dev/null)

DESCRIPTION
pfe is a programming environment for the programming language Forth. Forth is a highly interactive, stack oriented language well suited for technical applications. Writing a program in Forth means extending the language until a "word" in the language is the solution of the problem. pfe is nonstandard in that it claims to conform to the draft proposed American National Standard for the programming language Forth. In all other respects it conforms to this new standard. All word sets mentioned in the standard including their extensions are built into pfe and are immediately available. The only missing words are those related to the assembler. Being portable, pfe has no built-in assembler. Additionally pfe is compatible to the FORTH 83 Standard and has several words built in that stem from the FIG Forth model. The goal is to be familiar. pfe is free software; you can distribute it and/or modify it under the terms of the GNU General Public License for Libraries as published by the Free Software Foundation. The author has no plans for turning pfe into a commercial or share-ware product. pfe is available over the Internet by anonymous FTP from roxi.rz.fht-mannheim.de, file: pub/unix/languages/pfe-?.?.?.tar.gz.

  This manual
This manual is not a complete technical description of the portable Forth environment since the draft proposed American National Standard (dpANS) on Forth is an excellent description of 90% of this system which can't be repeated here. The main purpose of this manual is to meet the "additional documentation requirements" specified in the dpANS, i.e. to document the environmental dependencies and the implementational options chosen in the portable Forth environment.

OPTIONS
Starting from your operating system's command interpreter pfe recognizes the following command line options:

-c  Caps lock turned on initially.

-h  Help: Displays a help message and exits.

-q  Quiet: Suppress signon message.

-v  Verbose: Summarize memory usage on startup.

-l  Lower case: Accept lower case input of Forth words.

-bFILE
    The given file is used as block device.

-dFILE
    Load a saved dictionary from FILE.

-eNAME
    Use NAME as editor for text files.

-fN N is maximum number of simultaneously open files.

-kSIZE
    Allocate SIZE KB for all buffers.

-rN N is size of return stack in Cells.

-sN N is size of data stack in Cells.

The defaults for these options can be set at compile time and depend on your installation. The -h option shows the actual settings. Turn an option off by appending a '-' to the letter.

INTRODUCTION TO FORTH
This section is directed to the curious who try this package without deeper knowledge of Forth. It tries to shortly point out some of the basic ideas of forth.

  The Basic Ideas Of Forth
Forth is a stack oriented, extensible programming language. Writing a program in Forth means extending the language such that finally a word or a small set of words in the language solves the given problem. In fact "word" is the technical term in Forth for variables, constants, subroutines -- for almost everything you type in -- except numbers. The typical approach to a programming problem using Forth is `bottom up' and interactive. Most naturally at the beginning of a development words are written to solve very small sub-problems. These words are put together to solve bigger parts of the problem and finally to form the solution of the whole problem. At any time in the evolution of the program all parts can be tested individually by simply typing in the appropriate parameters and words. Being "stack oriented" means: The central data structure in Forth is a stack. Words expect their parameters on top of that stack and replace them by the results. It is neccessary in such a configuration to write a word consuming the parameters following those parameters, i.e. to use postfix notation (or "reverse polish notation", rpn):
        123 456 + 78 * . calculates (123+456)*78 and prints the result. In this example `+' and `*' are the "words" doing addition and multiplication, the numbers provide the parameters and `.' prints the result. You may be acquainted to this concept if you have used an HP calculator. Word names may contain any printable character with the exception of space. Space is used to separate words from each other. You can only use words that were defined before. These two simple rules and the postfix concept make the Forth Interpreter stunningly simple. There is no need for what makes other compilers complex: lexical, syntactic and semantic analysis. When asking if Forth is an interpreted or compiled language you may get different answers. I believe -- at least for pfe -- the correct answer is: Interpreted. But there are two different levels of interpretation and something called a "compiler" is in between of them. Other systems may be true compilers generating machine code. pfe is not such a true compiler.

  The Outer Interpreter
Any input to a Forth system -- wether from keyboard or from a file -- is processed by the outer interpreter. This interpreter does nothing but reading space-separated tokens, distinguishing between numbers and words, putting numbers on the stack and executing words. The executed words do the processing on the numbers.

  The Compiler
When forming a new word by putting together the actions of existing words, the Forth system is said to be "compiling". While recently there are true compilers for Forth available, a traditional Forth system just notes the addresses of all words to be executed in a list. Additionally the compiler can handle all sorts of control structures to make decisions and to loop in a convenient way.

  The Inner Interpreter
A word that was built by the compiler is executed by the inner interpreter. This inner interpreter doesn't need to read space-separated tokens from the input stream any more. This has already been done by the compiler. All the inner interpreter has to do is call every word the compiler has noted in the list. Obviously a word is a kind of subroutine. Typically the inner interpreter is only a handful of machine code instructions. In pfe it's a very tight loop. The lists generated by the compiler and interpreted by the inner interpreter are called "threaded code" and Forth is sometimes referred to as a "threaded interpretive language" (TIL).

DESCRIPTION
To start pfe type pfe. Now you can interactively type in Forth commands. To finish pfe and return to the OS shell, type in BYE.

  The Forth Command Line
Basically pfe is case significant. You must enter built-in Forth words in all upper case. You can define words in lower or upper case at your option but MyWord and myword are two different words. For compatibility with other - case insignificant - Forth implementations say LOWER-CASE ON or use the option -l. This causes pfe to convert all words to upper case prior to dictionary search and thus permits input of forth words in lower case. To make input of upper case text easier, a caps lock mode is supplied. The pfe command line exchanges lower and upper case characters by default. You can toggle this caps lock mode by pressing Ctrl-C on the command line. The pfe command line remembers your old input lines and you can recall them using the arrow up (or ^E) and arrow down (or ^X) keys. Editing the command line is possible with the arrow left/right (^S/^D) keys. Delete characters with your terminal's delete character key or with ^G. Toggle insert mode with your terminal's insert character key or with ^V. The pfe command line completes partially entered Forth words by comparing them to all words in the dictionary (not only those in the search order). Press the Tab-key to complete a word partially typed in. If the completion is unique, a space is appended. If no completion is possible the bell rings. This might have been disabled at compile time. Check your installation if it doesn't work.

  Special Keys and Signals
pfe puts the terminal in a kind of raw mode. All signals are handled by the program and most of them lead to the normal Forth error handling, i.e. the execution of a THROW which can be caught by a Forth program using CATCH. Consequently you can't quit from pfe with the interrupt key. You can use it however to break out of endless loops and to return to the Forth command line when you lost control over your Forth program.

^U  raises a SIGINT which is mapped inside pfe to -28 THROW meaning "user interrupt" and breaks any running Forth program. Returns to the Forth input loop if not caught by CATCH.

^\  raises a SIGQUIT and is equivalent to BYE. No core dump is generated.

^Z  suspends pfe and jumps back to your shell if that shell supports job control.

These keys might have been changed at compile time. Check your installation if they don't work as described.

  Handling signals
pfe tries to catch all signals your system generates and a program can reasonably recover from. The default action for most signals is to THROW an exception you can CATCH. (Others lead to a graceful exit including resetting the terminal so you can continue using it.) Additionally you can handle all signals with Forth words: Given a forth word's execution token (xt) use the word SIGNAL to install the word as handler to an arbitrary signal:
    : PEEP ." PEEP" 7 EMIT CR ;
    ' PEEP SIGINT SIGNAL Now pressing ^U (default interrupt character inside pfe) executes PEEP. Another ^U executes the default action of SIGINT again (i.e. -28 THROW). Use
    0 SIGINT SIGNAL to reset the state of SIGINT to pfe's default.

  Terminal Facilities Available
pfe tries to retrieve the neccessary informations to control the terminal using calls to the termcap library. If this fails a message is displayed after startup. Otherwise the following words to control the screen are available:

HIGHLIGHT
    Sets your terminal's best standout mode sending the "so" string.

-HIGHLIGHT
    Resets your terminal's standout mode sending the "se" string.

UNDERLINE
    Underlined text on, sends the "us" string.

-UNDERLINE
    Underline text off, sends the "ue" string.

INTENSITY
    Brighter text than normal, sending the "md" string.

-INTENSITY
    Normal text sending termcap's "me" string.

BLINKING
    Blinking text sending termcap's "mb" string.

-BLINKING
    Normal text sending termcap's "me" string.

REVERSE
    Reversed video on, sends termcap's "mr" string.

-REVERSE
    Normal text sending termcap's "me" string.

NORMAL
    Normal text sending termcap's "me" string.

Note that due to limitations of the termcap library not every feature can be turned on and off individually. The HIGHLIGHT mode is probably the same as either INTENSITY or REVERSE. This depends on your terminals capabilities and how accurate they are described in /etc/termcap.

AT-XY ( col row ---)
    Moves the cursor to the specified position.

HOME
    Moves the cursor to the upper left corner of the display.

CLS Clears the screen.

CLREOL
    Clears from the cursor position to the end of the current line.

?XY ( -- col row)
    Returns the actual cursor position.

XMAX ( -- col)
    Returns the number of columns on your screen.

YMAX ( -- row)
    Returns the number of rows on your screen.

Note: Since there is no way to retrieve the current cursor position from the terminal using methods of the termcap library, the cursor position is tracked inside pfe. The cursor position is initially unknown. So when using ?XY do an AT-XY, a CLS or a HOME at least once before. The cursor position is tracked by all pfe output operators but if a system call is executed, it gets lost. Same remedy.

  Return codes of EKEY
EKEY checks for all function keys defined in /etc/termcap and returns codes > 255 if one of them is received. For the function keys F1 through F10 the constants K1, K2, ..., K10 are defined.
Key | termcap | Code | CONSTANT
F1 | "k1" | 256 | K1
... | ... | ... | ...
F9 | "k9" | 264 | K9
F10 | "k0" | 265 | K10
arrow left | "kl" | 266 |
arrow right | "kr" | 267 |
arrow up | "ku" | 268 |
arrow down | "kd" | 269 |
home | "kh" | 270 |
home down | "kH" | 271 |
next page | "kN" | 272 |
previous page | "kP" | 273 |
backspace | "kb" | 274 |
delete character | "kD" | 275 |
exit insert mode | "kM" | 276 |
insert character | "kI" | 277 |
insert line | "kA" | 278 |
clear to end of line | "kE" | 279 |
delete line | "kL" | 280 |
clear screen | "kC" | 281 |
Usually those function keys send strings starting with the escape character ASCII 27. Therefore if the escape-key of the keyboard is pressed EKEY consumes it silently and checks if it forms a function key string together with the next keys pressed. If so, EKEY returns the code for that function key, otherwise it returns 27 and the following characters are spooled out on subsequent calls to EKEY.

  DATA STRUCTURES
pfe's internals are designed very traditionally. The data structures are similar to those chosen by FIG Forth and maybe even elder implementations. pfe uses one contiguous memory area allocated at startup. The size of that area is determined by the command line option -k. The area is divided in the following parts (from low to high memory):

Dictionary
    All definitions including their names are located here.

Data stack
    The size of the data stack is determined by the command line option -s. The stack grows from high addresses towards low addresses. The bottom of the data stack, i.e. the highest address of the data stack area, is stored in the variable S0.

Floating point stack
    The floating point stack is separated from the data stack. It's size is controlled by the command line option -p. It's bottom (highest address) can be found in the variable F0.

Return stack
    The size of the return stack is controlled by the command line option -r. It's bottom (highest address) can be found in the variable R0.

POCKET
    This area (1 KB if not changed at compile time) holds the string, that was found by the latest interpretive execution of S". Retrieve it with POCKET COUNT.

TIB This area (256 Bytes if not changed at compile time) holds the latest command string entered in response to QUERY.

History buffer
    This area (4 KB if not changed at compile time) is used to store entered (Forth-) command lines in order to have them available for the history function.

Files and blocks
    For every potentially open file (count controlled by the command line option -f) a 1 KB buffer plus some administrative information is allocated here. If the file is used as block device, the one KB buffer is the only block buffer in use. Otherwise the buffer is used as line buffer for INCLUDED.

FILES
pfe relies heavily on termcap functions. If on your installation the keyboard doesn't work as described, please check if the function keys are set up correctly in /etc/termcap. If you are using pfe in an xterm, check your .Xmodmap too. pfe includes ~/.pferc at startup.

ENVIRONMENT VARIABLES
pfe looks for the following environment variables:

PFEOPTIONS
    processed like command line options but before the command line options. You can store your favourite settings there and still override them on the command line.

PFEINCLUDE
    list of directories (according to the syntax of the PATH variable) where pfe looks for block files (USING) and for files to include (INCLUDE, INCLUDED).

BUGS
Don't use ^Z to suspend jobs started from pfe, e.g. the text editor. Doesn't recognize cursor keys when running in an xterm. Those I didn't notice yet and those I plan to fix really soon.

AUTHOR
pfe was written 1993-1994 by Dirk Uwe Zoller, Mannheim, Germany. Latest changes are due to Tektronix Inc, CTE, Berlin, Germany. Please direct any comments to:
Guido.Draheim@exgate.tek.com