PFE

Section: User Commands (1)
Updated: 12 Septemer 1993
Index Return to Main Contents

 

NAME

pfe - Portable Forth Environment

 

SYNOPSIS

pfe [-hlqv] [-bFILE] [-dFILE] [-eEDITOR] [-fN] [-kKB] [-rN] [-sN] [filename]

 

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.

KeytermcapCodeCONSTANT


F1"k1"256K1
............
F9"k9"264K9
F10"k0"265K10
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. Please direct any comments to:

duz@roxi.rz.fht-mannheim.de


 

Index

NAME
SYNOPSIS
DESCRIPTION
This manual
OPTIONS
INTRODUCTION TO FORTH
The Basic Ideas Of Forth
The Outer Interpreter
The Compiler
The Inner Interpreter
DESCRIPTION
The Forth Command Line
Special Keys and Signals
Handling signals
Terminal Facilities Available
Return codes of EKEY
DATA STRUCTURES
FILES
ENVIRONMENT VARIABLES
BUGS
AUTHOR

This document was created by man2html, using the manual pages.
Time: 14:49:35 GMT, November 05, 2024