Part 1. Programmer's Reference
Well, here I go again, off into another large project meant mostly for myself but hopefully of use to a few others as well when complete. Specifically, the task here is doing a manual for those who desire to diddle around with my favorite Forth compiler, as highly modified and adapted to my tastes. Since I've never taken the time to write a manual like this before, I think I'll start by copying the table of contents from a language manual laying on my desk and then add or subtract from the entries as they apply to Fig-Forth and this compiler. So please bear with me and give me all the feedback you can, and maybe in time someone can actually follow all this rambling. I'm none too good at dreaming up easy examples of code here, but I'll try to include some as I go along. Please note that I have been using this compiler for a number of years, so it is not an experimental, theoretical or alpha test program. Finally, since I've had problems with the internal formatting options of MS-Word, RTF and other formats, I'm inflicting everyone with an HTML version of this material. Hopefully this will also allow interactive links between the pages, as I manage to construct them. I know I said the previous version would be the last, but one must still correct errors when located. (See Final Comments.)
This documentation and software are distributed under the try-before-you-buy shareware concept, in that if you find it useful you are required to register and pay for the program within a reasonable period. It has taken a great many hours to construct this project, and a great many more to write this manual. You are granted license to create, develop and distribute application programs and their source code providing; there is no charge for the package, the copyright notice of the compiler is contained bearing the version number and date of the compiler, and the copyright notice and these terms are included. A reference to me and the compiler as the build system is expected in your documentation. Registration price is $25 US funds or market equivalent at the time of registration, for which I will offer support, utilities and assistance to your development. Emailing me is a good start, for I'm very willing to help friends.
Fig-Forth v2 may be distributed providing there is no charge for the executable, its utilities or documentation, though a small media fee may be charged for package distribution. Modification, decompiling or disassembling the package is not permitted. All parts are copyright owned this date or before and may not be sold in any form without written consent of the author, including but not limited to as part of software archives or libraries, CD-ROM collections, or other use. No warrantees, claims or guarantees are made or implied concerning Fig-Forth v2's stability or suitability for any use, and the user assumes full responsibility for any damages, inaccuracies or losses incurred by the operation of the software. If you desire special licensing arrangements for the use of this package, contact the author.
Fig-Forth v2 is a real mode 16 bit Forth language compiler and interpreter, designed for use upon an MS-DOS operating system in an IBM compatible machine with an Intel 386 or higher processor. Current requirements are a minimum of 256K free ram and 3 or more megabytes of disk space, (7 megabytes or more for the development package) a 100% compatible VGA, SVGA or VESA video card, with a modem, mouse and sound card as optional devices.
Fig-Forth v2 currently features two virtual memory pointers, 20 files open at a time, several graphics modes with fixed and proportional load-able fonts, font scaling, transparent mouse and modem interface, quad and double precision numbers, integer sine, cosine and square root functions, internal random number generator, and some specialized graphics routines. All of the compiler is written in run-time functions, with each fragment operable as a system call. Special search, compare and shell routines are employed. Most video cards are supported with or without VESA installed. Fast linking and program overlay creation has been fully implemented, with internal 8 bit sound drivers included.
To install the package unzip the delivery file into a directory of its own, then create a suitable shortcut or batch file to locate the executable. If in Windows 95 or higher platform set the shortcut properties to Full Screen usage without Screen Saver, as several display modes available in Fig-Forth are not compatible with the Windows Screen Emulation software. As a tip it is suggested to point your shortcut to the enclosed batch file FF.BAT, because this also contains a default command line to instruct Fig-Forth to load the screen based Editor on start-up. You can modify this batch file to load or run other programs as well, or follow the example given to create additional batch files as you deem necessary. For best speed of operation you should set Idle Sensitivity to zero, as listed under the Misc. Section of the shortcut window. In addition, if you desire to have Fig-Forth running a long computation in background, turn off the "suspend background" option in Windows 95. (Only applicable to TEXT-ONLY programs!)
Second, unzip the file MANUAL.ZIP to the Forth directory for the documentation, or optionally move the file to a sub-folder and unzip in that location. Because the new manual is formatted in HTML code, you may freely create a desktop or other icon to any chapter, or chapters, as are deemed necessary. As of this writing, the manual begins with the page of CONTENTS.HTM. See the PACKING.LST file for details of the files contained in the package.
This manual is broken up into three distinct sections, a programmer's reference, a user's guide and the appendixes. Those already familiar with the Forth language, or a previous installation of this software, will find parts one and three of greater use for moving code written previously to the new platform. Part two is meant to introduce programmers of other languages to Forth and this variation specifically, covering the most common functions in descending order. The appendixes are provided to allow reference and location of any specific information, along with code examples if such exists as of this writing. It is up to the user of this package to determine their best course at navigating the material, with the exception of the user's guide which offers a self paced course in becoming familiar with the compiler. Not all of the information contained in any one section is duplicated in the other sections, mostly because I'm lazy but also for download and printing size.
Version 2.24 made several advancements in the area of quad arithmetic, added integer square root functions, included the Write Mode 1 or fast paste for unchained video graphics, and an imbedded random number generator. 2.24 also added the shortcuts of 3+ and 3- and a much easier to use overlay word.
Version 2.25 added some new data manipulation words, a brand new input processor for dotted operations, and major changes to the video control words of VMODE and ATTR.
Version 2.26 contains the much needed DMIN and DMAX words, plus the added flag indicator of OV for divide overflow. Video synchronization has been extended and the integer division routines have changed their output values. Added ?DO, CASE:, :END, ?EXIT, SWITCH, LIBRARY and NEEDS. EXIT word changed, compiler code tweaked, Font Printer improved.
Version 2.27 added the UNLOOP word, just because it's useful. 2.27 also corrected a minor syntax enforcement error at the end of a definition, just because... (Beautification process.)
Version 2.28 corrects a minor bug in the VESA interface not spotted earlier, plus adds a new symbol search to the editor program. Demo timings corrected, sound card addressing expanded. Added TUCK & SIZE$.
Version 2.30 corrects (I hope finally) the read-write error inside the VESA video routines and changes the philosophy the compiler uses to detect the video card. Three new video modes are available, changing the VSTART video function. The CASE: and :END syntax has been relaxed with the addition of a token thread optimizer, shattering the one-to-one correspondence of token and source code. Reinstated +- and D+- from the Forth list of Core words, adding Q+- for good measure.
Version 2.31 corrects a library operation error both in code and documentation, plus adds another case to the optimizer. Included sample library file.
2.32 corrects an input processor error not spotted previously and discontinues the (FIND) and -FIND words in favor of the ANS compliant FIND definition. Restructured user variables.
See the Compatibility Appendix for information regarding changes to application source code.
Fig-Forth v2 is a Super-Set compiler and interpreter of the Forth Language as modeled by John Cassidy and made available by the Forth Interest Group. Containing both an interactive compiler and interpreter within the same package, Fig-Forth v2 offers a rapid development environment for program creation, a single pass compiler for code generation, and a large user space for holding user definitions. Because this is a Fig-Forth it does not conform to the ANS standard of Forth, and would probably be hard pressed to adhere to the Forth79 or Forth83 standards as well. It is therefore a FIG version of Forth, with all the limitations and syntactical enforcement imposed by that model.
This Super-Set of Forth also contains many functions and definitions not found in any of the above standards, since the package was created solely with the IBM-PC as its operating target. It is therefore intended to be a design and development tool upon this type of machine for DOS or Windows full screen applications, with an emphasis on developers and experimenters upon this platform. The compiler has gone through many changes and growth spurts in different directions, as the time has come to me and my own interests lead. So be careful!
Fig-Forth v2 contains a single-pass, double indirection, thread based compiler with a minimum of syntactical and type-checking enforcement code. It assumes that the programmer is aware of all the sizes, states and addresses handed to any function, and what the result will be from executing any portion of the kernel code using these parameters. It is therefore expected that the programmer will have an intimate or extended knowledge about the platform hardware, such that each function can be executed without generated errors. Because of the manner in which code chains are constructed Fig-Forth v2 is equivalent to a machine language assembler, without the data type enforcement normally present in such a system.
Fig-Forth v2 utilizes the double stack method of parameter passing and program control, currently offering a 512 item deep nested control stack and an N-deep parameter stack as there is available memory. The kernel code and user space occupy two different segments within the IBM machine system RAM, offering the greatest amount of user space for the creation of applications. Finally, Fig-Forth v2 offers four 1024 byte disk access buffers, a 256 byte user input space, and a transparent mouse, modem and sound card interface unit.
As in all Forth language packages, nearly every command word executed is expected to have any parameters specified in Reverse Polish Notation, such that the addition of 8 and 5 would appear as 8 5 + within the Forth line. Exceptions to this rule are outlined in this text, and will be caught by the compiler if attempted with an improper format. Refer to the Language Guide for more information.
Fig-Forth v2 is designed to be used with the Forth language as created by Charles Moore and Elizabeth Rather in the early 1970's, more precisely utilizing the Forth Interest Group variant of this language as it stood at the start of Sept. 1980. Because Fig-Forth v2 is also a super-set of this standard intended for the IBM class of computing hardware, a great many definitions and functions have been added to the root kernel. However, the syntactical enforcement of the Cassidy model is in operation within Fig-Forth, such that the following formats of command lines is required;
<spaces>
All words, labels, numbers and functions in Fig-Forth are required to be surrounded by ASCII spaces, the single exception being the keyboard input in which a carriage return functions as an input terminating space.
[value(s)] <dictionary word> [new word, parameter or command]
This sequence is used to create or set variables, open, load or edit files, and in some cases test previously defined functions for proper operation. The compiler begins such sequences in the Execution Mode, creating an active stack value for any number given and then running the dictionary word with that value as a parameter. Any subsequent values or commands are processed after the dictionary word has completed operation.
<create> <name field> [dictionary words] <end-create>
This sequence is used to add a function to the current dictionary, consisting of a list of redirection tokens for the kernel code to execute at a later time. All words calling CREATE require that the words in the given list already exist within the dictionary space, and are accessible within the vocabulary being constructed or referenced.
<flag or value> IF [dictionary words] [ELSE dictionary words] THEN [dictionary words]
This sequence is the conditional operation statement for making tests and branches within a token list. ELSE is optional but every IF must have a THEN, or an error is generated.
BEGIN [dictionary words] <flag or value> UNTIL
This is one of the four loops constructed in Fig-Forth. All portions must be present for proper operation, and the compiler will generate an error for any BEGIN or UNTIL not having the other.
BEGIN [dictionary words] AGAIN
This sequence constructs a never-ending loop (other than by errors, ABORT or QUIT) and both BEGIN and AGAIN must be present for operation.
BEGIN [dictionary words] <flag or value> WHILE [dictionary words] REPEAT
This sequence is the conditional execution loop, which requires that all three words are present. The flag or value is considered only at execution time.
<ending value> <starting value> DO [or ?DO] [dictionary words] LOOP [or <value> +LOOP]
This sequence is the counted loop in Fig-Forth. Every DO must have a LOOP or +LOOP.
CODE <name field> [or ;CODE] <assembly instructions or bytes>END-CODE
This sequence is used to add machine instructions to any definition, calling the Assembler if it is loaded. Assembly errors originate from the assembler package.
Fig-Forth v2 uses several standard structures for its internal operation, but supports only the byte array for program development. While the creation of additional structures is not forbidden by the compiler operation, the driver code for these structures must be defined within the dictionary space before their subsequent use. Examples of such addressing, implementation and use of these structures is available in this manual.
Back to Contents. Next Chapter