WHITE LIGHTNING - SECTION 2 SPECTRA FORTH by Stuart Smith Forth is an extraordinary computer language developed originally for the control of radio telescopes, by an American named Charles Moore. Forth is neither an interpreter or a compiler, but combines the best features of both to produce a super-fast, high-level language, incorporating the facilities offered by an interactive interpreter and the speed of execution close to that of machine code. In order to achieve these fantastic speeds, Forth employs the use of a data, or computation, stack, on which to hold the data or the operations to be performed, coupled with the use of Reverse Polish Notation (RPN). This may be quite a mouthful, but RPN is very easy to use and understand with only a little practice - in fact, Hewlett Packard use RPN on many of their calculators. All standard Forths use integer arithmetic for their operations and can handle up to 32-bit precision if required - floating point mathematics routines could be incorporated, but with a reduction in the execution speeds of a program. White Lightning consists of a standard Fig-Forth model, but with over 100 extensions to the standard vocabulary of Forth words. There are two important extensions to White Lightning; the first is the ability to access almost all of the Spectrum's own BASIC commands, just as you would when writing a BASIC program, and with the addition of many of the high resolution graphics commands (CIRCLE, DRAW, etc). Couple with the incredible execution speeds of White Lightning, the possibilities are limitless! The second, and possibly most important, addition is the IDEAL sub-language. In addition to the basic vocabulary of White Lightning words, the user can very easily add their own new words using previously defined words, thus extending the vocabulary and building up as complex a word as is necessary to do the task in hand. Full structured programming methods are also employed as a fundamental feature of Forth through the use of the structured control sequences included, such as: IF ... ELSE ... ENDIF DO ... UNTIL The standard Spectrum editor can be used to create lines of White Lightning source code for later compilation. Do not allow lines to exceed 64 characters - any characters after this are ignored. The standard Forth line editor is included for compatibility with existing text. The source code is stored in memory from $CC00 onwards, and can be LOADed or SAVEd to tape as and when required. Once the source code is complete, it may then be compiled into the White Lightning dictionary for later execution. Included in this documentation is a glossary of Fig-Forth terms (courtesy of the Forth Interest Group, PO Box 1105, San Carlos, CA 94070). Spectra Forth was written by Stuart Smith, the author of the extremely successful DragonForth, and is an enhancement of a program written by the Forth Interest Group - to whom we offer our thanks. At the time of writing, floppy discs are not readily available for the Spectrum, and instructions referring to discs should be interpreted as accessing RAM. AN INTRODUCTION TO SPECTRA FORTH This introduction does not set out to teach Forth programming, but rather to serve as a supplement to available texts on the subject; references include: "Starting Forth" by Brodie, published by Prentice Hall "Introduction to Forth" by Knecht, published by Prentice Hall "Discover Forth" by Hogan, published by McGraw Hill White Lightning syntax consists of Forth words or literals, separated by spaces and terminated by a carriage return. A valid name must not contain any embedded spaces since this will be interpreted as two distinct words, and must be less than 31 characters in length. If a word is entered which does not exist or has been spelled wrongly, or the number entered is not valid in the current base, then an error message will be displayed. To compile and execute programs created using the Editor type LOAD [CR]. Throughout these examples [CR] means "press ENTER". [...] In order to program in White Lightning, it is necessary to define new words based on the words already in the vocabulary. Values to be passed to these words are pushed onto the stack, and if required the word will pull these values from the stack, operate on them, and push the result onto the stack for use by another White Lightning word. As mentioned previously, Spectra Forth (as with all Forths) uses Reverse Polish Notation and integer numbers, therefore no precedence of operators is available; thus all operations are performed in the sequence in which they are found on the stack; eg. 1 2 + 3 * is equivalent to 3*(1+2) As can be seen, in RPN the operators are input after the numbers on which they have to operate have been input. [...] USING THE EDITOR Generally speaking, most users will want to use the Spectrum editor to type and edit source, but a full Forth line editor is included for compatibility with existing texts. The maximum length of any line is 64 characters; any characters after this will be ignored. Line Editor Included in this version of White Lightning is a line editor to enable you to create source or text files. To facilitate text editing, the text is organised into blocks of 512 bytes, divided into 8 lines of 64 characters. Once the text has been edited, it may then be compiled into the White Lightning dictionary and the text, if required, can be saved to tape. The text is stored in memory in the pages at C000 to F000; therefore, you can edit into screens 1 to 23. If the background facility is utilised, text is stored from CC00 onwards in screens 6 to 23, and screens 0 to 5 cannot be used. Here is a list of the editor commands and their descriptions: H Hold the text pointed to by the top number on the stack of the current screen in a temporary area known as PAD. S Fill (Spread) the line number at the top of the stack with blanks, and shift down all subsequent lines by 1, with the last line being lost. D Delete the line number held on the stack; all other lines are moved up by 1. The line is held in PAD in case it is still needed. Line 7 cannot be deleted. E Erase the line number at the top of the stack by filling it with spaces. RE REplaced the line number at the top of the stack with the line currently held in PAD. P Put the following text on the line number held on the stack, by overwriting its present contents. INS INSert the text from PAD to the line number held on the stack. The original and subsequent lines are moved down by 1, with the last line being lost. EDIT Works just like the normal Sinclair line editor. Also, it does an automatic LIST and an automatic FLUSH. This is far and away the best way to edit and the above are included only for compatibility with existing Forths. CLEAR Clear the screen number held on the stack and make it the current screen. WHERE If an error occurs during the loading of White Lightning's text screens, then keying in WHERE will result in the screen number and the offending line being displayed. You can now use the other editing commands to edit the screen, or you may move to another screen by either LISTing or CLEARing it. In order to compile this screen into the dictionary, it is necessary to use the word LOAD. LOAD This will start loading at the screen number held on the top of the stack and will stop at the end of the screen. If you wish to continue and LOAD the next screen, the current screen must end with --> ; this means "continue loading and interpreting". If you wish to stop the LOADing anywhere in a screen then use ;S ; this means "stop loading and interpreting". At the end of every editing session, and before saving your text, it is necessary to FLUSH the memory buffers into the text area. To do this, just key in: FLUSH [CR] Note that the EDIT command does an automatic FLUSH. You can save your text to tape using the Spectrum 'SAVE' command. You must first enter BASIC by typing PROG [CR] . Now for an example of how to edit a text file. The first step is to either LIST or CLEAR the screen about to be worked on: 9 CLEAR [CR] This sets the current screen to 9. To insert text use the EDIT command. Type 0 EDIT [CR] followed by the text below: THIS IS HOW TO PUT [CR] Then type: 1 EDIT [CR] TEXT ON LINE 1 [CR] and so on, until you have entered: 0 THIS IS HOW TO PUT [CR] 1 TEXT ON LINE 1 [CR] 2 LINE 2 [CR] 3 AND LINE 3 OF THIS SCREEN [CR] 9 LIST will produce: 0 THIS IS HOW TO PUT 1 TEXT ON LINE 1 2 LINE 2 3 AND LINE 3 OF THIS SCREEN 4 5 6 7 To change line 2, type EDIT 2 [CR] and then change it in the normal way to insert 'TEXT ON' before 'LINE 2'. Now type 9 LIST [CR] to see the result. The editor ignores characters after the 64th character of the line being edited. If you have a Sinclair printer connected, then it is probably worth defining a word to list screens to the printer: : SLIST PRT-ON 1+ SWAP DO I LIST CR LOOP PRT-OFF ; To use the above word, type the first screen number, last screen number, SLIST; eg.: 6 9 SLIST [CR] will list screens 6-9 to the printer. FORTH ERROR MESSAGES # 0 A word could not be found, or a numeric conversion could not take place. # 1 An empty stack, which will be encountered when trying to take more values from the stack than exist. # 2 Dictionary or stack overflow. # 4 An existing word has been redefined using a new colon definition. This is not really an error since the new word is still valid, but the old definition cannot be accessed until you FORGET the new one. # 6 Attempt to access a non-existent screen when editing, loading or listing. # 9 An Attempt was made to clear the sprite space of less than 2 bytes. # 10 A non-existent sprite has been referenced, or an attempt has been made to insert a sprite which already exists. # 17 This will occur when trying to use a word in 'immediate' mode which should only be used during a compilation; ie. during colon definitions. For a list of such words, refer to the glossary (words with "C" in the top right-hand corner of the description). # 18 A word meant for execution only has been put within a colon definition (words with "E" in the top right-hand corner of the description). # 19 A colon definition contains conditionals which have not been paired. # 20 A colon definition has not been properly finished. # 21 An attempt to delete something in the protected part of the Forth dictionary. # 22 Illegal use of --> when not loading text screens. # 23 Attempt to edit a non-existent line of screen data. FIG-FORTH GLOSSARY This glossary contains all the word definitions in release 1 of Fig-FORTH. The definitions are presented in the order of their ASCII sort and are reproduced courtesy of the Forth Interest Group, PO Box 1105, San Carlos, CA 94070. The first line of each entry shows a symbolic description of each action of the procedure on the parameter stack. The symbols indicate the order in which input parameters have been placed on the stack. Three dashes "---" indicate the execution point; any parameters left on the stack are listed. In this notation, the top of the stack is to the right. The symbols include: addr memory address b 8-bit byte (ie. hi 8 bits zero) c 7-bit ASCII character (hi 9 bits zero) d 32-bit signed double integer, most significant portion with sign on top of stack f boolean flag; 0 = false, non-zero = true ff boolean false flag = 0 n 16-bit signed integer number u 16-bit unsigned integer tf boolean true flag = non-zero The capital letters on the right show definition characteristics: C May only be used within a colon definition. A digit indicates number of memory addresses used, if other than one. E Intended for execution only. LO Level 0 definition of FORTH-78. LI Level 1 definition of FORTH-78. P Has precedence bit set. Will execute even when compiling. U A user variable. Unless otherwise noted, all references to numbers are for 16-bit signed integers. The high byte of a number is on top of the stack, with the sign on the leftmost bit. For 32-bit signed double numbers, the most significant bit (with the sign) is on top. All arithmetic is implicitly 16-bit signed integer math, with error and underflow indication specified. NOTE: All references to disk in this documentation can be read as references to the disk simulation area in memory from C200H to F000H, which are treated as a very limited disk capacity by White Lightning, and do not in any way change the operation or description of any of the FORTH words defined in this documentation. DO NOT use DRO, DR1 or GO. ! n addr --- LO Store 16 bits of n at address. Pronounced "store". !CSP Save the stack position in CSP. Used as part of the compiler security. # d1 --- d2 LO Generate from a double number d1, the next ASCII character which is placed in an output string. Result d2 is the quotient after division by BASE, and is maintained for further processing. Used between <# and #>. See #S. #> d --- addr count LO Terminates numeric output conversion by dropping d, leaving the text address and character count suitable for TYPE. #BUF --- n A constant returning the number of disk buffers allocated. #S d1 --- d2 LO Generates ASCII text in the output buffer, by the use of #, until a zero double number results. Used between <# and #>. ' --- addr P,LO Used in the form ' nnnn Leaves the parameter field address of dictionary word nnnn. As a compiler directive, executes in colon definition to compile the address as a literal. If the word is not found after a search of CONTEXT and CURRENT, an appropriate error message is given. Pronounced "tick". [... pages 93-118 missing ...] FORTH/BASIC GLOSSARY WORD PARAMETERS ACTION COPY copy screen to ZX printer AT N1,N2 move print position to N1,N2 BORDER N1 set border colour to N1 CLS clear whole screen, home cursor and fill with current attributes DRAW-ARC N1,N2,N3 +/-X,+/-Y,ANGLE; as Sinclair's own CIRCLE N1,N2,N3 X,Y,RADIUS; as Sinclair's own DRAW N1,N2 +/-X,+/-Y; as Sinclair's own PLOT N1,N2 X,Y; as Sinclair's own SCREEN$ N1,N2 leave on the stack the ASCII code of the character at ROW N1, COL N2 ATTR N1,N2 leave on the stack the attribute code of the character at ROW N1, COL N2 POINT N1,N2 test pixel at N1,N2 and leave a true or false flag on the stack TAB N1 set print position to COL N1 OVER N1 zero or one; as Sinclair's own INVERSE N1 zero or one; as Sinclair's own BRIGHT N1 zero or one; as Sinclair's own FLASH N1 zero or one; as Sinclair's own PAPER N1 set paper colour; as Sinclair's own INK N1 set ink colour; as Sinclair's own USR CALLS PRINT USR 24832 enter Forth from BASIC via a COLD START PRINT USR 24836 enter Forth from BASIC via a WARM START PRINT USR 30006 re-enter Forth from BASIC and continue execution of the next Forth word RANDOMIZE USR 30000 call Forth and continue execution up to the first occurrence of the Forth word RETUSR EXTENDED SPECTRA-FORTH GLOSSARY WORD PARAMETERS ACTION PRT-ON send all subsequent output to the printer PRT-OFF send all subsequent output to the screen EDIT N1 edit line number N1 from the current screen WARM->COLD create extended Forth J copy second loop index to the top of the stack K copy third loop index to the top of the stack DUMP N1 memory dump from address N1 WARM perform a warm start EMITC N1 as EMIT but control characters are also supported -- end of Section 2