readme.txt

strongForth: a strongly typed dialect of Forth implemented in ANS Forth.

StrongForth.f 1.2
=================


Contents:

1. Introduction
2. Installation and first steps
3. ANS compliance
4. Known issues
5. Version history
6. Next steps
7. Contact



1. Introduction

StrongForth is a programming language that is very close to ANS 
Forth. One of the biggest differences is that it includes strong 
static type-checking. ANS Forth itself is often called "typeless" 
or "untyped", which means that neither interpreter nor compiler 
do any type-checking when applying a function (a "word") to one 
or more operands. It is completely up to the programmer to chose 
the correct functions. In StrongForth, the interpreter and the 
compiler check if a function matches the operands on the stack. 
This allows finding type mismatches and unbalanced loops and 
conditional branches already at compile time. Additionally, it 
is possible to overload words by using the same name for 
different functions, as long as each word expects a different 
set of parameters on the stack. 

The majority of Forth users might believe that strong static 
typing is not Forth-like. Nevertheless, the implementation of 
StrongForth proves that Forth can incorporate static 
type-checking without increasing the complexity of the language. 

StrongForth.f is an implementation of StrongForth in ANS Forth. 
I. e., it is supposed to run as an application on every ANS Forth 
system, taking over properties like the cell size from its host. 
Although StrongForth.f has its own interpreter loop and its own 
dictionary, it takes full advantage of all optimizations that are 
incorporated in the host system's compiler. StrongForth.f has 
been successfully validated on GForth, SwiftForth(TM) and CHForth.

StrongForth.f is distributed under the GNU General Public license 
(see file copying.txt).



2. Installation and first steps

The complete package consists of 17 files:

readme.txt          This file
strong.f            ANS Forth source file of StrongForth.f 1.2
corelib.sf          StrongForth.f core library
facility.sf         Facility word set
memory.sf           Memory-Allocation word set
oop.sf              Object Oriented Programming package
tools.sf            Programming-Tools word set
copying.txt         GNU General Public License
intro.htm           An introduction to StrongForth.f
oop.htm             Object Oriented Programming Tutorial
crossref.htm        An ANS Forth - StrongForth.f cross reference
gforth.htm          StrongForth.f glossary
gfacility.htm       Glossary of the Facility word set
gmalloc.htm         Glossary of the Memory-Allocation word set
goop.htm            Glossary of the Object Oriented Programming package
gtools.htm          Glossary of the Programming-Tools word set
fdl.txt             GNU Free Documentation License

To install StrongForth.f, simply unpack the ZIP file into a new 
directory.

To run StrongForth.f as an application on your ANS Forth system, 
include the file strong.f and then enter STRONG to start 
StrongForth's interpreter loop. After the StrongForth.f command 
line prompt appears, include the core library:

S" <dir>\strong.f" INCLUDED  ok
STRONG  OK
" corelib.sf" INCLUDE  OK

Note that StrongForth uses INCLUDE to include a file, whereas the 
ANS Forth host uses INCLUDED. You might see a lot of warnings 
about redefinitions of words as a response to both INCLUDE's. 
These warnings can safely be ignored, because defining words that 
have the same name as already existing words is not unusual in 
StrongForth. In fact, if your host system allows disabling these 
warnings, you should do so. Your host system has to provide the 
following ANS Forth word sets in order to successfully include 
strong.f:

Core
Double-Number
Exception
File-Access
Locals
Programming-Tools
String

After the core library has been included, StrongForth.f is up and 
running. If you are not yet familiar with StrongForth, it is 
recommended that you start working through the introduction 
intro.htm. Note that standard words are recognized in upper case 
only, because StrongForth.f is case sensitive by default. You can 
turn to case insensitivity by changing the value of the constant 
CASE-INSENSITIVE in the file strong.f from FALSE to TRUE before 
including this file. Integer literals have data type UNSIGNED by 
default, and data type SIGNED if preceded by a sign character 
(- or +). Literals with a trailing decimal point are double-cell 
numbers. To quit StrongForth and return to the ANS Forth host 
system, type QUIT. You can resume StrongForth.f at any time by 
executing STRONG. Since StrongForth's dictionary will remain as 
it was immediately before executing QUIT, you don't have to 
include the core library again. However, note that StrongForth.f 
is an application and not a library. You cannot mix StrongForth 
words and ANS Forth words, because the execution of words that 
are not defined in the StrongForth dictionary will most likely 
corrupt StrongForth's data type system. To exit both StrongForth 
and the ANS Forth host system, type BYE.

Once StrongForth has been started with STRONG, you may include 
additional word sets and other StrongForth source files like the 
OOP package. You can also import additional words from the host 
system with 'HOST, which returns the execution token, and IMPORT, 
which adds a new definition with a given execution token to the 
StrongForth dictionary. Take care to provide a correct stack 
diagram. Here's an example:

'HOST DUMP IMPORT DUMP ( ADDRESS UNSIGNED -- )

If the word to be imported is a parsing word, 'HOST should be 
replaced with 'HOST-PARSING. 'HOST-PARSING creates a wrapper 
definition that ensures parsing is done correctly:

'HOST-PARSING SEE IMPORT SEE ( -- )


3. ANS compliance

StrongForth is not compliant to ANS Forth. The most important 
differences are that a precise stack diagram is included in the 
definition of each word, and that many words are overloaded. 
Other differences between ANS Forth and StrongForth are described 
in intro.htm. crossref.htm is an ANS Forth to StrongForth cross 
reference.

StrongForth.f 1.2 contains the following word sets, which have 
been only slightly modified with respect to the ANS Forth 
standard:

Core
Double-Number
Exception
Facility
File-Access
Locals
Memory-Allocation
Programming-Tools
Search-Order
String

Note that the Facility, Memory-Allocation and Programming-Tools 
word sets have to be explicitly included, while all other word 
sets are already contained in strong.f and corelib.sf. The 
Programming-Tools word set does not contain words related to 
assembler programming, like CODE, END-CODE, ASSEMBLER, and ;CODE.
Including the Facility word set may cause an exception to be 
thrown, because many ANS Forth host systems do not provide all 
words belonging to this word set. The Object Oriented 
Programming package, which may optionally be included, requires 
the Memory-Allocation word set.



4. Known issues

- SEARCH and SEARCH_ALL use TOKEN instead of a qualified token 
  for the callback word.
- CATCH cannot be applied to words whose stack diagrams contain 
  one or more tuples.
- CODE, END-CODE, ASSEMBLER, and ;CODE are not implemented.
- >THIS cannot be used together with LOCALS|. 
  Use LOCALS| THIS ... |
- RECURSE, [PARENT] and [BIND] do not work with AUTOTHIS.



5. Version history

2008-09-29 Version 1.0
- Initial release, including the following word sets:
  Core, Double-Number, Exception, File, Locals, and String.

2008-10-02 Version 1.1
- Defined own versions of TIB and #TIB instead of reusing the 
  host system's terminal input buffer.
- Fixed defects related to parsing.
- Fixed a defect in MATCH.
- Fixed a defect in \ by making it an immediate word. 

2009-02-03 Version 1.2
- Added Search-Order word set.
- Added Memory-Allocation word set.
- Added Facility word set.
- Added Programming-Tools word set.
- Added OOP library with glossary and documentation.
- Added 'HOST-PARSING to allow import of parsing words.
- Added ORIG/DEST as a common parent data type for ORIG and 
  DEST.
- Added PREVIEW-WORD, NO-PARAMS-DOES> and (COMPILE,).
- Added FIRST and LAST.
- Fixed 'HOST, PROCREATES, DOES>, VARIABLE and LOCAL,.
- Added qualified token SEARCH-CRITERION and used it for 
  SEARCH and SEARCH-ALL.
- Added control-flow stack: CFSTACK #NESTING CFSP CFSP! >CF CF>.
- Fixed a defect in ?TOKEN in order to restore the dictionary 
  pointer correctly.
- Fixed SAVE-INPUT and RESTORE-INPUT by extending them for 
  files.
- Changed "<NULL>" in . for DATA-TYPE to "???".
- Removed CODE.




6. Next steps

The following features will be added in the next versions of 
StrongForth.f:

1. Validation for additional host systems.
2. Additional ANS Forth word sets.
3. Improved documentation.



7. Contact

Questions, comments and new ideas are welcome. Send an email to 
[e-mail].

The latest version and up-to-date information are available at 
http://home.vrweb.de/stephan.becher/strongforth.f

February 3rd, 2009