Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD1.mdf / forth / compiler / bbl / doc / bbl.doc < prev next >

Wrap

Text File | 1986-10-25 | 261.9 KB | 6,667 lines

BBL FORTH REFERENCE General BBL (Big Business Language or Big Black Lady) is a public domain 32- bit Forth Compiler for MS-DOS machines. It is written in Microsoft Assembler version 4. You are free to use, sell, modify or cannibalize any parts of BBL without credit. All source, object code and documentation can be used for any purpose, except military. This documentation covers the BBL Forth compiler. It is a reference document -- not too much use for learning. To learn how to write BBL Forth you should read Leo Brodie's Starting Forth and practice with a 16-bit Forth-79 compiler. BBL is usually used as the underpinnings of the Abundance language, but it can stand on its own as a very fast 32- bit Forth-83 compiler. The most common BBL verbs are also documented in ABUN.DOC, but all the BBL verbs described here can also be used in Abundance programs. Learning BBL Forth To get an overview of the internal workings of Forth you might read the Forth article by Mahlon G. Kelly and Nicholas Spies in the 1986 September PC Tech Journal. You cannot truly understand, appreciate or milk the full power of Forth until you have an understanding of how it works under the hood. Unlike most other languages, the applications programmer is expected to tinker with the innards to take command of the compiling process. There is a wealth of documentation embedded in the BBL compiler listings in either BBL.LST or BBL*.ASM. Looking at the assembler source code for a word can often be far more informative than reams of documentation. I personally learned Forth without any documentation at all; I just studied John James PDP-11 FIG-Forth compiler listings. The other way to learn about a word is to use the editor to search for uses of the word in the source code examples. I also strongly recommend reading BBLDOC.ASM which gives an overview of how the BBL Forth compiler works internally. There are lots of beginning Forth books, but they just tell you the easy stuff you can figure out with no trouble on your own. Brodie goes a little further than most with his Under the Hood chapter. I have never seen a decent description of how to create your own IMMEDIATE words like IF THEN and .". I have never seen a really decent explanation of CREATE DOES> and ;CODE. They are handled in advanced magazine articles, but by the time you are knowledgeable enough to understand them, you have figured out it out on your own already. One of the best intermediate books is Kevin McCabe's Forth Fundamentals Volume 2 - The Language Glossary. It shows some of the \BBL\BBL.DOC -1- last updated 1986 October 14 21:30 BBL Forth Reference source listings of a heavily-commented simple-minded Forth-79 compiler, written for clarity rather than speed. Later you might subscribe to Forth Dimensions, PO Box 2786, Rochester New York, 14627, USA. It is an advanced magazine. Someday I might be smart enough to understand it. They use thermometers on the articles to warn you of the degree of difficulty, and there is some material for beginners, but if you are a rank amateur, reading it may prove discouraging. The problem with Forth is that once you understand it, it is so simple and elegant no explanation seems necessary. Yet as soon as you try to explain it, it sounds like Greek. Some day I may have the time to write some real documentation that does not presume you already know Forth. In the meantime, all I can say is Forth is the most deeply satisfying language I have ever encountered -- and I have used dozens of them. Learning it is well worth the considerable initial effort. However, the document you will keep coming back to is this one -- the BBL reference document. Think of Forth as a secret code you have to crack. The way you find out 80% of your knowledge will be by performing experiments. Do not feel discouraged; experiments are easier to perform in Forth than in any other language you are likely to have tried. When I teach Forth, I tell the kids, "Here are some words DUP SWAP ROT PICK. See if you can figure out what they do." Even my Mom figured them out eventually. BBL and Forth-83 Roughly speaking, BBL is just like a standard 16-bit Forth-83, except instead of working on 16-bit quantities on the stacks it works with 32-bit quantities. All the standard operators work on 32-bit quantities instead of 16-bit ones. Another difference is that, instead of being simple 16-bit offsets relative to the start of the program, addresses are 32-bit absolute machine addresses formed of a 16-bit segment and 16-bit offset portion. To get the true 20-bit linear address, the 8088 addressing hardware adds the segment (shifted four bits left -- i.e. multiplied by 16) to the offset. Thus the same 20-bit physical address can be gotten at with a number of different segment and offset combinations. A given segment register can be used to cover 64K -- in other words with a given segment you can get at the following 64K worth of addresses without having to change the segment register. All the string handling instructions are limited to strings of 64K where the beginning and end of the string are covered by the same segment. To learn more about segments and offsets you will have to read The 8086 Book by Russell Rector and George Alexy. Before that makes much sense, you will probably need a fair understanding of 8086 assembler programming. I have bad news. The 8086 has the most complex machine language of anything short of a Burroughs 6700. \BBL\BBL.DOC -2- last updated 1986 October 14 21:30 BBL Forth Reference 16-bit Forth-83 programs are limited to 64K. BBL 32-bit Forth programs are limited to 1,000K -- a full megabyte. BBL has a much more complex dictionary structure than the FIG Forth model. The complexity allows much faster compilation, much more compact code, and execution speeds that rival the best 16-bit Forth compilers. Errors Parts of this document may sound like it was written by a lawyer. That is because was derived from the Forth-83 standard document. The original document was typed by volunteers with no computer experience. Thus many strange errors crept in. If you doubt your eyes, perform experiments, consult the Forth-83 standard, and examine the compiler listings. There are still numerous errors in this document, so take anything you read with a grain of salt. Please report even minor errors so I can clean them up and save future generations of programmers the frustration. Stack Parameters There are two stacks in Forth the Data stack where intermediate calculation are stored and the Return stack where BBL keeps track of what routine called what routine. Numbers and addresses can be pushed to either stack. The format is the same for both stacks. Unless otherwise stated, all references to the stack refer to the data stack not the return stack. Unless otherwise stated, all references to numbers apply to 32-bit signed integers. The following are the stack parameter abbreviations and types of numbers used throughout the glossary. These abbreviations may be suffixed with a digit to differentiate multiple parameters of the same type. flag Boolean value. 0 represents false. Any non-zero value represents true. Most commonly -1 is used for true. Note that in Forth-79 (Leo Brodie's book) 1 is most commonly used for true. Flags are always 32-bits. A flag is called canonical if it is normalized to either 0 or -1. true Boolean value. As a result it is always a canonical - 1. As an operand it is any non-zero value. Always 32- bits. false Boolean value. 0. Always 32-bits. \BBL\BBL.DOC -3- last updated 1986 October 14 21:30 BBL Forth Reference c Unsigned 8-bit integer or IBM-extended ASCII character {0 .. 255} {0 .. FF} {0 .. 28-1} Takes 8 bits in RAM, 32 bits 0-extended on the stack. w Signed 16-bit integer {-32,768 .. 32,767} {8000 .. 7FFF} {-215 .. 215-1} Takes 16 bits in RAM, 32 bits sign-extended on the stack. +w Positive signed 16-bit integer {0 .. 32,767} {0 .. 7FFF} {0 .. 215-1} Takes 16 bits in RAM, 32 bits 0-extended on the stack. uw Unsigned 16-bit integer {0 .. 65,535} {0 .. FFFF} {0 .. 216-1} Takes 16 bits in RAM, 32 bits 0-extended on the stack. t signed 24-bit integer {-8,388,608 .. 8,388,607} {800000 .. 7FFFFF} {-223 .. 223-1} Takes 24 bits in RAM, 32 bits sign-extended on the stack. +t Positive signed 24-bit integer {0 .. 8,388,607} {0 .. 7FFFFF} {0 .. 223-1} Takes 24 bits in RAM, 32 bits 0-extended on the stack. ut Unsigned 24-bit integer {0 .. 16,777,215} {0 .. FFFFFF} {0 .. 224-1} Takes 24 bits in RAM, 32 bits 0-extended on the stack. n Signed 32-bit integer {-2,147,483,648 .. 2,147,483,647} {80000000 .. 7FFFFFFF} {-231 .. 231-1} Always 32 bits. \BBL\BBL.DOC -4- last updated 1986 October 14 21:30 BBL Forth Reference +n Positive signed 32-bit integer {0 .. 2,147,483,647} {0 .. 7FFFFFFF} {0 .. 231-1} Always 32 bits. u Unsigned 32-bit integer {0 .. 4,294,967,295} {0 .. FFFFFFFF} {0 .. 232-1} Always 32 bits. d Signed double precision 64-bit integer. {-9,223,372,036,854,775,808 .. 9,223,372,036,854,775,807} {8000000000000000 .. 7FFFFFFFFFFFFFFF} {-263 .. 263-1} Always 64 bits. +d Positive signed double precision 64-bit integer. {0 .. 9,223,372,036,854,775,807} {0 .. 7FFFFFFFFFFFFFFF} {0 .. 263-1} Always 64 bits. ud Unsigned double precision 64-bit integer {0 .. 18,446,744,073,709,551,615} {0 .. FFFFFFFFFFFFFFFF} {0 .. 264-1} Always 64 bits. addr An absolute segment:offset machine address. {0000:0000 .. FFFF:FFFF} Always 32 bits. The offset can have any value {0 .. FFFF}, but it is usually kept small enough so that the same segment can cover any useful data following this address. The offset is kept in the LSW (low order 16 bits) and the segment is kept in the MSW (high order 16 bits). For most practical purposes this address can be treated as if it were a plain 32-bit integer offset from the beginning of RAM. For example, you can add 1 to an address to get the segment:offset of the following address. Before you can compare two addresses, they must both have the same segment or they both must be converted to relative addresses. Compare absolute addresses using unsigned compares and relative addresses using signed compares. \BBL\BBL.DOC -5- last updated 1986 October 14 21:30 BBL Forth Reference caddr A canonical absolute segment:offset machine address. The offset is always in the range 0 .. 15. Always 32 bits. pronounced "canonical address". When addresses are in this form, they cover the most territory after them. In other words addresses up to 64K past the address can be got at by simple addition to the offset portion without adjusting the segment portion of the address. LSW Least significant word - low order 16 bits of a 32-bit quantity. MSW Most significant word - high order 16 bits of a 32-bit quantity. saddr A screen address in the REGEN buffer. {0 .. 3999} { 0 .. (25*80*2)-1 }. The offset of a character or attribute byte being displayed on the screen. Note this is not the segment:offset address of the character. At the even byte e.g. saddr 0, 2, 4 ... in the REGEN buffer is the character currently displayed in the upper-left corner of the screen. At the following odd byte e.g. saddr 1, 3, 5 ... is the attribute byte for that character that determines if it is blinking, bright, dim, red, green, yellow, etc. pronounced "sadder" raddr A relative address. The offset from the beginning of the program as a 32-bit signed integer. Note this is not in segment:offset form. Before you can compare two absolute addresses, they must both have the same segment or they both must be converted to relative addresses. Compare absolute addresses using unsigned compares and relative addresses using signed compares. pronounced "relative address" Addition There is no word "addition" in BBL, however all addition operators work the same way. All addition operators work on either signed or unsigned quantities. Overflow is ignored; only the least significant bits of the sum are kept. 12 2 + -- 14 -12 2 + -- -10 12 -2 + -- 10 -12 -2 + -- -14 c.f. + D+ 1+ 2+ 4+ +! \BBL\BBL.DOC -6- last updated 1986 October 14 21:30 BBL Forth Reference Subtraction There is no word "subtraction" in BBL, however all subtraction operators work the same way. All subtraction operators work on either signed or unsigned quantities. Overflow is ignored; only the least significant bits of the difference are kept. Subtraction is done by taking the two's complement of the subtrahend and adding it to the minuend. 12 2 - -- 10 -12 2 - -- -14 12 -2 - -- 14 -12 -2 - -- -10 c.f. - D- SWAP- 1- 2- 4- -! NEGATE ?NEGATE DNEGATE ?DNEGATE NOT Multiplication There is no word "multiplication" in BBL, however all multiplication operators work the same way. All multiplication operators work on either signed or unsigned quantities. Overflow is ignored; only the least significant bits of the product are kept. Multiplication by powers of two is done with shifts. Use of the NEC V20 PD 70108-5 microprocessor greatly speeds multiplication. The new processor chip costs under $20 and simply replaces the 8088 chip. If you have an 8MHz accelerated clock machine you will need the faster 70108-8. 12 2 * -- 24 -12 2 * -- -24 12 -2 * -- -24 -12 -2 * -- 24 c.f. * M* UM* Q* */ */MOD 2* 4* 8* 10* 16* 64* 256* SHIFT Division There is no word "division" in BBL, however all division and MOD operators work the same way using integer floored division. BBL takes the next lowest integer if the quotient is fractional. The remainder has same sign as divisor. The result of division by zero is 0 remainder 0. The absolute value of the remainder is always less than the divisor. Division is so defined that if you take the quotient and multiply it by the divisor and add back the remainder you will get the dividend. Surprisingly some other languages (including earlier versions of Forth) do not have these obvious Euclidean properties for division when negative numbers are involved. Even though it is possibly contrary to the Forth 83 standard, BBL recovers from division by 0 by giving a 0 quotient and 0 remainder without any error message. It also recovers from overflow of the quotient by giving the least significant part of the quotient without issuing any error message. \BBL\BBL.DOC -7- last updated 1986 October 14 21:30 BBL Forth Reference Use of the NEC V20 microprocessor greatly speeds division. When this processor is not used, BBL checks for numerous special cases to optimize division. Even in the worst case, BBL handles a 64 by 32-bit divide in 2 DIV and 2 MUL instructions -- a substantial improvement over Knuth's standard multiprecision algorithm used in most other Forth compilers. If all goes well, other compilers will soon cannibalize BBL's algorithm. 12 2 /MOD -- rem 0 quot 6 -12 2 /MOD -- rem 0 quot -6 12 -2 /MOD -- rem 0 quot -6 -12 -2 /MOD -- rem 0 quot 6 10 4 /MOD -- rem 2 quot 2 -10 4 /MOD -- rem 2 quot -3 10 -4 /MOD -- rem -2 quot -3 -10 -4 /MOD -- rem -2 quot 2 10 0 /MOD -- rem 0 quot 0 -10 0 /MOD -- rem 0 quot 0 Here is a complete list of division operators: Unsigned division MU/MOD ( num-64 denom-32 -- rem-32 quot-64 ) Q/ ( num-32 denom-32 -- quot-32 ) Q/MOD ( num-32 denom-32 -- rem-32 quot-32 ) QMOD ( num-32 denom-32 -- rem-32 ) SHIFT......( num-32 -n -- quot-32 ) UM/MOD-OVL ( num-64 denom-32 -- rem-32 quot-32 ) UM/MOD ( num-64 denom-32 -- rem-32 quot-32 ) UMMOD ( num-64 denom-32 -- rem-32 ) UM/ ( num-64 denom-32 -- quot-32 ) U/MOD ( num-32 denom-32 -- rem-32 quot-32 ) UMOD ( num-32 denom-32 -- rem-32 ) U/ ( num-32 denom-32 -- quot-32 ) Signed division M/MOD ( num-64 denom-32 -- rem-32 quot-32 ) MMOD ( num-64 denom-32 -- rem-32 ) M/ ( num-64 denom-32 -- quot-32 ) /MOD ( num-32 denom-32 -- rem-32 quot-32 ) MOD ( num-32 denom-32 -- rem-32 ) Q/ ( num-32 denom-32 -- quot-32 ) Q/MOD ( num-32 denom-32 -- rem-32 quot-32 ) QMOD ( num-32 denom-32 -- rem-32 ) / ( num-32 denom-32 -- quot-32) 2/ ( num-32 -- quot-32) D2/ ( num-64 __ quot-64) */MOD ( n1*n2/n3 -- rem-32 quot-32 ) */ ( n1*n2/n3 -- quot-32 ) \BBL\BBL.DOC -8- last updated 1986 October 14 21:30 BBL Forth Reference The Data_Stack Unless otherwise stated, all references to the stack refer to the data stack not the return stack. The Data stack is always maintained in 32-bit (4-byte) chunks. All values are stored with the most significant 16 bits on the top of the stack i.e. in lower memory because the stack grows down. Within each 16 bits the least significant byte is stored first in lower memory. For 64-bit quantities, the most significant 32 bits are stored on the top of the stack, i.e. in lower memory. Note this is NOT the same format used to store data in RAM. For further clarification see the notes in the BBL compiler listings or perform some experiments with DUMP C@ W@ UW@ T@ UT@ @ 2@ SP@ and .S. When values are fetched to the stack that are not even multiples of 32 bits, they can be padded out to 32 bits in one of two ways: pad on the left with zeros, or pad on the left with either zeros or ones depending on the sign bit. The first style is called 0-extension and is used for unsigned positive quantities. The second style is called sign-extension and is used for signed quantities. C@ UT@ UW@ do not sign extend, whereas W@ and T@ do. In other words C@ UT@ UW@ are for unsigned quantities, W@ and T@ are for signed quantities, and @ and 2@ are for both signed and unsigned. For further clarification see the notes in the BBL compiler listings. The Return_Stack Unless otherwise stated, all references to the stack refer to the data stack not the return stack. The Return stack is always maintained in 32-bit (4-byte) chunks. All values are stored with the most significant 16 bits (the segment) on the top of the stack i.e. in lower memory because the stack grows down. Within each 16 bits the least significant byte is stored first in lower memory. The most common things to find in the Return stack are the return addresses pushed there by : so that after each routine ends, BBL knows where to carry on in the calling routine. The addresses are always absolute segment:offset. Because CREATE canonizes HERE, the offset portion of a return address is usually a number under 100, but the address is not necessarily canonical (offset under 15). The return address points to the 16-bit token in the calling routine after the one currently being executed. Using the words >R R@ and R> you can use the Return stack as a helping hand when the Data stack is getting too complex. However you must be VERY careful to balance your >Rs and R>s within a routine. When you use the Return stack as a helping hand, you you had better get it put back the way it was before you exit, unless you really know what you \BBL\BBL.DOC -9- last updated 1986 October 14 21:30 BBL Forth Reference are doing. Most system crashes are caused by not pairing >R and R> properly. The symptoms of a unpaired >R R> are ghastly things like returning to DOS or rebooting or hanging. RANK NOVICES SHOULD AVOID USING THE RETURN STACK AS A HELPING HAND. DO loops use the return stack to save three quantities -- the current loop index, the limit, and the LEAVE address. For this reason you must be careful with words like >R R@ R> and EXIT where loops are involved. Internal RAM formats When numbers are stored in RAM with C! W! T! ! or 2! then 8-bit, 16- bit, 32-bit, 24-bit or 64-bit data are stored least significant byte first in low memory taking up 1, 2, 3, 4 or 8 bytes respectively. Note that storing operators such as W! and T! work equally well on signed or unsigned quantities whereas fetching operators such as W@ and T@ have unsigned versions such as UW@ and UT@. The format used for storing numbers in RAM is different from the format used on the stack where numbers always occupy either 4 or 8 bytes. ON is equivalent to -1 SWAP ! and OFF is equivalent to 0 SWAP !. Vocabularies and Search Order The main differences between FIG Forth, Forth-79 and Forth-83 are the way they handle vocabularies. BBL follows the Forth-83 ONLY ALSO format which is quite different from FIG Forth. What are vocabularies used for? When you are working with the ASSEMBLER vocabulary the word BL refers to the low 8 bits of the BX register. When you are using the FORTH vocabulary BL refers to the hex constant 20 -- the ASCII code for blank. Vocabularies allow the same word to have different meaning s in different contexts. Vocabularies can effectively hide definitions from the users of your programs. You can place intermediate definitions you don't want anyone to use in one vocabulary and ones you do want them to use in another. There are two vocabularies of importance. The first is the CONTEXT vocabulary where BBL first goes to look up the meaning of a word. The second is the CURRENT vocabulary where BBL places new definitions. To set the CONTEXT vocabulary you simply mention the name of the vocabulary e.g. MY-VOC. To set the CURRENT vocabulary you use the word DEFINITIONS e.g. MY-VOC DEFINITIONS. Note that MY-VOC also set the CONTEXT vocabulary. If you want to set the current and context vocabularies to different things, you must do something like this: MY- VOC DEFINITIONS FORTH. \BBL\BBL.DOC -10- last updated 1986 October 14 21:30 BBL Forth Reference This seems simple enough, but most of the time you want BBL to search 2 or 3 different vocabularies -- e.g. HIDDEN EDITOR and FORTH. You also want to control the order in which the vocabularies are searched. For speed you want to look in the most likely vocabulary first. If a word appears in two different vocabularies with two different meanings, the search order becomes very important. There is never any need for more than one CURRENT vocabulary at a time, simply because you cannot dither about which vocabulary you want new definitions placed in. The usual case is that you have one transient CONTEXT vocabulary -- the first in the search order which you change all the time -- maybe several times within a single definition. You also have 1 to 5 resident CONTEXT vocabularies to search as a backup if the word cannot be found in the transient vocabulary. Usually you don't change these resident vocabularies very often. The transient vocabulary may even be a duplicate of one of the resident vocabularies. We have already discussed how you change the transient vocabulary -- all you do is mention its name. How then do you add a resident vocabulary? You simply make a vocabulary the transient vocabulary then use the word ALSO which makes the transient vocabulary also one of the resident ones. Then you are free to change the transient vocabulary again. e.g.. This means search FORTH first then search MY-VOC. The word ALSO is misleading. You might think it is operating on the following word, but it is not, but you can read it as if it were. You can add further resident vocabularies in the same way because the old resident vocabularies slide over to make room for the new one. e.g.: MY-VOC ALSO FORTH ALSO EDITOR This means first search EDITOR as the transient vocabulary, then search the first resident library FORTH, then search the second resident vocabulary MY-VOC. You can keep this process up adding resident vocabularies. BBL maintains one transient and four resident vocabularies and one special sticky one called ONLY. If you keep adding more resident libraries the oldest ones fall off the end without comment. Thus you can never have more than four resident vocabularies. How then do you get rid of resident vocabularies? There is a special vocabulary called ONLY. When you execute it, in addition to the normal action of installing itself as the transient CONTEXT vocabulary, it erases the resident vocabulary list and installs itself as both the first and fifth resident vocabulary. Then you can only use words defined in the ONLY vocabulary. Thus you had better have words like FORTH defined in ONLY or you would be stuck in ONLY forever. To set up a new list of resident vocabularies you do something like this: ONLY MY-VOC ALSO FORTH ALSO EDITOR \BBL\BBL.DOC -11- last updated 1986 October 14 21:30 BBL Forth Reference This means first search EDITOR as the transient vocabulary, then search the first resident library FORTH, then search the second resident vocabulary MY-VOC, then search the third resident vocabulary ONLY. You need not worry about ONLY sliding off the end of the resident vocabulary list and then losing the ability to change vocabularies because ONLY is special in that it installs itself also in a special fifth slot in the list of resident vocabularies. It sticks there and is never shoved out by adding new resident vocabularies with ALSO. Note that having duplicates in the list of resident libraries may slow the search process down slightly, but it will never hurt. I considered teaching BBL to scan the resident list to prune out duplicates, but this would confuse programs that expect resident libraries to fall off the end in a simple-minded way. The Forth-83 standard recommends having only three resident vocabularies. BBL has four. You can find out the names of all possible vocabularies with VOC-LIST and the names of all vocabularies currently being searched with ORDER. To get a list of all the words in the transient CONTEXT vocabulary use WORDS. Finally you can use the verb SEAL to lock your users into some subset of the vocabularies. SEAL will go through your list of resident libraries and remove all references to ONLY -- even the fifth special sticky one. This effectively locks the user into the current set of vocabularies by turning off the words ALSO and ONLY. Before you create a new vocabulary make sure the variable VOC-SIZE contains a reasonable number of bytes to allocate to hold all the nfas that will ever be placed into that dictionary. Instead of driving yourself crazy trying to compute how big it should be, make it too big, then compile, then see how much room is left by setting the CURRENT vocabulary with MY-VOC DEFINITIONS then comparing HEREV and BIGGEST-HEREV. Then the next time you compile you can shrink VOC-SIZE just prior to defining the vocabulary. Be careful with a newly created vocabulary. If you have no resident vocabularies set up and then use the name of your newly created vocabulary to make it the CONTEXT, you will get an error because no words at all exist yet in the new vocabulary. ABORT does a built-in FORTH, so your system will not hang permanently. Newly created vocabularies are not usually immediate, unless of course you make them immediate. The builtin vocabularies FORTH and ONLY are not immediate. In Forth-83 vocabularies are usually not immediate. Thus you must say things like : X [ FORTH ] I ; where you would have said : X FORTH I ; in Forth-79. \BBL\BBL.DOC -12- last updated 1986 October 14 21:30 BBL Forth Reference c.f. VOCABULARY CURRENT CONTEXT ONLY ALSO DEFINITIONS SEAL ORDER WORDS VOC-LIST VOC-SIZE REBUILD-VOC FOR-EACH-VOC VOC-LINK Dictionary Structure BBL's dictionary structure is very complex. The best way to fully understand it is to read the source listings and in particular the documentation in BBLDOC.ASM. It bares almost no resemblance to the simple FIG Forth dictionary implementation described in the text books. However you might do well to understand the FIG Forth model before leaping into the intricacies of BBL. The Forth-83 standard says the applications programmer is not allowed to examine or modify the dictionary except through standard words such as CREATE and ALLOT. In theory you are not supposed to have any understanding of how the dictionary is organized. However I cannot imagine anyone using CREATE and ALLOT correctly without having some model in his or her mind about how the dictionary is organized -- even if the model were incorrect in minor details. A definition has four parts: the cfa, nfa, pfa and lfa. These are abbreviations for code field address, name field address, parameter field address and link field address. In Forth-83 there are no verbs named CFA PFA NFA and LFA as there used to be in Forth-79. You can use the words >BODY >NAME >LINK BODY> NAME> LINK> N>LINK L>NAME and LINK@ to convert between the different addresses. In addition you can use LATEST-NFA and PREV-NFA or EARLIEST-NFA and NEXT-NFA to get at the previously compiled nfa in the same vocabulary as some other word -- regardless of hashing thread. Note that the cfa nfa and pfa are not stored contiguously as they are in the FIG Forth model. There are four separate blocks of memory. All the cfas go in the first cfa or CODE block. The cfa block is always under 64K. All the pfas in the second pfa or TOKENS block. There is no limit on the size of the pfa block, though you need to configure BBL to control the actual size. All the nfas and lfas go in the third nfa or VOCREG block. The nfa block is broken into sub- blocks of under 64K -- one per vocabulary. The fourth block is called the stack segment where the data and return stacks are kept along with the screen buffers for cached disk i/o. This stack segment is also limited to 64K. The most important of the four dictionary addresses is the CFA. ['] and ' provide the cfa. EXECUTE wants the CFA. The CFA is the address in the cfa segment (lowest 64K of the program) where a tiny piece of assembler code is to kick off the execution of a word. Even high level words have a tiny piece of assembler to kick them off. All words have a CFA. Because all cfas are in the low 64K, the segment portion of the address is always equal the the CS: register -- the paragraph base address where the program is loaded. CFAs are NOT canonical. Most Forth implementations are set up so that the cfa \BBL\BBL.DOC -13- last updated 1986 October 14 21:30 BBL Forth Reference points to a word containing the address of a tiny piece of assembler code to kick off the execution of a word. BBL is more direct. The cfa points directly to the assembler code. This is 50% of the secret of BBL's speed. The next most important is the NFA. The name of the word spelled out in ASCII is stored in a separate vocabulary segment preceded by a special byte that packs into it the length and some bit flags to control the IMMEDIATE and SMUDGE features. Because BBL has separable headers, the nfa is needed only at compile time. It may or may not be thrown away at execute time. The next most important is the PFA. For high level definitions, the compiled code consists of a list of 16-bit tokens. The first of these is stored at the pfa. The 16-bit tokens represent the offsets of the cfas of the words that make up the definition. For Variables, the value of the variable is stored in some bytes Allotted at the pfa. The bulk of the dictionary (typically about 200K) forms the pfa part of the dictionary. Primitive words (written in assembler) and CONSTANTs do NOT have pfas. This is an unusual feature of BBL. If for example you were to were to attempt: 4 CONSTANT FOUR ' FOUR >BODY @ you would just get junk. The next most important is the LFA. The words in the dictionary are kept on threads so that the dictionary can be rapidly searched. The lfa points to the nfa of the previous word on the same thread. BBL used a hashed dictionary with multiple threads. Because of this, in practice the threads are very short -- usually containing only one word. In the general case there is no predecessor -- and to save space there is no lfa either. The presence of the lfa is controlled by a bit in the lead byte at the nfa. Thus most of the time the lfa does not even exist so words such as N>LINK >LINK will just return junk. Even when the link field exists it is only 16-bits long giving only a relative offset within the nfa segment. This you must manipulate it with LINK@ instead of @. WARNING about Comparing Addresses WATCH OUT -- COMPARING ADDRESSES IS THE MOST COMMON PLACE ELUSIVE BUGS CREEP INTO BBL PROGRAMS. There are two types of addresses absolute machine Segment:offset and relative -- signed 32 bit offsets from the place where the program is loaded. To compare absolute addresses you must arrange that both addresses have the same segment portion, then use unsigned compares such as U< or U<=. If you erroneously use signed compares, your program will fail if the addresses are above the 512K mark. Cfas and Nfas can be compared without converting to relative, but in general pfas cannot. Addresses within a control block compiled under a single \BBL\BBL.DOC -14- last updated 1986 October 14 21:30 BBL Forth Reference CREATE will all have the same segment because the segment part of HERE is usually changed only by CREATE. ALLOT does not change the segment part of HERE unless it absolutely has to i.e. when more than 64K worth of ALLOTs are done between CREATEs. If the addresses do not have the same segment portion, you must convert them both to relative addresses with >REL. Then the relative addresses must be compared with signed compares e.g. < or <=. If you erroneously use unsigned compares, your program will fail for negative relative addresses below the point where your program is loaded. Pfas nearly always must be converted to relative before comparing. c.f. addr caddr raddr BBL Forth Words **!** words that begin with ! ! ( 32b-value address -- ) store value at address. Stores 4 bytes signed or unsigned value. Value has the MSW on the top of the stack, but the value is stored with the LSW first in memory. The address is seg:offset -- not necessarily canonical. The address must cover all four bytes. There are no alignment restrictions, but if the address is even, the code will run faster. Forth programmers pronounce this "Store". Abundance programmers pronounce it "Bang", but they rarely use it, preferring "TO" instead. c.f. 0! ON OFF C! W! T! 2! !CSP ( -- ) Not normally used by programmers. Save the data stack depth at the start of a colon definition. This is used by Colon to make sure Colon-SemiColons are properly paired. Forth programmers pronounce it "Store c s p" \BBL\BBL.DOC -15- last updated 1986 October 14 21:30 BBL Forth Reference **"** words that begin with " **#** words that begin with # # ( +d1 -- +d2 ) Used to convert numbers from internal form to displayable ASCII. The remainder of +d1 divided by the value of BASE is converted to an ASCII character and appended to the output string toward lower memory addresses. Pictured numeric output conversion works from right to left -- which means formatting characters such as # must be written in reverse order from the way the final result looks. +d2 is the quotient and is maintained for further processing. Note that there is no equivalent for # that works on single precision numbers. You must convert to double precision before using the output formatting features. Typically used between <# and #> c.f. <# #S HOLD SIGN #> pronounced "sharp" #> ( +d -- addr +len ) Pictured numeric output conversion is ended. addr is the address of the resulting output string -- just below PAD where the string has been built. +len is the number of characters in the output string. addr and +len together are suitable for TYPE. c.f. <# # #S HOLD SIGN pronounced "sharp-greater" #S ( +d -- 0.0 ) +d is converted appending each resultant character onto the pictured numeric output string until the quotient (see: # ) is zero. A single zero is added to the output string if the number was initially zero. Typically used between <# and #> . c.f. <# # HOLD SIGN #> pronounced "sharp-s" #TIB ( -- addr ) A variable containing the number of bytes {0..132} in the TIB (text input buffer) right now -- not the maximum capacity of the TIB, not the bytes remaining in the TIB to be interpreted, not the address of the TIB. The text in the TIB is parsed by WORD when BLK is zero. Typically used #TIB @ to get number of chars in the TIB. Because a null hex 00 character marks the current end of the TIB, #TIB is not needed by the BBL internals to ensure parsing does not run off the end of the TIB. c.f. TIB STREAM WORD pronounced "number t i b" \BBL\BBL.DOC -16- last updated 1986 October 14 21:30 BBL Forth Reference **$** words that begin with $ **%** words that begin with % **&** words that begin with & **'** words that begin with ' ' ( -- cfa-addr ) Used in the form: ' <name> addr is the compilation address (cfa) of <name>. An error condition exists if <name> is not found in the currently active search order. Nearly always you should use ['] instead. The only times you use ' are if you are outside a colon definition, or if you are writing your own variant of ['] where the name of the word to be looked up will be parsed later. The segment portion of the address returned is always equal to CS:. Warning! in Forth79 tick was STATE-smart and returned the pfa instead of the cfa. c.f. ['] EXECUTE pronounced "tick" 'EMIT ( -- addr ) a variable used to hold the cfa of the current EMIT routine. CONSOLE vectors in SEMIT to emit to the screen and PRINTER vectors in PEMIT to emit to the printer. CONSOLE does ['] SEMIT 'EMIT ! to redirect EMIT to the screen. EMIT does 'EMIT @ EXECUTE to emit a character with the currently vectored EMIT routine. If you change the value of 'EMIT you will usually also want to change 'TYPE. If you write your own EMIT routine, you may find GTYPE useful as the corresponding TYPE routine to use for 'EMIT. c.f. EMIT CONSOLE PRINTER SEMIT PEMIT TYPE 'TYPE GTYPE STYPE PTYPE \BBL\BBL.DOC -17- last updated 1986 October 14 21:30 BBL Forth Reference 'TYPE ( -- addr ) a variable used to hold the cfa of the current TYPE routine. CONSOLE vectors in STYPE to emit to the screen and PRINTER vectors in PTYPE to emit to the printer. CONSOLE does ['] STYPE 'TYPE ! to redirect TYPE to the screen. TYPE does 'TYPE @ EXECUTE to display a string with the currently vectored TYPE routine. If you change the value of 'TYPE you will usually also want to change 'EMIT. If you write your own EMIT routine, you may find GTYPE useful as the corresponding TYPE routine to use for 'TYPE. c.f. TYPE CONSOLE PRINTER GTYPE STYPE PTYPE EMIT SEMIT PEMIT **(** words that begin with ( ( ( -- ) ( -- ) (compiling) IMMEDIATE Comment initiator used in the form: ( Just Stuff) ( .. ) are comment delimiters. The characters Just Stuff, delimited by ) (closing parenthesis), are considered comments. Comments are not otherwise processed. The blank following ( is necessary, and not part of Just Stuff. ( may be freely used while interpreting or compiling. The number of characters in Just Stuff may be from zero to the number of characters remaining in the input stream up to the closing parenthesis. By convention, ) is usually preceded by a space, however this is not necessary. Does NOT ensure there is a pair, and cannot handle any paired () inside the comment. c.f. \ ;S (ABORT") ( -- : issue message and abort ) Not normally used by programmers. DOES NOT EXPECT A FLAG. Used, but NOT compiled by, (?ABORT). ABORT" compiles as token-("?ABORT) 1-byte-length string poss- even-pad-byte. cf. ABORT" (?ABORT") (AS) ( ' YYY ' XXX AS -- ) executing ( ['] YYY ['] XXX AS -- ) compiling (AS) patches the cfa XXX to jump to the cfa at YYY. This effectively turns XXX into an ALIAS for YYY. Usually XXX is defined with DEFER XXX, but XXX can be any existing word. Watch out if XXX is an ALIAS already, since the cfa is patched, both the ALIAS and the orginal word will be effectively turned into ALIASes for YYY. See the discussion under DEFER. c.f. AS DEFER PERFORM EXECUTE ' ['] LOGO \BBL\BBL.DOC -18- last updated 1986 October 14 21:30 BBL Forth Reference (+LOOP) ( increment -- ) Not normally used by programmers. Adds DO loop increment to I and loops back if I < N, but if the increment is negative, loops back if I >= N. +LOOP compiles as token-(LOOP) followed by a 16-bit BRANCH- style byte offset back to the start of the loop after the leave-offset following the (DO) or (?DO). c.f. DO ?DO LEAVE LOOP +LOOP (DO) (?DO) (LOOP) (LEAVE) (.") ( -- : types the inline string ) Not normally used by programmers. ." compiles as (.")- token 1-byte-count the-string even-pad-byte. c.f. ." .( (;CODE) ( -- ) Not normally used by programmers. Makes cfa of LATEST word point to asm code pointed to by token after (;CODE) ) ;CODE compiles as token-(;CODE) token-start- asm-code. (;CODE) is quite unlike the usual FORTH (;CODE) that redirects LATEST to the code following (;CODE). There is no code following (;CODE). The code is in an entirely different segment at HEREC. ;CODE executes when a defining word is defined. (;CODE) executes later when a word is defined using the defining word. DOES> also compiles as (;CODE). c.f. ;CODE DOES> (?ABORT") ( flag-- ) Not normally used by programmers. If the flag is true, issue message and abort. The flag convention is opposite to Abundance. True means BAD here. ABORT" xxx" compiles as token-("?ABORT) 1-byte-length string poss-even-pad-byte. cf. ABORT" (ABORT") ABORT (?DO) ( n1 n2 -- ) Not normally used by programmers. Compiled by ?DO to start a loop. If n1 = n2 bypass the loop entirely. Watch out! if n2 > n1 the loop will run for a long long time unless you are using -n +LOOP. ?DO compiles as token-(?DO) followed by a BRANCH style leave-offset to just past (LOOP)'s offset. (?DO) pushes 3 values onto the return stack. Note that most Forth 79 implementations push 2 values. The deepest value is an address for Leave, the next deepest is a modified value for N and the top of the return stack has a modified value for I. If you wish to understand how or why "I" is modified, examine the BBL compiler listings. c.f. DO ?DO LEAVE LOOP +LOOP (DO) (LOOP) (+LOOP) (LEAVE) \BBL\BBL.DOC -19- last updated 1986 October 14 21:30 BBL Forth Reference (A") ( -- addr len : inline string literals ) Not normally used by programmers. A" xxxx" inline string literal compiles as token-(A") 1-byte-len the- string poss-pad-byte. At execution time pushes the address and length of the string to the data stack (CREATE) ( -- : does most of the work of creating a header for CREATE ) Not normally used by programmers. (DO) ( N I -- : starts a loop) Not normally used by programmers. Watch out! I must be <= N or this will loop for a very very long time. DO compiles as token-(DO) followed by BRANCH style leave- offset to just past (LOOP)'s offset. Pushes 3 values onto the return stack. Note that most Forth 79 implementations push 2 values. The deepest value is an address for Leave, the next deepest is a modified value for N and the top of the return stack has a modified value for I. c.f. DO ?DO LEAVE LOOP +LOOP (LOOP) (+LOOP) (LEAVE) (FIND) ( counted-string-to-find hash# vocab-region -- ) Not normally used by programmers. Used by FIND to look up a word in a given vocabulary. (FIND) presumes counted-string-to-find is counted string with no excess bits in the count field e.g. Immediate, HasLink, or Smudged bits. (FIND) presumes all dictionary entries and the counted string have length 1..31. hash# is from HASH -- not the result after masking to thread #. NOTE (FIND) is NOT the same as (FIND) or -FIND of Forth 79. The counted string to find will usually be at HEREB, but (FIND) does not insist on it. c.f. FIND ' ['] (LEAVE) ( - : leaves loop immediately ) Not normally used by programmers. LEAVE compiles as token-(LEAVE). It is not followed by an offset. (LEAVE) finds out where the end of the loop is by looking deep in the return stack for an address pushed there by (DO) or (?DO) c.f. DO ?DO LEAVE LOOP +LOOP (DO) (?DO) (LOOP) (LINE) ( line# scr# --- addr len : line 0..15 of given screen ) Used by words such as LIST to consider a screen as 16 lines numbered 0..15 of 64-character lines. Uses BLOCK. \BBL\BBL.DOC -20- last updated 1986 October 14 21:30 BBL Forth Reference (LOOP) ( -- ) Not normally used by programmers. adds 1 to I and loops back if I < N. LOOP compiles as token-(LOOP) followed by a 16-bit BRANCH style byte offset back to the start of the loop after the offset following the (DO) or (?DO). c.f. DO ?DO LEAVE LOOP +LOOP (DO) (?DO) (+LOOP) (LEAVE) **)** words that begin with ) ) FORTH comment terminator. ***** words that begin with * * ( n1 * n2 -- n3 ) 32- bit multiply multiplies n1 by n2 leaving the result n3. Works with either signed or unsigned quantities. 12 2 * -- 24 -12 2 * -- -24 12 -2 * -- -24 -12 -2 * -- 24 Overflow is ignored; only the least significant 32 bits of the result are kept. c.f. multiplication Q* */ */MOD 2* 4* 8* 10* 16* 64* 256* SHIFT pronounced "times" in Forth "star" in Abundance. */ ( n1 n2 n3 -- n4 : all signed ) ( n1*n2 / n3 -- quot-n4 ) n1 is first multiplied by n2 producing an intermediate 64-bit result. n4 is the floor of the quotient of the intermediate 64-bit result divided by the divisor n3. The product of n1 times n2 is maintained as an intermediate 64-bit result for greater precision than the otherwise equivalent sequence: n1 n2 * n3 /. */ is very similar to */MOD except */ throws away the remainder. There is no unsigned version of this operator. c.f. division, */MOD pronounced "times-divide"in Forth "star-slash" in Abundance. \BBL\BBL.DOC -21- last updated 1986 October 14 21:30 BBL Forth Reference */MOD ( n1 n2 n3 -- n4 n5 : all signed ) ( n1*n2 / n3 -- rem-n4 quot-n5 ) Uses signed floored division. Remainder has same sign as n3 n1 is first multiplied by n2 producing an intermediate 64-bit result. n4 is the remainder and n5 is the floor of the quotient of the intermediate 64-bit result divided by the divisor n3. A 64-bit intermediate product is used for */. n4 has the same sign as n3 or is zero. Very similar to */ except */MOD provides the remainder as well as the quotient. c.f. division, */ pronounced "star-slash-mod" **+** words that begin with + + ( n1 n2 -- n3 ) Adds n1 and n2 leaving the result n3. Works with either signed or unsigned quantities. 12 2 + -- 14 -12 2 + -- -10 12 -2 + -- 10 -12 -2 + -- -14 Overflow is ignored; only the least significant 32 bits of the result are kept. c.f. +! 1+ 2+ 4+ D+ +LOOP +! ( N ADDR -- : adds n to memory ) add value to contents of address. Value is MSW on top of data stack, LSW first in memory. Address is seg:offset -- not necessarily canonical c.f. + 1+ 2+ 4+ D+ +LOOP pronounced "plus-bang" \BBL\BBL.DOC -22- last updated 1986 October 14 21:30 BBL Forth Reference +LOOP ( increment -- ) executing ( backaddr-1 backaddr-2 3 -- ) (compiling) Used in the form: 10 0 DO ... 2 +LOOP I = 0 2 4 6 8 0 10 DO ... -2 +LOOP I = 10 8 6 4 2 0 Used in loops that run down instead of up, or which run up by increments other than one. The increment (positive or negative) is added to the loop index. If the new index was incremented across the boundary between limit-1 and limit then the loop is terminated and loop control parameters are discarded. In other words loops back if I < N if the increment is positive and loops back if I >= N if the increment is negative. When the loop is not terminated, execution continues to just after the corresponding DO . +LOOP compiles as (+LOOP) token followed by a BRANCH style offset back to the token after the offset after the (DO). c.f. DO ?DO (DO) (?DO) LOOP (LOOP) (+LOOP) pronounced "plus-loop" +WLIT ( -- value ) Not normally used by programmers. LITERAL compiles as +WLIT token followed by a 16-bit unsigned positive literal.to handle in-line literals in the range 0 .. 0FFFF. **,** words that begin with , , ( 32b -- ) ALLOT space for 32b then store 32b at HERE 4- . pronounced "comma". This is used to compile numbers into the PFA part of the dictionary. This is the most commonly used part of the dictionary. **-** words that begin with - - ( n1 n2 -- n3 ) Subtracts n2 from n1 leaving the result n3. Works with either signed or unsigned quantities. 12 2 - -- 10 -12 2 - -- -14 12 -2 - -- 14 -12 -2 - -- -10 Overflow is ignored; only the least significant 32 bits of the result are kept. Do not confuse with unary NEGATE. Note that SWAP- works faster than -. c.f. 1- 2- D- NEGATE ?NEGATE SWAP- DNEGATE ?DNEGATE pronounced "minus" \BBL\BBL.DOC -23- last updated 1986 October 14 21:30 BBL Forth Reference -1 ( -- -1 ) c.f. ON -LEADING ( addr1 +n1 -- addr2 +n2) Trims off any leading blanks from a string. The length length may also be 0 or 1, but not negative. The address and character count +n1 of a text string beginning at addr1 is adjusted to exclude trailing spaces. If +n1 is zero, then +n2 is also zero. If the entire string consists of spaces, then +n2 is zero. The length n1 must be under 64K and the last character of the string must be covered by Seg of addr. Addr need not be canonical. pronounced "dash-leading or minus-leading" -ROT ( a b c -- c a b ) Reveres rotate. Equivalent to but faster than ROT ROT. rotates the top number on the stack to the third stack position. Constructions of the form >R ... R> can often be handled more efficienly with -ROT. c.f. ROT TUCK 2ROT -TRAILING ( addr +n1 -- addr +n2) Trims off any trailing blanks from a string. The length length may also be 0 or 1, but not negative. The character count +n1 of a text string beginning at addr is adjusted to exclude trailing spaces. If +n1 is zero, then +n2 is also zero. If the entire string consists of spaces, then +n2 is zero. The length n1 must be under 64K and the last character of the string must be covered by Seg of addr. Addr need not be canonical. pronounced "dash-trailing or minus-trailing" -WLIT ( -- value : inline negative constants 0FFFF0000 .. 0FFFFFFFFh ) Not normally used by programmers. LITERAL compiles as WLIT-token followed by a 16-bit unsigned negative literal to handle negative in-line constants in the range -10000h .. -1. Note that the sign bit of the 16b literal may be on or off, but it is always sign extended as a negative quantity. \BBL\BBL.DOC -24- last updated 1986 October 14 21:30 BBL Forth Reference **.** words that begin with . . ( n -- ) Destructively types the value of the signed number on the top of the data stack. The absolute value of n is displayed in a free field format with a leading minus sign if n is negative followed by a space. Uses the current BASE. If you always want a decimal result use .D c.f. .S U. .R .D .D .B pronounced "dot" ." ( -- ) ( -- ) (compiling) Used to TYPE string literals. Used in the form: ." My message" Only used inside colon definitions. Outside them, use .( My message) instead. Later execution will display the characters My message up to but not including the delimiting (close-quote). The blank following ." is necessary and not part of My message. A blank space before the closing " will be considered a part of the string. Compiles as (.")-token 1-byte-count the-string even-pad-byte Watch out in Forth 79 ." was STATE-smart. c.f. .( pronounced "dot-quote" .( ( -- ) ( -- ) (compiling) Used to type string literals. Used in the form: .( My message) Normally used only used outside colon definitions. Inside them, use ." My message" instead. The characters My message up to but not including the delimiting (closing parenthesis) are displayed. The blank following .( is necessary and not a part of My Message. A blank space before the closing ) will be considered a part of the string. The BBL implementation temporarily builds the string at HEREB. c.f. ." pronounced "dot-paren" .B ( u -- ) types top of data stack in unsigned binary This format is useful for debugging because the binary digits are broken into groups like this 1111_1111_1111_1111:1111_1111_1111_1111. Does not examine or change the BASE. Followed by a space. c.f. .D .D . \BBL\BBL.DOC -25- last updated 1986 October 14 21:30 BBL Forth Reference .BASE ( -- ) Displays the BASE in English. Useful in debugging to find out what the value of BASE is. Prints out the word Hex or Binary or Decimal or Base 12. If you simply did BASE @ . you would always just see 10 no matter what the base was because the conversion is always done in the current base -- not too informative. .S uses .BASE. c.f. BASE .S .D ( n -- ) type value in signed DECIMAL. Does not examine or change the BASE. Followed by a space; c.f. .B .H . .H ( u -- ) type value in unsigned HEX with colon separator between the MSW and LSW. Useful in debugging to display addresses. Does not examine or change the BASE. Followed by a space. c.f. .D .B . .ID ( NFA -- ) types name of word at the given cfa. ALIAS for .NAME c.f. .INFO .NAME .INFO ( nfa -- ) displays the cfa pfa nfa and name of a word whose nfa is given. There is no builtin CR. c.f. .INFO-HEAD .NAME .INFO-HEAD ( nfa -- ) displays the heading suitable for labelling the results of .INFO. There is no builtin CR. c.f. .INFO .NAME .LINE ( LINE SCR -- ) types line 0..15 of given screen. Useful in writing screen editors or generating error messages. .NAME ( NFA -- ) types name of word at the given cfa. In older Forths was sometimes called .ID c.f. .INFO \BBL\BBL.DOC -26- last updated 1986 October 14 21:30 BBL Forth Reference .R ( n1 +n2 -- ) Print a signed number n in a fixed width field +n2 wide. n1 is converted using BASE and then displayed right aligned in a field +n2 characters wide. A leading minus sign is displayed if n1 is negative. If the number of characters required to display n1 is greater than +n2, the field is simply widened without comment. The Forth 83 standard considers this an error condition. c.f. . .S pronounced "dot r" .S ( -- ) dumps the data stack non destructively. Used in debugging. Displays the stack in both Hex and Decimal. Synonym for .s .s ( -- ) dumps the data stack non destructively. Used in debugging. Displays the stack in both Hex and Decimal. ALIAS for .S .WORD ( -- : types word at HEREB ) This displays the most most recently parsed word. This is useful in error messages to pinpoint what word was being parsed at the time of the error. The word is enclosed in quotes to make it clearer if any embedded control characters are part of the word. **/** words that begin with / / ( num-32 denom-32 -- quot-32 : signed floored division ) divides n1 by n2 leaving n3 using signed integer division with a floored result Use /MOD if you want both the remainder and quotient.. MOD gets just the remainder. 2/ divided rapidly by 2 by using an arithmetic shift. Note that the unsigned version U/ is faster than /. c.f. division 2/ Q/ /MOD MOD U/. pronounced "slash" /MOD ( num-32 denom-32 -- rem-32 quot-32 : signed floored division ) Remainder has same sign as divisor. MOD gets just the remainder. / gets just the quotient. The unsigned version U/MOD is faster than /MOD. c.f. division, / MOD U/MOD Q/MOD pronounced "slash-mod" \BBL\BBL.DOC -27- last updated 1986 October 14 21:30 BBL Forth Reference **0** words that begin with 0 0 ( -- 0 ) 0! ( ADDR -- ) Stores 32 bit zero at addr. This is equivalent to 0 SWAP !, but it executes much more quickly. Also called OFF. c.f. OFF ON ! ERASE 0. ( -- 0. : 64b double precision ) 0< ( n -- flag ) flag is true if n is less than zero (negative) using signed compares. Note that 0< NOT is equivalent to but slower than 0>=. c.f. 0<= 0> 0>= 0= D0= 0<> NOT pronounced "zero-less" 0<= ( n -- flag ) true if n is less than or equal to 0. Note that 0<= NOT is equivalent to but slower than 0>. c.f. 0< 0> 0>= 0= D0= 0<> NOT 0<> ( n -- flag : true if n not equal 0 ) Normally there is no need to use this verb since any non-zero value is considered TRUE anyway. "X @ IF" is a better way to express to "X @ 0<> IF". 0<> is needed if you wish to combine flags with AND e.g. X @ 0<> Y @ 0<> AND, but it in not usually needed if you wish to combine flags with OR because "X @ Y @ OR IF" is equivalent to "X @ 0<> Y @ 0<> OR IF". 0<> NOT is equivalent to but slower than 0=. c.f. 0< 0<= 0> 0>= 0= D0= NOT 0= ( n -- flag ) flag is true if n is zero. This is not quite the same as "NOT". 0= always leaves 0 or -1 or the data stack. "NOT" will leave 0 or -1 if it operates on a canonical flag, but it will leave the one's complement of the value if it is anything else. c.f. 0< 0<= 0> 0>= D0= 0<> NOT pronounced "zero-equals" 0> ( n -- flag ) flag is true if n is greater than zero using signed compares. Note that 0> NOT is equivalent but slower than 0<=. c.f. 0< 0<= 0>= 0= D0= 0<> NOT pronounced "zero-greater" \BBL\BBL.DOC -28- last updated 1986 October 14 21:30 BBL Forth Reference 0>= ( n -- flag ) flag true if n is greater than or equal to 0 using signed compares. Note that 0>= NOT is equivalent to but slower than 0<. c.f. 0< 0<= 0> 0= D0= 0<> NOT **1** words that begin with 1 1 ( -- 1 ) 1+ ( n1 -- n2 ) Increment by 1. n2 is the result of adding one to n1 according to the operation of +. Do not confuse with 1+! which adds one to memory. 1+ is equivalent to 1 +, but executes more quickly pronounced "one-plus" 1- ( n1 -- n2 ) Decrement by 1. n2 is the result of subtracting one to from according to the operation of -. Do not confuse with -1 which simply puts a -1 on the data stack. 1- is equivalent to 1 -, but executes more quickly pronounced "one-minus" 10 ( -- 10 in decimal mode ) ( -- 16 in hex mode ) this is an in-line literal word not a built-in word c.f. TEN SIXTEEN 10* ( n1 -- n2 ) 10* multiplies by decimal 10. n2 is the result of 2* + 8* . This works on both signed and unsigned numbers. 10* is equivalent to 10 * c.f. * */ */MOD 2* 4* 8* 10* 16* 64* 256* SHIFT pronounced "ten-star" in Abundance. 16* ( n1 -- n2 ) 16* multiplies by decimal 16 = 2**4 = LEFT SHIFT 4. Works on both signed and unsigned numbers. c.f. multiplication * 2* 4* 8* 10* 64* 256* SHIFT **2** words that begin with 2 2 ( -- 2 ) \BBL\BBL.DOC -29- last updated 1986 October 14 21:30 BBL Forth Reference 2! ( D-value address -- : store value at address ) Stores 8 bytes = 64b Value is MSW on top of data stack, LSW first in memory. Address is seg:offset -- not necessarily canonical Does NOT mean 2 !, pronounced " two-bang" c.f. C! W! T! ! 2* ( n1 -- n2 ) n2 is the result of shifting n1 left one bit. This works on both signed and unsigned numbers. 2* is equivalent to 2 * . A zero is shifted into the vacated bit position. Note that 2* is NOT double precision multiplication. c.f. multiplication * */ */MOD 4* 8* 10* 16* 64* 256* SHIFT pronounced "two-star" in Abundance. 2+ ( n1 -- n2 ) n2 is the result of adding two to n1 according to the operation of + . 2+ is equivalent to 2 + . Note that 2+ is NOT double precision addition. c.f. + 1+ 4+ D+ pronounced "two-plus" 2- ( n1 -- n2 ) n2 is the result of subtracting two from n1 according to the operation of - . 2- is equivalent to 2 - . Note that 2- is NOT double precision subtraction. c.f. - 1- D- NEGATE pronounced "two-minus" 2/ ( n -- n/2 ) Very quick signed divide by 2 using a shift. n2 is the result of arithmetically shifting n1 right one bit. The sign is included in the shift and remains unchanged. Equivalent to 2/ Note that 2/ is NOT double precision division. -1 SHIFT would handle unsigned division by 2. c.f. division / SHIFT D2/ pronounced "two-slash" 256* ( n1 -- n2 ) 256* multiplies by decimal 256 = 2**8 = LEFT SHIFT 8. Works on both signed and unsigned numbers. c.f. multiplication * 2* 4* 8* 10* 16* 64* SHIFT \BBL\BBL.DOC -30- last updated 1986 October 14 21:30 BBL Forth Reference 2@ ( addr -- 64b ) fetches the 64-bit value stored at addr. The 8-byte value is stored in ram LSB first, but with the most significant 32 bits on the top of the data stack. The address need not be canonical. c.f. 2! C@ W@ UW@ T@ UT@ @ pronounced "two-fetch" 2CONSTANT ( 64b -- ) A defining word executed in the form: 64b 2CONSTANT <name> Creates a dictionary entry for <name> so that when <name> is later executed, 64b will be left on the data stack. pronounced "two-constant" 2DROP ( 64b -- ) 64b is removed from the data stack -- i.e. two stack entries -- equivalent to DROP DROP but executes more quickly. c.f. DROP R2DROP pronounced "two-drop" 2DUP ( 64b -- 64b 64b ) Duplicate 64b. An alternative way of looking at it is that it duplicates the top pair on the data stack, ( n1 n2 -- n1 n2 n1 n2 ) pronounced "two-dupe" 2OVER ( 64b1 642 -- 64b1 64b2 64b3 ) 64b3 is a copy of 64b1. This is OVER for doublewords. pronounced "two-over" 2ROT ( 64b1 64b2 64b3 -- 64b2 64b3 64b1 ) The top three double numbers on the data stack are rotated, bringing the third double number to the top of the stack. c.f. ROT -ROT pronounced "two-rote" 2SWAP ( 64b1 642 -- 64b2 64b1 ) The top two double numbers are exchanged. Another way of looking at this is ( n1 n2 n3 n4 -- n3 n4 n1 n2 ) pronounced "two-swap" \BBL\BBL.DOC -31- last updated 1986 October 14 21:30 BBL Forth Reference 2VARIABLE ( -- ) A defining word executed in the form: 2VARIABLE <name> A dictionary entry for <name> is created and eight bytes (64 bits) are ALLOTted in its parameter field. This parameter field is to be used for contents of the variable. The application is responsible for initializing the contents of the variable which it creates if a value other than 0 is needed.. When <name> is later executed, the address of its parameter field is placed on the data stack. c.f. VARIABLE pronounced "two-variable" **3** words that begin with 3 3 ( -- 3 ) 3DROP ( N1 N2 N3 -- ) DROP top 3 elements on the data stack. Equivalent to DROP DROP DROP but it executes more quickly. c.f. DROP R3DROP 3DUP ( a b c --- a b c a b c ) duplicates top three items on data stack **4** words that begin with 4 4 ( -- 4 ) 4* ( n1 -- n2 ) n2 is the result of shifting n1 left two bits. This works on both signed and unsigned numbers. 4* is equivalent to 4 * . c.f. multiplication * */ */MOD 2* 8* 10* 16* 64* 256* SHIFT pronounced "four-star" in Abundance. 4+ ( n1 -- n2 ) n2 is the result of adding four to n1 according to the operation of + . 4+ is equivalent to 4 + . c.f. + 1+ 2+ D+ pronounced "four-plus" 4- ( n -- n-4 ) quick subtract of 4. Equivalent to 4-. c.f. - 1- 2- D- \BBL\BBL.DOC -32- last updated 1986 October 14 21:30 BBL Forth Reference 4DROP ( N1 N2 N3 N4 -- ) DROP top 4 elements on the data stack. Equivalent of DROP DROP DROP DROP. Another way of looking at it is ( D1 D2 -- ) c.f. DROP R4DROP **5** words that begin with 5 5 ( -- 5 ) **6** words that begin with 6 6 ( -- 6 ) 64* ( n1 -- n2 ) 64* multiplies by decimal 64 = 2**6 = LEFT SHIFT 6. Works on both signed and unsigned numbers. c.f. multiplication * 2* 4* 8* 10* 16* 256* SHIFT **7** words that begin with 7 7 ( -- 7 ) **8** words that begin with 8 8 ( -- 8 ) 8* ( n1 -- n2 ) 8* multiplies by decimal 8 = 2**3 = LEFT SHIFT 3. Works on both signed and unsigned numbers. c.f. multiplication * 2* 4* 10* 16* 64* 256* SHIFT **9** words that begin with 9 9 ( -- 9 ) \BBL\BBL.DOC -33- last updated 1986 October 14 21:30 BBL Forth Reference **:** words that begin with : : ( -- ) A defining word executed in the form: : <name> ... ; This creates a word definition for a new <name> and compiles it into the dictionary . The newly created word definition for <name> cannot be found in the dictionary until the corresponding ; or ;CODE is successfully processed. The : must always be followed by a space. When the name is later used, it must be spelled exactly the same way including capitalization. Abundance programmers use a word very similar to : called <<<. Everything that applies to : also applies to <<<. c.f. ; **;** words that begin with ; ; ( -- ) Stops compilation of a colon definition, UNSMUDGEs to allow the <name> of this colon definition to be found in the dictionary, sets interpret state and compiles as EXIT. Abundance programmers use a word very similar to ; called >>>. Everything that applies to ; also applies to >>>. c.f. ;CODE (;CODE) \BBL\BBL.DOC -34- last updated 1986 October 14 21:30 BBL Forth Reference ;CODE ( -- ) Used in the form: : <namex> ... CREATE ... ;CODE ... END-CODE Stops compilation, terminates the defining word <namex> and executes ASSEMBLER. When <namex> is executed in the form: <namex> <name> to define the new <name>, the execution address of <name> will contain the address of the code sequence following the ;CODE in <namex>. Execution of any <name> will cause this machine code sequence to be executed. The only way you will ever understand this is to examine the source code in the BBL compiler. See BBLDOC.ASM for an overview. Once you understand this you may consider yourself one of the blessed ones who truly grok Forth. There is a Forth tradition of not explaining this deep mystery. Perhaps people who have slogged to figure it out don't want it to be too easy for those following to join the select club. More likely, it is just too difficult to explain. It is a slippery concept. Even after writing this compiler, I cannot easily remember how it works myself. c.f. CODE (;CODE) DOES> pronounced "semi-colon-code" ;S ( -- ) Exit current procedure, synonym for EXIT. ;S is compiled by ; to make it a little easier to disassemble code. Internal EXITS compile to EXIT, but the final one compiles implied by ; compiles to ;S. ;S is also used to mean ignore the rest of this screen. It turns the rest of the screen into a comment. Forth purists seem to think ;S is a rude word. I am not sure why. c.f. \ ( ) EXIT **<** words that begin with < < ( n1 n2 -- flag ) Flag is true if n1 is less than n2 using signed compares. Note that < NOT is equivalent to but slower than >=. See the warning about comparing addresses. c.f. U< D< <= > U> D> >= = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "less-than" \BBL\BBL.DOC -35- last updated 1986 October 14 21:30 BBL Forth Reference <# ( D1 -- D1 ) Initialize pictured numeric output conversion of internal binary to displayable ASCII. The ASCII text string result is stored in right-to left order just under the PAD with the rightmost char at PAD-1. Note that <# works on double precision numbers. There is no single precision equivalent. c.f. # #S HOLD SIGN #> pronounced "less-sharp" <= ( n1 n2 -- flag ) true if n1 is less than or equal to n2 using signed compares. Note that <= NOT is equivalent to but slower than >. See the warning about comparing addresses. c.f. < U<= D< > U> D> >= = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "less-or-equal" <MARK ( -- addr ) Only used by clever programmers. Marks a back branch. Used at the destination of a backward branch. addr is typically only used by <RESOLVE to compile a branch address. For example the code for DO would contain a <MARK to arrange for LOOP to use <RESOLVE to build a (LOOP) branch back just after the DO. c.f. <RESOLVE >MARK >RESOLVE pronounced "backward-mark" <RESOLVE ( addr -- ) Only used by clever programmers. Resolves a back branch. Used at the source of a backward branch after either BRANCH or ?BRANCH . Compiles a branch address using addr as the destination address. For example the code for DO would contain a <MARK to arrange for LOOP to use <RESOLVE to build a (LOOP) branch back just after the DO. pronounced "backward-resolve" <SCAN ( addr len char -- index of found char, true: if found ) ( addr len char -- false : if not found ) scan string right to left searching for char. The left most char is index 0. If the string is 0 length, the result is always false. The length must be 16 bits unsigned. <SCAN is somewhat like PL/I index function. Returns index = 0 for first and = 1 for 2nd position. Note: 0-based. c.f. SCAN WSCAN SCAN<> \BBL\BBL.DOC -36- last updated 1986 October 14 21:30 BBL Forth Reference **=** words that begin with = = ( n1 n2 -- flag ) flag is true if n1 is equal to n2. works for signed and unsigned. For a logical bit-wise equal compare use XOR NOT. Note than = NOT is equivalent to but slower than <>. See the warning about comparing addresses. c.f. < U< D< <= > U> D> >= = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "equals" **>** words that begin with > > ( n1 n2 -- flag ) Flag is true if n1 is greater than n2 using signed compares. > NOT is equivalent to but slower than <=. See the warning about comparing addresses. c.f. U> < U< D< <= > D> >= = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "greater than" >< ( n1 -- n2 ); n2 is n1 with low 2 bytes swapped, high 2 bytes are undisturbed. Do not >< confuse with <> which means not equal. c.f. W>< <> >= ( n1 n2 -- flag) true if n1 is greater or equal to n2 using signed compares. Note that >= NOT is equivalent to but slower than <. See the warning about comparing addresses. c.f. U>= < D< <= > U> D> >= = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE >BODY ( cfa -- pfa ) converts cfa (code field address) to pfa (parameter field address). Note that primitive words (those written in assembler) do not have a pfa. CONSTANTs do not have pfa's either. c.f. >NAME >LINK BODY> NAME> LINK> N>LINK L>NAME PREV- NFA pronounced "to-body" >DIGIT ( Char base -- N2 true : if valid conversion ) ( Char base -- false : if invalid ) Only least significant 8 bits of C and base are examined. Converts ^ 0 i.e. decimal 48 to binary 0. Converts ^ F to 15. Used by CONVERT and NUMBER. \BBL\BBL.DOC -37- last updated 1986 October 14 21:30 BBL Forth Reference >IN ( -- addr ) A variable which contains the present character offset within the input stream {0..the number of characters in the input stream}. The offset may be either in the TIB or in the screen being interpreted. c.f. WORD pronounced "to-in" >LINK ( cfa -- lfa ) converts cfa (code field address) to the lfa (link field address. The link field must be accessed with LINK@ to get the nfa of the predecessor on the dictionary thread. c.f. >BODY >NAME BODY> NAME> LINK> N>LINK L>NAME PREV- NFA >MARK ( -- addr ) Only used by clever programmers. Marks a forward branch. Used at the source of a forward branch. Typically used after either BRANCH or ?BRANCH . Compiles space in the dictionary for a branch address which will later be resolved by >RESOLVE. For example IF would use >MARK to half build the ?BRANCH address to jump over the code between IF and THEN. THEN would use >RESOLVE to finish building the address to jump just past the THEN. pronounced "forward-mark" >NAME ( cfa -- nfa ) converts cfa (code field address) to nfa (name field address). Use this word sparingly. WARNING THIS WORD IS EXTREMELY SLOW! It works by scanning all nfas in all vocabularies to find a match. If you really need this feature, I suggest capturing the nfa at compile time with LATEST and storing it somewhere near the pfa. c.f. >BODY >LINK BODY> NAME> LINK> N>LINK L>NAME PREV- NFA pronounced "to-name" >R ( 32b -- ) Removes 32b from the data stack and transfers it to the return stack. Must always be paired with R>. This is a very useful word but see the dire warnings on its use under Return Stack. c.f. R> R@ RDROP EXIT pronounced "to-r" \BBL\BBL.DOC -38- last updated 1986 October 14 21:30 BBL Forth Reference >REL ( absolute addr -- relative addr ) converts an absolute Seg:offset address to a relative 32 bit signed number -- the offset of the address from the start of the program. It can be used an any machine address in any segment. However if you use REL> to convert it back, you won't necessarily get the same representation of that address. c.f. >REL >REL> pronounced "to-relative" >REL> ( absolute addr -- canonical addr ) converts an absolute Seg:offset address to a canonical one with the offset in the range 0..15. It really only useful on addresses in the pfa part of the dictionary or on addresses outside the program. It does not cleverly handle addresses in the code segment to make them have a segment equal to CS:. Neither does it handles addresses in the stack segment to make them have a segment equal to SS:. Neither does it handle addresses in the vocabulary segments to make them have segments equal to the start of the vocabulary region. See the warning about comparing addresses. c.f. >REL REL> pronounced "canonize" >RESOLVE ( addr -- ) Only used by clever programmers. Resolves a forward branch. Used at the destination of a forward branch. Calculates the branch address (to the current location in the dictionary) using addr and places this branch address into the space left by >MARK. For example IF would use >MARK to half build the ?BRANCH address to jump over the code between IF and THEN. THEN would use >RESOLVE to finish building the address to jump just past the THEN. pronounced "forward-resolve" **?** words that begin with ? ?BRANCH ( flag -- : compiled by immediate words to conditionally jump) When used in the form: COMPILE ?BRANCH a conditional branch operation is compiled. See BRANCH for further details. When executed, if flag is false the branch is performed as with BRANCH . When flag is true execution continues at the compilation address immediately following the branch address. Followed in dictionary by a signed relative byte offset. It is optimized for the case where the branch is usually not taken. Alias 0BRANCH in older FORTH implementations. pronounced "question-branch" \BBL\BBL.DOC -39- last updated 1986 October 14 21:30 BBL Forth Reference ?BRANCH-USUALLY ( flag -- : compiled by immediate words to conditionally jump) Followed in dictionary by a signed relative byte offset. It is an optimized form of ?BRANCH for the case where the branch is usually taken. Alias 0BRANCH in older FORTH implementations. ?COMP ( -- : ensures compiling ) If you are not compiling (in the middle of a colon definition) BBL aborts with an error message. Used by words such as IF to ensure they are not used outside colon definitions. ?CSP ( -- ) ensures a colon definition starts and ends with same data stack depth by comparing the current stack depth with the one recorded with !CSP. Colon does a !CSP and semicolon does a ?CSP. c.f. !CSP ?DNEGATE ( D1 n2 -- D1 if n2 >=0) ( D1 n2 -- -D1 if n2 < 0) ?DNEGATE is usually used to transfer the sign of n2 to a usually unsigned D1. Note n2 is not normally a canonical flag, but if it is, it means negate D1 if the flag is true, otherwise leave it alone. c.f. NEGATE ?NEGATE DNEGATE ?DO ( n1 n2 -- ) ( -- back-addr1 back-addr2 3 ) (compiling) used in the form ?DO .. LOOP or ?DO .. 2 +LOOP Starts a loop. Like DO except that it has an extra check in it to see if n1 = n2. If they are equal the entire loop is bypassed. Note that if n1 < n2 the loop still attempts to carry on with usually disastrous results! In Abundance the <<<FOR and <<<RUN style loops are used in preference to ?DO. ?DO compiles as a (?DO) token followed by a BRANCH style offset for leave. ?DUP ( 32b -- 32b 32b ) or ( 0 -- 0 ) duplicate 32b if it is non-zero Normally used in the form ?DUP IF ... THEN c.f. DUP 2DUP pronounced "question-dupe" ?EXEC ( -- ) ensures executing. If you are in the middle of compiling a colon definition, it will abort with an error message. Used to ensure words like colon are only used outside colon definitions. \BBL\BBL.DOC -40- last updated 1986 October 14 21:30 BBL Forth Reference ?FOUND ( 0/1/-1 found flag -- ) ensure FIND worked. If the found flag, usually created as a result of FIND, is 0 ?FOUND aborts with an error message. ?LOADING ( -- ) ensure loading. If interpreting the input from the TIB instead of a screen, ?LOADING will abort with an error message. Used by words such as ( to ensure they are only used on screens, not typed in directly. ?NEGATE ( n1 n2 -- n1 if n2 >=0) ( n1 n2 -- -n1 if n2 < 0) ?NEGATE is usually used to transfer the sign of n2 to a usually unsigned n1. Note n2 is not normally a canonical flag, but if it is, it means negate n1 if the flag is true, otherwise leave it alone. c.f. NEGATE DNEGATE ?DNEGATE ?PAIRS ( N1 N2 --- ) ensures conditionals paired by aborting with an error message if n1 is not equal n2. At compile time structured conditionals such as IF put a unique code number on the data stack that is checked for by the matching ending e.g. THEN. Here is a list of the code numbers used by the various structures: BEGIN 1 ... AGAIN BEGIN 1 ... END BEGIN 1 ... flag WHILE 4 ... REPEAT BEGIN 1 ... flag UNTIL flag IF 2 ... THEN flag IF 2 ... ELSE 2 ... THEN n1 n2 DO 3 ... LOOP n1 n2 DO 3 ... +LOOP n1 n2 ?DO 3 ... LOOP n1 n2 ?DO 3 ... +LOOP Note that : ... ; uses !CSP and ?CSP instead of ?PAIRS. ?STACK ( -- ) ensure both stacks are in bounds. ABORTs with a message if the either the data or return stack has underflowed or overflowed. ?TERMINAL ( -- flag ) true if char waiting in keystroke buffer. Does not read or lose the character. Use KEY to get the character. c.f. KEY \BBL\BBL.DOC -41- last updated 1986 October 14 21:30 BBL Forth Reference **@** words that begin with @ @ ( addr -- 32b ) fetches the 32-bit value stored at addr. The 4-byte value is stored in ram LSB first. The address need not be canonical. c.f. ! C@ W@ UW@ T@ UT@ 2@ TOKEN@ PC@ P@ COUNT pronounced "fetch" **A** words that begin with A A" ( A" xxxx" -- addr len ) inline string literal. STATE-smart -- can be used either while compiling or executing. Compiles as (A")- token 1-byte-length the-string poss-pad-byte. ABORT ( -- ) Clears the data stack and performs the function of QUIT. No message is displayed. ABORT clears both the return and data stacks where QUIT just clears the return stack. ABORT also sets FORTH as the CONTEXT vocabulary. This will help you recover from errors where you screw up the transient or resident context search order vocabularies. c.f. ABORT" QUIT ABORT" ( flag -- ) executing ( -- ) compiling Used in the form: flag ABORT" my error message" When later executed, if the flag is true the characters my error message delimited by " (close-quote), are displayed along with the name of the most recently parsed word. Then an ABORT,is performed. If flag is false, the flag is dropped and execution continues. The blank following ABORT" is necessary and not a part of the error message. The flag being true means bad - the opposite of the usual Abundance convention. Compiles as token-("?ABORT) 1-byte-length string poss- even-pad-byte ABS ( n -- u ) u is the absolute value of n. In other words ABS makes n positive. If n is < 0 then the result is -n. If n is greater than 0 then the result is simply n. If n is -232 then ABS cannot work properly as there is no positive equivalent that can be expressed in 32 bits, so in that case the result is unchanged at -232. \BBL\BBL.DOC -42- last updated 1986 October 14 21:30 BBL Forth Reference ADCON ( 32b -- ) A defining word executed in the form: 32b ADCON <name> Creates a dictionary entry for <name> so that when <name> is later executed, 32b will be left on the data stack. The value must be a relocatable absolute address. The names defined with ADCONs have cfas but no pfas as ADCON generates primitive assembler code to push the value of the constant to the data stack. ADCON is just a quick form of CONSTANT used if you are willing to live with the restriction that the value represent an absolute address in the program, rather than outside the program e.g. somewhere in ROM BIOS or DOS. The value may NOT be a relative address. c.f. CONSTANT, QCONSTANT AGAIN Used in the form BEGIN ... AGAIN ( BEGIN back-addr 1 ... AGAIN ) compiling ( BEGIN ... AGAIN ) executing Generates an endless loop. The only way out of it is to use an EXIT inside the loop. Note that in this implementation LEAVE is NOT allowed inside a BEGIN AGAIN loop. ALIAS ( ' X ALIAS Y ) ( ' X ALIAS Y IMMEDIATE) Makes Y a ALIAS for X. No cfa or pfa is created. The nfa of Y points directly to X. If X is IMMEDIATE then normally you would manually make Y immediate as well. This would not happen automatically. X and Y need not be in the same vocabularies. X must be in the CONTEXT search order, and Y will be placed in the CURRENT DEFINITIONS vocabulary. When LOGO mode is used, if X is redefined Y will be also. If you FORGET Y, this will not necessarily FORGET X as well. Note that ALIAS is not immediate. It is normally used outside colon definitions. ' + ALIAS PLUS is faster than : PLUS + ; ' THEN ALIAS ENDIF IMMEDIATE is faster than : ENDIF [COMPILE] THEN ; IMMEDIATE c.f. DEFER AS EXECUTE PERFORM ALLOT ( +w -- ) Allocates w bytes in the pfa dictionary. HERE -- the address of the next available dictionary location is updated accordingly. ALLOT sometimes canonizes HERE. c.f. HERE HEREB , C, ALLOTC ALLOTR ALLOTV \BBL\BBL.DOC -43- last updated 1986 October 14 21:30 BBL Forth Reference ALLOTC ( +w -- ) Not normally used by programmers. Allocates w bytes in the cfa dictionary. HEREC -- the address of the next available dictionary location is updated accordingly. Normally the programmer uses ALLOT instead of ALLOTC. c.f. ALLOT HEREC ALLOTR ( +w -- ) Not normally used by programmers. Allocates w bytes from the region reserved for new vocabulary storage regions. +W must be a multiple of 16 or there will be dire consequences later. HERER -- the address of the next available dictionary location is updated accordingly. Normally the programmer uses ALLOT instead of ALLOTV. When new vocabularies are defined the system automatically uses ALLOTR to reserve a vocabulary storage region of VOC-SIZE @ bytes to hold the nfas of the words to be defined later in the new vocabulary. c.f. ALLOTV HEREV VOC-SIZE ALLOTV ( +w -- ) Not normally used by programmers. Allocates w bytes in the nfa dictionary. HEREV -- the address of the next available dictionary location is updated accordingly. Normally the programmer uses ALLOT instead of ALLOTV c.f. ALLOTV HEREV ALSO ( -- ) Allows you to set up more than one VOCABULARY to be searched. Used in the form: ONLY FORTH ALSO EDITOR ALSO HIDDEN DEFINITIONS This would set up the search to first look in HIDDEN, then in EDITOR then in FORTH, then in ONLY. New definitions would be added to the HIDDEN vocabulary. The transient vocabulary becomes the first vocabulary in the resident portion of the search order. Up to the last three resident vocabularies will also be preserved, in order, forming the resident search order. Note that ALSO need not be immediately preceded or followed by the name of a vocabulary. c.f. ONLY FORTH ORDER WORDS FORGET DEFINITIONS SEAL VOCABULARY \BBL\BBL.DOC -44- last updated 1986 October 14 21:30 BBL Forth Reference AND ( n1 n2 -- n3 ) n3 is the logical-and on all 32 bits. Thus BINARY 0101 0011 AND is equal to 0001 -- if both bits are 1 the result is 1. If either bit is a 0 the result is a 0. Note that b1 NOT b2 NOT AND is better expressed as b1 b2 NOR and b1 NOT b2 NOT OR is better expressed as b1 b2 NAND. If you use canonical flags, then this bit- wise AND has the same meaning as the word "and" in English. In particular if n1 and n2 are canonical flags (0 or -1) then: true true -- true false true -- false true false -- false false false -- false c.f. OR NAND XOR NOT NOR AS ( ' YYY AS XXX ) executing ( ['] YYY AS XXX ) compiling STATE-smart word that patches the cfa XXX to jump to the cfa at YYY. This effectively turns XXX into an ALIAS for YYY. Usually XXX is defined with DEFER XXX, but XXX can be any existing word. Watch out if XXX is an ALIAS already, since the cfa is patched, both the ALIAS and the orginal word will be effectively turned into ALIASes for YYY. See the discussion under DEFER. c.f. (AS) DEFER PERFORM EXECUTE ' ['] LOGO ASCII ( -- ) at compile time ( -- c ) at run time. Used to create character literals. ASCII A compiles the constant 65. At run time, the literal is placed on the stack. ASCII is a synonym for _. A state-smart literal that can be used inside or outside colon definitions. c.f. _ the underscore ASSEMBLER ( -- ) Execution replaces the first vocabulary in the search order with the ASSEMBLER vocabulary. c.f. VOCABULARY \BBL\BBL.DOC -45- last updated 1986 October 14 21:30 BBL Forth Reference **B** words that begin with B BASE ( -- addr ) The address of a variable containing the current numeric conversion radix. {2..72}. For example BINARY is defined as 2 BASE !. When BASE = 16 all numbers will be printed in HEX and all numbers typed in or compiled will be interpreted as HEX. Be very careful to distinguish the between the value of the BASE when a definition is compiled and the value of the BASE when the definition is executed. Words like HEX control the execution time BASE where words like [ HEX ] control the compile time BASE. There is only one variable BASE that is used to control both compile-time and execution time conversions. c.f. .BASE CONVERT <# # #> . .S BEEP ( freq time -- ) Sounds a tone. The frequency is measured in Hertz. The time is measured in hundreds of seconds. e.g. 440 500 BEEP plays middle A for 5 seconds. BEGIN ( -- ) ( -- back-addr 1 ) (compiling) Used in the form BEGIN ... flag UNTIL BEGIN ... flag WHILE ... REPEAT BEGIN ... AGAIN BEGIN marks the start of a word sequence for repetitive execution. A BEGIN-UNTIL loop will be repeated until flag is true. A BEGIN-WHILE-REPEAT loop will be repeated until flag is false. The words after UNTIL or REPEAT will be executed when either loop is finished. The BEGIN ... AGAIN loop runs forever. The only way out would be an EXIT in the loop. Note that in the current implementation, LEAVE cannot be used to terminate a BEGIN style loop. BIGGEST-HERE ( -- ADDR ) last allowed slot in pfa region region. When HERE gets bigger than this we are in deep trouble. The problem may be rectified by configuring a version of BBL with a bigger pfa region with more or bigger segments. c.f. HERE ALLOT \BBL\BBL.DOC -46- last updated 1986 October 14 21:30 BBL Forth Reference BIGGEST-HEREC ( -- ADDR ) last allowed slot in cfa region. When HEREC gets bigger than this we are in deep trouble. The problem may be rectified by configuring a version of BBL with a bigger cfa region. However if the region is already at 64K, all you can do it get rid of assembler code which always goes in the cfa segment by converting it to high level code which always goes in the expandable pfa segment. c.f. HEREC ALLOTC BIGGEST-HEREV ( -- ADDR ) last allowed slot in CURRENT (DEFINITIONS) vocabulary. When HEREV gets bigger than this we are in deep trouble. The problem may be rectified by configuring a version of BBL with a bigger nfa region. In a grossly pathological situations where a single vocabulary takes more than 64K for the names, you may need to split it into two vocabularies. This should never happen. c.f. HEREV BIGGEST-RP@ ( -- addr ) Not normally used by programmers. Used by ?STACK to detect Return stack overflow. Value for RP@ when return stack is full. BIGGEST-SP@ ( -- addr ) Not normally used by programmers. Used by ?STACK to detect data stack overflow. Value for SP@ when data stack is full. BIGGESTHEREV ( -- ADDR ) Not normally used by programmers. Used by CREATE to determine if the nfa vocabulary region has overflowed. Last allowed slot in CURRENT vocabulary region. Result is not canonical the segment is set to the start of the vocab region. BINARY ( -- ) causes conversions to be done in radix 2. Defined as 2 BASE ! BL ( -- 32 ) 20h the constant blank. Leave the ASCII character value for space pronounced "b-l" \BBL\BBL.DOC -47- last updated 1986 October 14 21:30 BBL Forth Reference BLANK ( addr uw -- ) uw bytes of memory beginning at addr are set to the ASCII character value for space. No action is taken if u is zero. addr +u must be in the same segment as addr. For canonical addresses, u must be less than 65,519. pronounced "blank" BLK ( -- addr ) A variable containing the number of the mass storage block being interpreted as the input stream is taken from the text input buffer. If this variable contains 0 the input stream is taken from the TIB. The variable has values {0..the number of blocks available-1} pronounced "b-l-k" BLOCK ( uw -- addr ) addr is the address of the assigned buffer of the first byte of block uw. If the block occupying that buffer is not block u, and has been Updated it is transferred to mass storage before assigning the buffer. If block u is not already in memory, it is transferred from mass storage into an assigned block buffer. A block may not be assigned to more than one buffer. If u is not an available block number an error condition exists. Only data within the last buffer referenced by BLOCK or BUFFER is valid. The contents of a block buffer must not be changed unless the change may be transferred to mass storage. BODY> ( pfa -- cfa ) Converts pfa (parameter field address) to cfa (code field address). Use this word sparingly. WARNING THIS WORD IS EXTREMELY SLOW! It works by scanning all nfas in all vocabularies to find a match. You cannot use this word if the nfa header has been thrown away. If you need to do this, I suggest capturing the cfa at compile time when it can be gotten quickly with LATEST NAME> and storing it somewhere near the pfa. c.f. >BODY >NAME >LINK NAME> LINK> N>LINK L>NAME PREV- NFA pronounced "from-body" \BBL\BBL.DOC -48- last updated 1986 October 14 21:30 BBL Forth Reference BRANCH ( -- ) compiled by immediate words such as ELSE to unconditionally jump. When used in the form: COMPILE BRANCH an unconditional branch operation is compiled. A branch address must be compiled immediately following this compilation address. The branch address is typically generated by following BRANCH with <RESOLVE or >MARK. Followed in dictionary by a signed relative byte offset. BRANCH +2 is a NOOP branch. -2 is an endless loop. BUFFER ( uw -- addr ) like BLOCK except need not read the block because it is new or we no longer need the data in it. Assigns a block buffer to block uw. addr is the address of the first byte of the block within its buffer. This function is fully specified by the definition for BLOCK except that if the block is not already in memory it might not be transferred from mass storage. The contents of the block buffer assigned to block uw by BUFFER are unspecified. build-adcon ( value -- ) Internal word to generate asm code for an ADCON. build-constant ( value -- ) Internal word to generate asm code for a CONSTANT. build-jmp ( jumpaddr pfa -- ) internal word to build assembler JMP commands. build-model ( pfa patch-offset model-addr model-len -- ) internal word used to build code to go at the cfa from a model template. build-qconstant ( value -- ) Internal word to generate asm code for a QCONSTANT. BYE ( -- ) terminates BBL and returns to DOS. Closes all files. **C** words that begin with C C! ( value address -- ) Stores low order 1 byte at address. Works on both signed and unsigned quantities. Value is MSW on top of data stack, LSW first in memory . Address is seg:offset -- not necessarily canonical c.f. W! T! ! 2! ON OFF pronounced "c-bang" \BBL\BBL.DOC -49- last updated 1986 October 14 21:30 BBL Forth Reference C, ( c -- ) ALLOT one byte then store the least-significant 8 bits of 32b at HERE 1- in the pfa dictionary. pronounced "c-comma" C,C ( c -- ) Not normally used by programmers. ALLOT one byte then store the least-significant 8 bits of 32b at HEREC 1- in the cfa dictionary. pronounced "c-comma" C@ ( addr -- c ) c is the 8-bit contents of the byte at addr. The high order 3 bytes are zero filled -- not sign extended. There is no 1-byte fetch with sign extend c.f. C! W@ UW@ T@ UT@ @ 2@ pronounced "c-fetch" CACHE-HANDLE ( -- addr ) Variable containing the DOS file handle for the currently open cache file of screens. It will be 0 if the cache file is not open. c.f. CACHE-NAME USING OPEN-CACHE CLOSE-CACHE LAST-SCR CACHE-NAME ( -- addr ) an area of memory usually 40 bytes long that contains the external dos filename of the cache file where Forth screens are kept e.g. C:\ABS\FORTH.BLK. The name must be followed by an ascii null or enough blanks so that the builtin ascii null following CACHE-NAME acts as the terminator. To change the CACHE-NAME, first CLOSE- CACHE then change CACHE-NAME and then reopen with OPEN- CACHE. c.f. USING BLOCK CACHE-HANDLE OPEN-CACHE CLOSE-CACHE LAST-SCR CLEARSCREEN ( -- ) Clears the screen. If the video mode is 7 it will clear the monochrome screen. If the video mode is 2 for Black and White or 3 for colour it will clear the colour screen. CLOSE-CACHE ( -- ) close the CACHE file of Forth screens. DISK-ERROR @ is 0 if ok, 8 if could not close. BYE does this automatically. If you use the verbs BLOCK and BUFFER while the CACHE file is closed, the behaviour mimics being attached to the NULL device. You normally would do a FLUSH or SAVE-BUFFERS before calling CLOSE-CACHE. c.f. USING OPEN-CACHE DISK-ERROR FLUSH SAVE-BUFFERS EMPTY-BUFFERS CACHE-NAME LAST-SCR \BBL\BBL.DOC -50- last updated 1986 October 14 21:30 BBL Forth Reference CMOVE ( from-addr1 to-addr2 length-uw -- ) Move u bytes beginning at address addr1 to addr2. The byte at addr1 is moved first, proceeding toward high memory. If u is zero nothing is moved. CMOVE works from left to right thus you can slide a string on top of itself to lower memory. The length must be under 64K and must be covered by Segs of both addrs. The length may also be 0 or 1, but not negative. The addresses need not be canonical but addr-1 must cover both ends of string-1 and addr-2 must cover both ends of string-2. c.f. CMOVE> CMOVE> ( from-addr1 to-addr2 length-uw -- ) Move u bytes beginning at address addr1 to addr2. The move begins by moving the byte at (addr1 plus u minus 1) to (addr2 plus u minus 1) and proceeds to successively lower addresses for u bytes. If u is zero nothing is moved. CMOVE> works from right to left thus you can slide a string on top of itself to higher memory. The length must be under 64K. The length may also be 0 or 1, but not negative. The addresses need not be canonical but addr-1 must cover both ends of string-1 and addr-2 must cover both ends of string-2. c.f. CMOVE CODE ( -- ) A defining word executed in the form: CODE <name> ... END-CODE Creates a dictionary entry for <name> to be defined by a following sequence of assembly language words. Words thus defined are called code definitions. This newly created word definition for <name> cannot be found in the dictionary until the corresponding END-CODE is successfully processed. Executes ASSEMBLER to invoke the words in the ASSEMBLER vocabulary. c.f. END-CODE COMPILE ( -- ) Typically used in the form: : <name> ... COMPILE <namex> ... ; When <name> is executed, the compilation address compiled for <namex> is compiled and not executed. <name> is typically immediate and <namex> is not immediate. COMPILE compiles the next inline token into the pfa dictionary e.g. ?DO would have a COMPILE (?DO) in its definition. See; "compilation" \BBL\BBL.DOC -51- last updated 1986 October 14 21:30 BBL Forth Reference COMPILE-NUM ( d -- ) Not normally used by programmers. Used by INTERPRET after NUMBER to compile either a 32-bit or 64-bit inline literal depending on the value of DPL. Numbers with decimal points get compiled as double precision 64-bit literals and numbers without decimal points get compiled as 32-bit literals. DLITERAL is an immediate word that compiles as DLIT-token followed by a 64-bit literal. LITERAL is an immediate word that optimizes the building of 32-bit literals by compiling +WLIT - WLIT or LIT as needed. c.f. LITERAL DLITERAL COMPILE-STRING ( -- ) Not normally used by programmers. Used by words such as ." to build "-delimited counted strings into dictionary. CONSOLE ( -- ) redirects EMIT and TYPE output to screen by setting up the 'EMIT and 'TYPE vectors. CONSOLE is defined as : CONSOLE ['] SEMIT 'EMIT ! ['] STYPE 'TYPE ! ; c.f. PRINTER TYPE EMIT 'TYPE 'EMIT SEMIT STYPE CONSTANT ( 32b -- ) A defining word executed in the form: 32b CONSTANT <name> Creates a dictionary entry for <name> so that when <name> is later executed, 32b will be left on the data stack. c.f. QCONSTANT, ADCON \BBL\BBL.DOC -52- last updated 1986 October 14 21:30 BBL Forth Reference CONSTANT! ( value cfa -- ) In normal Forth you can actually change the value of a CONSTANT by saying 4 CONSTANT FOUR 5 ' FOUR >BODY ! This cheat will not work in BBL because CONSTANTS are generated as primitives -- directly as assembler code to push the value to the stack. To change a CONSTANT you must do the following 4 CONSTANT FOUR 5 ' FOUR CONSTANT! CONSTANT! will not work reliably on ADCONs or QCONSTANTS. This whole discussion may sound like something out of Alice in Wonderland. Why would anyone in their right mind try to change the value of a CONSTANT? They might to implement read-mostly variables. CONSTANTS don't need a @ so they work much faster than VARIABLEs to examine their contents. However VARIABLES are must faster to set. You just use !. To change a CONSTANT you use CONSTANT! which actually ends up re-assembling a tiny routine to generate the new value. c.f. CONSTANT. CONTEXT ( -- addr ) The address of a variable which determines the dictionary search order. CONVERT ( +d1 addr1 -- +d2 addr2 ) +d2 is the result of converting the characters within the text beginning at addr1+1 into digits, using the value of BASE , and accumulating each into +d1 after multiplying +d1 by the value of BASE . Conversion continues until an unconvertible character is encountered. addr2 is the location of the first unconvertible character. c.f. BASE NUMBER >DIGIT CORRAL ( value lowest highest -- safe-value) traps a value between two bounds. If too small it set to the low bound, if too high it is set to the high bound. Roughly equivalent to Value Lowest MAX Highest MIN. For it to work lowest must be less than or equal to highest. Uses signed compares. e.g. 4 5 8 CORRAL -- 5 7 5 8 CORRAL -- 7 9 5 8 CORRAL -- 8 c.f. MIN MAX \BBL\BBL.DOC -53- last updated 1986 October 14 21:30 BBL Forth Reference COUNT ( addr1 -- addr2 +n ) Used to prepare counted string for TYPE. addr2 is addr1+1 and +n is the length of the counted string at addr1. The byte at addr1 contains the byte count +n followed by the string. Range of +n is {0..255} CR ( -- ) Displays a carriage-return (ASCII char 13) and line- feed (ASCII char 10). Also does OUT 0! to reset the count of characters in a line. pronounced "c-r" CREATE ( -- ) ( -- pfa : when <name> is executed ) A defining word executed in the form: CREATE <name> Creates a dictionary entry for <name>. After <name> is created, the next available dictionary location HERE is the first byte of <name>'s pfa (parameter field address). When <name> is subsequently executed, the address of the first byte of <name>'s parameter field is left on the data stack. CREATE does not allocate any space at all in <name>'s parameter field. However it does generate 11 bytes of assembler code at <name>'s cfa whose duty is to push the pfa when <name> is executed. Most often used : KIND CREATE n ALLOT DOES> ... ; or CREATE XXX n1 , n2 , ... outside a colon definition. If the word being CREATEd already exists in the CURRENT DEFINITIONS vocabulary, normally you will get a Redefined warning message. Whether the word is defined in some other vocabulary other than the CURRENT one is immaterial e.g. No message is given if the word is in one of the CONTEXT resident vocabularies. However if you are in LOGO mode set by LOGO ON, the old version will be patched to jump to the new one. This has the effect of redirecting all the users of the old version to the new. Words like : VARIABLE CONSTANT and ALIAS all use CREATE to set up the nfa of the newly defined word in the CURRENT DEFINITIONS vocabulary. c.f. LOGO CURRENT DEFINITIONS create-model ( -- ) used internally as the model assembler code that CREATE generates at the cfa of a newly defined word. \BBL\BBL.DOC -54- last updated 1986 October 14 21:30 BBL Forth Reference CURRENT ( -- addr ) The address of a variable specifying the vocabulary in which new word definitions are appended. It is sometimes called the compilation vocabulary or the DEFINITIONS vocabulary. CURRENT @ gets you the address of the base of the vocabulary storage region. CURRENT @ @ gets you the latest definition added to the current vocabulary. c.f. CONTEXT DEFINITIONS FORGET LATEST **D** words that begin with D D+ ( wd1 wd2 -- wd3 ) wd3 is the arithmetic sum of wd1 plus wd2. Adds two signed 64b numbers pronounced "d-plus" D, ( D --- ) Compiles a 64-bit value into the pfa part of the dictionary. c.f. , D- ( wd1 wd2 -- wd3 ) wd3 is the result of subtracting wd2 from wd1. pronounced "d-minus" D. ( d -- ) Prints a 64-bit signed number followed by a space. The absolute value of d is displayed in a free field format. A leading negative sign is displayed if d is negative. pronounced "d-dot" D.R ( d +n -- ) d is converted to ASCII using the value of BASE and then displayed right aligned in a field +n characters wide. A leading minus sign is displayed if d is negative. If the number of characters required to display d is greater than +n the field is simply widened to accommodate it. pronounced "d-dot-r" D0= ( d -- flag ) flag is true if d is zero c.f. 0< 0<= 0> 0>= 0= 0<> NOT pronounced "d-zero-equals" \BBL\BBL.DOC -55- last updated 1986 October 14 21:30 BBL Forth Reference D2/ ( d1 -- d2 ) quick 64-bit divide by 2. d2 is the result of d1 arithmetically shifted right one bit. The sign is included in the shift and remains unchanged. c.f. SHIFT division 2/ / pronounced "d-two-slash" D< ( d1 d2 -- flag ) flag is true if d1 is less than d2 using signed 64-bit compare. c.f. < U< <= > U> D> >= = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "d-less-than" D= ( d1 d2 -- flag ) flag is true if d1 equals d2. Can also be used to compare the two sets of pairs of 32-bit numbers for equality. c.f. < U< D< <= > U> D> >= = <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "d-equal" DABS ( d -- ud ) ud is the absolute value of d. In other words DABS makes d positive. If d is < 0 then the result is -d. If d is greater than 0 then the result is simply d. If d is -264 then ABS cannot work properly as there is no positive equivalent that can be expressed in 64 bits, so in that case the result is unchanged at -264. DECIMAL ( -- ) Set the input-output numeric conversion base to ten. DEFER ( used in form DEFER XXX ) creates a new word that does nothing. Later you use ['] YYY AS XXX to give XXX a new meaning. Thereafter XXX acts as an alias for YYY. Use ALIAS for static aliases. Use DEFER as for dynamic ALIASes. You can also use ['] and EXECUTE to get similar effects. The DEFER AS method is faster and cleaner but non-standard. e.g. VARIABLE 'XXX : XXX 'XXX @ EXECUTE ; ' YYY 'XXX ! is equivalent to: DEFER XXX ' YYY AS XXX is also equivalent to: ' YYY ALIAS XXX c.f. AS (AS) EXECUTE PEFORM ['] ' DEFINITIONS ( -- ) The compilation vocabulary is changed to be the same as the first vocabulary in the search order. Makes the CURRENT vocabulary same as CONTEXT. c.f. CURRENT CONTEXT LATEST \BBL\BBL.DOC -56- last updated 1986 October 14 21:30 BBL Forth Reference DEPTH ( -- n ) n is the number of 32-bit values contained in the data stack before n was placed on the data stack. If the data stack has underflowed, the result could be negative. Note that DEPTH is measured in 4-byte chunks -- not bytes. DIGIT> ( digit 0..36 --- ascii char ) Used by # to convert a single digit to ASCII e.g.. 0 - - ^ 0 decimal 48, 10 -- ^ A decimal 65, 15 -- ^ F decimal 70 DISK-ERROR ( -- addr ) variable that contains the status of the most recent BLOCK BUFFER SAVE-BUFFERS OPEN-CACHE or CLOSE-CACHE. The contents of the variable are 0 if all is ok, 1 if there was a read error, and 2 if there was a write error, 4 if there was an open error and 8 if there was a close error. Note that for a disk full write error you will not get an error on UPDATE. It will not show up until SAVE-BUFFERS or possibly a subsequent BLOCK. c.f. USING BLOCK BUFFER SAVE-BUFFERS CLOSE-CACHE OPEN- CACHE FLUSH LAST-SCR DLIT ( -- Dvalue ) Not normally used by programmers. DLITERAL compiles as DLIT-Token followed by a 64-bit constant stored LSW first to handle 64-bit inline constants. The constant may be signed or unsigned. This is a not a word that used directly. It is generated by DLITERAL or in-line constants containing decimal points. e.g. 3.414. c.f. DLITERAL DMAX ( d1 d2 -- d3 ) d3 is the greater of d1 and d2. pronounced "d-max" DMIN ( d1 d2 -- d3 ) d3 is the lesser of d1 and d2. c.f. MIN MAX CORRAL pronounced "d-min" DNEGATE ( d1 -- d2 ) d2 is the two's complement of d1 i.e. -d1 pronounced "d-negate" \BBL\BBL.DOC -57- last updated 1986 October 14 21:30 BBL Forth Reference DO ( n1 n2 -- ) ( -- back-addr-1 back-addr-2 3 ) (compiling) Used in the form: DO ... LOOP or DO ... n +LOOP Begins a loop which terminates based on control parameters. The loop index begins at n2, and terminates based on the limit n. See LOOP and +LOOP for details on how the loop is terminated. The loop is always executed at least once. DO compiles as (DO)- token. The most common type of loop to execute n times is of the form n 0 DO. I will then have the values 0, 1 .. n-1 each time through the loop. c.f. ?DO LOOP +LOOP LEAVE (DO) (?DO) (LOOP) (+LOOP) (LEAVE) docol ( -- ) Not normally used by programmers. This little piece of assembler code is used to kick off the execution of all colon definitions. dodoes ( -- ) Not normally used by programmers. This little piece of assembler code is used to kick off the execution of all DOES> code. does-model ( -- ) Not normally used by programmers. This little piece of assembler code is used as a model to create the cfa code needed to kick off DOES> code. DOES> ( -- addr ) ( --) (compiling) Defines the execution-time action of a word created by a high-level defining word. Used in the form: : <namex> ... <create> ... DOES> ... ; and then <namex> <name> where <create> is CREATE or any user defined word which executes CREATE. CREATE DOES> is the most powerful feature of Forth. It is almost impossible to understand without examining lots of examples. For example if you wished to create your own slow running version of CONSTANT using CREATE DOES> you could code it like this: : MY-CONSTANT CREATE , ( compile time behaviour to store value at pfa ) DOES> @ ( run time behaviour to fetch value from pfa ) ; 6 MY-CONSTANT Six Six . \BBL\BBL.DOC -58- last updated 1986 October 14 21:30 BBL Forth Reference dovoc DP ( -- addr ) Variable containing the address of of the next available dictionary location in the pfa (parameter field address) part of the dictionary. There is only one DP -- not one per VOCABULARY. HERE acts like DP @. Because of the delicate segment:offset forms required you should not meddle directly with DP. Use HERE and ALLOT instead. Existing programs written in Forth-83 will need to have every use of DP or HERE examined to see if it should read HERE, HEREB, HEREC HEREV or HERER. Most of the time HERE or HEREB is what is wanted. c.f. HERE DPB DPC DPR DPV DPB ( -- ADDR ) Not normally used by programmers. Variable containing the address where WORD leave the counted string it has parsed. It is usually set to HEREV+2, but sometimes points to the nfa of the most recently added word in the CURRENT DEFINITIONS vocabulary. HEREB behaves like DPB @. Because of the delicate segment:offset forms required you should not meddle directly with DPB Use HEREB instead. c.f. HEREB DP DPC DPR DPV DPC ( -- ADDR ) Not normally used by programmers. Variable containing next free location the the cfa (code field address) part of the dictionary. HEREC acts like DPC @. Because of the delicate segment:offset forms required you should not meddle directly with DPC. Use HEREC or ALLOTC instead. c.f. HEREC DP DPB DPR DPV DPR ( -- ADDR ) Not normally used by programmers. Variable containing next free slot in area of memory from which new vocabulary storage regions are carved. HERER behaves like DPR @. Because of the delicate segment:offset forms required you should not meddle directly with DPR. Use HERER or ALLOTR instead. c.f. HERER DP DPC DPB DPV DPV ( -- ADDR ) Not normally used by programmers. Variable containing the next free slot in CURRENT vocabulary region HEREV behaves like DPV @. Because of the delicate segment:offset forms required you should not meddle directly with DPV. Use HEREV instead. c.f. HEREV DP DPC DPB DPR \BBL\BBL.DOC -59- last updated 1986 October 14 21:30 BBL Forth Reference DROP ( 32b -- ) 32b is removed from the data stack. c.f. 2DROP 3DROP 4DROP RDROP DU< ( ud1 ud2 -- flag ) flag is true if ud1 is less than ud2. Both numbers are unsigned. pronounced "d-u-less" DUMP ( addr len -- ) Debugging tool to examine an area of memory in both HEX and ASCII. The display can be paused by hitting Ctrl- Numlock. The display can be interrupted by hitting any other key. DUP ( 32b -- 32b 32b ) Duplicate 32b. pronounced "dupe" **E** words that begin with E EARLIEST-NFA ( ' My-Voc >BODY --- nfa ) From the pfa of an arbitrary vocabulary EARLIEST-NFA calculates the NFA of the oldest word added first at the beginning of that vocabulary. If the vocabulary is empty the result is 0. It is used in conjunction with NEXT-NFA to chase through all the words in a vocabulary. It does NOT use the hash threads. c.f. LATEST-NFA PREV-NFA NEXT-NFA LATEST EDIT ( -- ) invokes the NED screen editor. Note that you do NOT place the number of the screen you wish to edit on the data stack as you do with most Forth screen editors. See NED.DOC for a further description of the editor. Once you are in NED use F1 for Help. EDITOR ( -- ) The name of the VOCABULARY where the words that make up the NED screen editor are kept. EDITOR makes this vocabulary the CONTEXT vocabulary -- the one first in the search order. \BBL\BBL.DOC -60- last updated 1986 October 14 21:30 BBL Forth Reference ELSE ( -- : executing ) ( backaddr 2 -- backaddr 2 : compiling ) Used in the form: flag IF ... ELSE ... THEN ELSE executes after the true part following IF . ELSE forces execution to continue at just after THEN . sys1 is balanced with its corresponding IF . sys2 is balanced with its corresponding THEN . c.f. IF THEN EMIT ( c -- ) The least-significant 8-bit ASCII character is displayed. EMIT can be redirected to the screen with CONSOLE or to the printer with PRINTER. TYPE is defined as an optimized version of : EMIT 'EMIT @ EXECUTE ; Thus you can redirect EMIT by providing your own type routine and vectoring it in with ['] MY-EMIT 'EMIT !. Normally when you redirect EMIT you also redirect TYPE. c.f. CONSOLE PRINTER 'EMIT SEMIT PEMIT GTYPE TYPE 'TYPE STYPE PTYPE. EMPTY-BUFFERS ( -- ) Unassign all block buffers. Updated blocks are not written to mass storage. c.f. BLOCK pronounced "empty-buffers" ENCLOSE ( addr1 delim -- addr1 n1 n2 n3 ) Used by WORD to parse the input stream. Can be used to parse any string terminated by a null. Addr1 is where to start parsing. The delimiter is usually 020h = blank. n1 = byte offset first non delimiter i.e. start word. n2 = byte offset of the trailing delimiter - end word +1. n3 = byte offset first char not included = n2+1 normally. Null Hex 00 is also treated as delimiter. If no work at all can be found -- just delimiters then n1=offset of null n2=n1+1 n3=n2. If the word is followed by null, n1=offset start word, n2=offset null and n3=n2. END-CODE ( -- ) Terminates a code definition and allows the <name> of the corresponding code definition to be found in the dictionary. END-CODE is balanced with its corresponding CODE or ;CODE . c.f. CODE ;CODE pronounced "end-code" ENTRY ( -- ) Not normally used by programmers. Used as part of the cold start. \BBL\BBL.DOC -61- last updated 1986 October 14 21:30 BBL Forth Reference EVENUP ( N1 -- N2 ) Rounds up to next even number. N2=N1 if N1 is even N2=N1+1 if N2 is odd. EXECUTE ( cfa-addr -- ) Allows you to execute a routine passed as a parameter via its cfa address. Similar to Pascal's Procedure parameters. The word definition indicated by addr is executed. An error condition exists if addr is not a compilation address. The address is nearly always provided by ['] or '. EXECUTE ignores the segment part of the address, presuming it is CS:. For this reason EXECUTE will work on either relative addresses or CS: based segment addresses. It will not work if the address is based on any other value. As long as the address is created with ['] or ' this will not cause a problem. ['] X EXECUTE is equivalent to X. The DEFER AS method solves a similar problem to the one EXECUTE does but it executes more quickly. c.f. ' ['] PERFORM DEFER AS EXIT ( -- ) Exit current procedure, synonym for ;S EXIT is preferred for premature exit from a high level definition. Compiled within a colon definition such that when executed, that colon definition returns control to the definition that passed control to it by returning control to the return point on the top of the return stack. An error condition exists if the top of the return stack does not contain a valid return point. In this implementation it may not be used within a do- loop. c.f. ;S EXPECT ( addr +n -- ) Receive characters from the keyboard and store each into memory. The transfer begins at addr proceeding towards higher addresses one byte per character until either a "return" is received or until +n characters have been transferred. No more than +n characters will be stored. The "return" is not stored into memory. No characters are received or transferred if +n is zero. All characters actually received and stored into memory will be displayed, with the "return" displaying as a space. The string will be delimited by a Hex 00 null character. The variable SPAN is set to the length of the string not counting the return or null. c.f. SPAN \BBL\BBL.DOC -62- last updated 1986 October 14 21:30 BBL Forth Reference **F** words that begin with F FILL ( addr uw c -- ) uw bytes of memory beginning at addr are set to c. No action is taken if uw is zero. Uw may also be 0 or 1, but not negative. Uw must be under 64K. The address need not be canonical, but it must cover both ends of the area in memory to be filled. c.f. BLANK ERASE CMOVE CMOVE> FIND ( addr1 -- addr2 n ) addr1 is the address of a counted string (usually but not necessarily at HEREB). The string contains a word name to be located in the currently active search order. If the word is not found, addr2 is the string address addr1, and n is zero. If the word is found, addr2 is the cfa compilation address and n is set to one of two non-zero values. If the word found has the immediate attribute, n is set to one. If the word is non-immediate, n is set to minus one (true). c.f. (FIND) ?FOUND ['] ' FIRST ( -- addr ) Not normally used by programmers. Address of the first screen buffer. The segment portion of this address is SS: Watch out! Fig Forth programs sometimes make unwarranted assumptions about the relative position of FIRST and other system areas. FLUSH ( -- ) Performs the function of SAVE-BUFFERS then unassigns all block buffers. (This may be useful for mounting or changing mass storage media). In the good old days FLUSH was a synonym for SAVE-BUFFERS. Now they have a different meaning. c.f. EMPTY-BUFFERS SAVE-BUFFERS FOR-EACH-VOC ( ' Routine -- ) : Routine ( pfa -- ) ... ; If you write a routine that expects the pfa of a vocabulary on the stack, then FOR-EACH-VOC will chase the VOC-LINK chain for you and call your routine once for each vocabulary in the VOC-LINK chain starting with the newest vocabulary. Note that pfa @ will get you the address of the start of the vocabulary storage region. pfa @ @ will get you the nfa of the latest word in the vocabulary. c.f. VOC-LINK VOCABULARY ORDER \BBL\BBL.DOC -63- last updated 1986 October 14 21:30 BBL Forth Reference FORGET ( -- ) Used in the form: FORGET <name> If <name> is found in the compilation CURRENT DEFINITIONS vocabulary, delete <name> from the dictionary and all words added to the dictionary after <name> regardless of their vocabulary. Failure to find <name> is an error condition. An error condition also exists if any CURRENT or CONTEXT vocabulary is deleted. If new vocabularies were defined after <name> they too will be forgotten, along with all the words in them. The word you FORGET must have a cfa and pfa e.g. a colon definition. Thus you cannot use a CONSTANT as the object of a FORGET. Typically a dummy colon routine such as : TASK ; is used as the object. Forget presumes the dictionaries have not been snaked. I.e. If B were compiled after A, then the cfa of B is greater or equal to the cfa of A, the pfa of B is greater or equal to the pfa of A. Furthermore if A and B are in the same vocabulary then, the nfa of B is greater or equal to the nfa of A. If A and B are both vocabularies then B's vocabulary storage region must be higher in memory than A's. The cfa rule can be broken in the case of ALIASes. LOGO mode has potentially dangerous effects when used with FORGET. See information in BBLVOCS.ASM on how FORGET is implemented to get a deeper understanding. c.f. ALIAS LOGO FORTH ( -- ) The name of the primary vocabulary. Execution replaces the first vocabulary in the search order with FORTH . FORTH is initially the compilation vocabulary and the first vocabulary in the search order. New definitions become part of the FORTH vocabulary until a different compilation vocabulary is established. FORTH is not immediate. This follows the Forth-83 rather than Forth-79 convention. c.f. VOCABULARY FORTH-83 ( -- ) Assures that a FORTH-83 Standard System is available, otherwise an error condition exists. THIS WORD IS NOT PRESENT. BBL does not conform strictly to the Forth-83 standard because BBL is 32-bit and because it has non- linear addresses. The confusing multiplicity of HERE HEREC HEREV HEREB HERER would I am sure give the Forth 83 standards team just reason to pull their hair. However I have attempted to follow the Forth-83 standard as closely as possible even when I thought it was off-base. \BBL\BBL.DOC -64- last updated 1986 October 14 21:30 BBL Forth Reference **G** words that begin with G GOTOXY ( col row -- ) Move the DOS screen cursor to row and column. Upper left corner is 0 0. Lower right corner is 79 24. GTYPE ( addr len -- ) types string to printer or screen using the current EMIT routine. It is almost never used directly as the TYPE routine is usually faster than repeated uses of the EMIT routine. However it can be useful if you have written your own EMIT routine and are too lazy to write your own TYPE routine. To vector in your new EMIT routine for both EMIT and TYPE you would do ['] MY-EMIT 'EMIT ! ['] GTYPE 'TYPE !. c.f. TYPE EMIT 'TYPE 'EMIT STYPE SEMIT PTYPE PEMIT PRINTER CONSOLE. **H** words that begin with H HASH ( nfa -- hash# ) Not normally used by programmers. Used by FIND to speed dictionary searches. Expects counted string at nfa 0..31 bytes. Returns 16-bit randomized (but not random) number. This hash# number needs to be masked to get the thread number in the dictionary where this word could be found. HERE ( -- addr ) The address of the next available dictionary location in the pfa (parameter field address) part of the dictionary. There is only one HERE -- not one per VOCABULARY. HERE is usually not canonical. The segment part of HERE is as it was canonized at the last CREATE -- pointing at or just before the pfa. HERE acts like DP @. This is the normal pfa style HERE in the token segment where variable and the colon definitions are kept. IT IS NOT where WORD builds the parsed word. Existing programs written in Forth-83 will need to have every use of HERE examined to see if it should read HERE, HEREB, HEREC HEREV or HERER. Most of the time HERE or HEREB is what is wanted. c.f. DP HEREB HEREV HEREC HERER \BBL\BBL.DOC -65- last updated 1986 October 14 21:30 BBL Forth Reference HEREB ( -- ADDR ) Not normally used by programmers. Where WORD leave the counted string it has parsed. It is usually set to HEREV+2, but sometimes points to the nfa of the most recently added word in the CURRENT DEFINITIONS vocabulary. The address is result is not canonical -- the segment part of the address is the start of the vocab region. The only time you would use HEREB is if you were writing code like .WORD that produced error messages about the most recently parsed word. HEREB behaves like DPB @. c.f. DPB HERE HEREC HEREV HERER HEREC ( -- ADDR ) Not normally used by programmers. Next free location the the cfa (code field address) part of the dictionary. There is only one HEREC -- not one per VOCABULARY. HEREC is not canonical. The segment part of the address part is always CS:. HEREC acts like DPC @. The only time you would ever touch HEREC is if you were writing words that generate assembler code. c.f. DPC HERE HEREB HEREV HERER HERER ( -- ADDR ) Not normally used by programmers. Next free slot in area of memory from which new vocabulary storage regions are carved. Each time a new vocabulary is defined, a chunk of memory for its vocabulary storage region is allocated. The size of this chunk is determined by VOC-SIZE. This region is used to store the hash threads and the nfa's of words that will be later defined in this vocabulary. This is in addition to the small amount of space allocated for the cfa and pfa. Because vocabulary storage regions always start and end on paragraph boundaries, the offset part of HERER will always be 0. Note that each VOCABULARY has its own separate HEREV, but there is one HERER from which the vocabulary regions are allocated. The only time you would use HERER is if you were writing code that built new vocabularies. HERER behaves like DPR @. c.f. DPR HERE HEREB HEREC HEREV VOCABULARY VOC-SIZE \BBL\BBL.DOC -66- last updated 1986 October 14 21:30 BBL Forth Reference HEREV ( -- ADDR ) Not normally used by programmers. Next free slot in CURRENT vocabulary region i.e. the DEFINITIONS vocabulary where new definitions are compiled. The address is result is not canonical -- the segment part of the address is the start of the vocab region. Note that each VOCABULARY has its own separate HEREV. The only time you would use HEREV is if you were writing code that built the nfa headers in the vocabulary region. HEREV behaves like DPV @. c.f. DPV HERE HEREB HEREC HERER HEX ( - ) Set the numeric input-output conversion base to sixteen. pronounced "hex"; c.f. BINARY DECIMAL BASE .BASE HIDDEN ( -- ) The name of a vocabulary used to hold definitions you do not want users to see or experiment with. HOLD ( char -- ) char is inserted into a pictured numeric output string. Typically used between <# and #> It can be used to insert decorative commas, decimal points, currency characters etc. c.f. <# # #> **I** words that begin with I I ( -- n ) n is a copy of the loop index. May only be used in the form: DO ... I ... LOOP or DO ... I ... +LOOP; The most common loop has the form n 0 DO I LOOP. In that case the loop is executed n times, and the loop index has the values 0, 1 , 2, ... n-1. The loop index never equals n. Because the loop index is stored on the return stack in a modified form, I is NOT synonymous with R@ as it is in many Forth-79 implementations. Watch Out! c.f. J R@ DO LOOP \BBL\BBL.DOC -67- last updated 1986 October 14 21:30 BBL Forth Reference IF ( flag -- ) ( -- backaddr 2 ) (compiling) Used in the form: flag IF ... ELSE ... THEN or flag IF ... THEN If flag is true, the words following IF are executed and the words following ELSE until just after THEN are skipped. The ELSE part is optional. If flag is false, words from IF through ELSE , or from IF through THEN (when no ELSE is used), are skipped. IF can only be used inside colon definitions. IMMEDIATE ( -- ) Marks the most recently created dictionary entry as a word which will be executed when encountered during compilation rather than compiled. Sets the IMMED bit in the LATEST nfa. Words such as IF and DO are IMMEDIATE because they execute at compile time, ensuring balanced pairs and computing offsets, and leave behind non-immediate words such as ?BRANCH and (DO) that perform the actual work at execution time. Note that VOCABULARIES such as FORTH and ONLY are NOT immediate. This is the Forth-83 convention. In Fig- Forth and Forth-79 vocabularies were immediate as God intended. INDEX ( n1 n2 -- ) displays the first lines of disk screens n1 through n2. The first line us usually a comment to summarize the contents of the screen. The display can be paused by hitting Ctrl-Numlock. The display can be interrupted by hitting any other key. If n1 must be less than or equal to n2. If n2 is out past the current end of the cache file, the index listing will stop early when it hits the end of file. INIT-BUFFERS ( -- ) Not normally used by programmers. Part of cold boot to initialize the BUF-OFF pointers to point to the first byte of each buffer. INTERPRET ( -- ) Begin text interpretation at the character indexed by the contents of >IN relative to the block number contained in BLK, continuing until the input stream is exhausted. If BLK contains zero, interpret characters from the TIB text input buffer. INTERPRET keeps going until it hits a Null Hex 00, or it until it executes a QUIT or ABORT. Normally INTERPRET will interpret one line of keyed commands or one screen of text. pronounced "interpret" \BBL\BBL.DOC -68- last updated 1986 October 14 21:30 BBL Forth Reference **J** words that begin with J J ( -- n ) n is a copy of the index of the next outer loop. May only be used within a nested DO-LOOP or DO-+LOOP in the form, for example: DO...DO...J ... LOOP ... +LOOP Because this implementation stores modified values of the loop index on the return stack, J cannot be used to get at elements buried in return stack. c.f. I K R@ DO ?DO **K** words that begin with K KEY ( -- c ) The least-significant 8 bits is the next ASCII character received from the keyboard. All valid ASCII characters and the IBM extended 8-bit set can be received. In addition the standard 0-lead in sequences for function keys can be received. Control characters are not processed by the system for any editing purpose. Characters received by KEY will not be displayed **L** words that begin with L L>NAME ( lfa -- nfa ) Not normally used by programmers. Converts lfa (link field address) to nfa (name field address). This gets the nfa of the corresponding name, not the predecessor. This word uses the hash threads. c.f. >BODY >NAME >LINK BODY> NAME> LINK> LINK@ N>LINK LINK@ PREV-NFA pronounced "link-to-name" LAST-SCR ( -- addr ) a variable that contains the screen number of the last screen in the cache file. It is maintained by OPEN- CACHE, UPDATE and SAVE-BUFFERS. It is not changed by BLOCK. If the cache file is not open LAST-SCR will contain a 0. c.f. OPEN-CACHE UPDATE SAVE-BUFFERS BLOCK DISK-ERROR \BBL\BBL.DOC -69- last updated 1986 October 14 21:30 BBL Forth Reference LATEST ( -- NFA ) The name field address of most recently added word in CURRENT DEFINITIONS compilation vocabulary. The result is not canonical - the segment part of the address is the start of the vocab region. To get the equivalent for an arbitrary vocabulary use LATEST-NFA. EARLIEST-NFA LATEST-NFA PREV-NFA NEXT-NFA CURRENT DEFINITIONS CONTEXT. LATEST-NFA ( ' My-Voc >BODY --- nfa ) From the pfa of an arbitrary vocabulary LATEST-NFA calculates the NFA of the most recently added word at the end of that vocabulary. If the vocabulary is empty the result is 0. If you which this for the CURRENT DEFINITIONS compilation vocabulary, use can use LATEST instead. LATEST-NFA is used in conjunction with PREV- NFA to chase through all the words in a vocabulary. c.f. EARLIEST-NFA PREV-NFA NEXT-NFA LATEST LEAVE ( -- ) ( -- ) (compiling) Transfers execution to just beyond the next LOOP or +LOOP . The loop is terminated and loop control parameters are discarded. May only be used in the form: DO ... LEAVE ... LOOP or DO ... LEAVE ... +LOOP LEAVE may appear within other control structures which are nested within the do-loop structure. More than one LEAVE may appear within a do-loop. LEAVE compiles as a (LEAVE) token. LEAVE does not mess with pairs placed on the data stack at compile time by DO. LINK> ( lfa -- cfa ) Not normally used by programmers. Converts lfa (link field address) to cfa (code field address) c.f. >BODY >NAME >LINK BODY> NAME> LINK@ N>LINK L>NAME LINK@ PREV-NFA pronounced "from-link" LINK@ ( lfa -- nfa of predecessor ) Not normally used by programmers. Used to fetch the 16-bit backward pointer at the link field address to get the name field address of the predecessor word on the same thread. Watch out. In PCForth Plus LINK@ was used for UT@ to fetch an unsigned 3-byte quantity c.f. >BODY >NAME >LINK BODY> NAME> LINK> N>LINK L>NAME PREV-NFA pronounced "link-fetch" LIST ( SCR --- ) types whole screen \BBL\BBL.DOC -70- last updated 1986 October 14 21:30 BBL Forth Reference LIT ( -- value ) Not normally used by programmers. LITERAL compiles as LIT-token followed by a 32-bit constant stored LSW first to handle 32-bit inline constants. The constant may be signed or unsigned. LITERAL ( -- 32b ) ( 32b -- ) (compiling) Handles creation inline literals. Typically used in the form: [ 32b ] LITERAL Compiles as +WLIT-token, -WLIT-token, LIT-token or one of the primitive constant tokens 0..9, or TEN so that when later executed, 32b will be left on the data stack. Handles -1 .. 10d as single tokens. Handles 11d .. ffffh AS +WLIT 16-BIT. Handles ffff0000h ... fffffffeh as -WLIT 16-BIT. Handles the rest as LIT 32- bit. The popular CLIT of Forth-83 has been discontinued because BBL likes to start tokens on an even byte boundary so there is no advantage in 1-byte literals over 2-byte ones. Most commonly used to compute expressions at compile time into inline constants: e.g. [ x y + ] LITERAL c.f. LITERAL DLITERAL COMPILE-NUM LIT +WLIT -WLIT LIT. LOAD ( U -- ) Effectively executes the commands on disk screen u as though they were being rapidly keyed in by temporarily redirecting the keyboard input to screen u. Most commonly used to compile colon definitions created with the editor. The contents of >IN and BLK, which locate the current input stream, are saved. The input stream is then redirected to the beginning of screen u by setting >IN to zero and BLK to u. The screen is then interpreted. If interpretation from screen u is not terminated explicitly (e.g. by ;S or QUIT) it will be terminated when the input stream is exhausted and then the contents of >IN and BLK will be restored. An error condition exists if u is zero. c.f. >IN BLK BLOCK \BBL\BBL.DOC -71- last updated 1986 October 14 21:30 BBL Forth Reference LOGO ( -- addr ) The Logo language behaves differently from Forth when you recompile a new version of an existing word. The LOGO logical variable lets you persuade BBL Forth to behave the wonderful way Logo does. Normally LOGO contains a 0. However if you do LOGO ON then BBL uses Logo's way of handling what happens when you recompile a word with the same name as one already in the dictionary. LOGO contains -1 = TRUE if previous incarnations of a word are to be patched to use the new version. With this mode a full recompile is not necessary if a word deep down is recompiled, because all the code that used the old version will go to the old version, but then be redirected to the new one. LOGO contains 0 = FALSE if old code uses the old version of a word. The default is false. -- per normal FORTH. If you use LOGO mode be careful after a FORGET. The old version which pops to the fore is patched to the deleted new version. If you were to use the old version (even indirectly) without recompiling a new version, you would have a dangerous dangling pointer most likely leading to a system crash. In Forth mode with LOGO 0, the old version comes to the fore undamaged the way it used to be. With LOGO mode you can recompile the same word over and over and every incarnation gets indirectly re-routed in several steps to the newest one. If you redefine a Forth system word while in LOGO mode, the Forth nucleus will also start using your new definition. Unless your new version is very similar to the original meaning, the system will almost certainly crash. LOGO mode can be used to give you forward references without having to build vectoring routines. Just define a dummy routine such as : DOIT ; Then use DOIT. Then later define the real DOIT and the old version will be patched to use the new version effectively giving you the ability to use a routine that isn't written yet. When you are in LOGO mode if you redefine a word with a name that already exists in the current definitions vocabulary you will get a "recompiled" warning message. When you are in Forth mode mode you will get a "redefined" warning message instead. c.f. FORGET \BBL\BBL.DOC -72- last updated 1986 October 14 21:30 BBL Forth Reference LOOP ( -- ) ( backaddr-1 backaddr-2 -- ) (compiling) Increments the DO-LOOP index by one. If the new index was incremented across the boundary between limit-1 and limit the loop is terminated and loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding DO. The most common form of LOOP use is 10 0 DO ... LOOP. The loop is executed 10 times with the loop index taking the values 0, 1, 2 ... 9. LOOP compiles as (LOOP)-token followed by a BRANCH style offset back to; the token after the offset after the (DO) c.f. DO ?DO +LOOP LSW ( n1 -- n2 ) Least Significant Word. n2 is the least significant 16 bits of n1 padded on the left with zeros. Note that both n1 and n2 are values on the data stack -- not addresses in RAM. c.f. MSW **M** words that begin with M M* ( n1-32 n2-32 -- d3-64 ) Mixed mode multiply of a signed 32-bit * 32-bit giving a 64-bit product. c.f. multiplication UM* M/ ( num-64 denom-32 -- quot-32 ) signed floored division with no remainder. To get both the remainder and quotient, use M/MOD. To get just the remainder use MMOD. Note that the unsigned version UM/ is faster than M/. c.f. division, M/MOD MMOD UM/. M/MOD ( num-64 denom-32 -- rem-32 quot-32 ) Signed floored division with both remainder and quotient. The remainder has same sign as divisor. To get just the remainder use MMOD. To get just the quotient use M/. Note that the unsigned version UM/MOD is faster than M/MOD. c.f. division MMOD M/ UM/MOD pronounced "m-mod" \BBL\BBL.DOC -73- last updated 1986 October 14 21:30 BBL Forth Reference MAX ( n1 n2 -- n3 ) n3 larger of signed n1 n2. Code is faster if n1 >= n2. Watch out! 0 MAX is used to corral an expression so that it never gets below 0. In other words 0 MAX sets the LOWER bound on an expression. A very common bug is to get MIN and MAX confused when used in this way. c.f. MIN DMIN DMAX CORRAL pronounced "max" MIN ( n1 n2 -- n3 ) n3 is smaller of signed n1 n2. Code is faster if n1 <= n2 Watch out! 999 MIN is used to corral an expression so that it never gets above 999. In other words 999 MIN sets the UPPER bound on an expression. A very common bug is to get MIN and MAX confused when used in this way. c.f. MAX DMIN DMAX CORRAL pronounced "min" MMOD ( num-64 denom-32 -- rem-32 ) Signed floored division giving just the quotient. In contrast M/MOD gets remainder and quotient. M/ gets just the quotient. Note that the unsigned version UMMOD is faster than MMOD. c.f. division M/MOD M/ UMMOD MOD ( num-32 denom-32 -- rem-32 ) Signed floored division to get the remainder In contrast /MOD gets remainder and quotient. / gets just the quotient. Note that the unsigned version UMOD is faster than MOD. c.f. division /MOD / UMOD QMOD MS ( n -- ) delays n milliseconds (thousandths of a second). This is implemented by a cpu delay loop. BBL wastes n milliseconds of CPU time. For MS to work correctly you must have configured BBL with the correct processor speed. If you wish to do time delays that are independent of processor speed, consider the Abundance verb TICKS which uses the 1/18 second resolution timer interrupts. MSW ( n1 -- n2 ) Most Significant Word. n2 is the most significant 16 bits word of n1 padded on the left with zeros. Note that both n1 and n2 are values on the data stack -- not addresses in RAM. c.f. LSW \BBL\BBL.DOC -74- last updated 1986 October 14 21:30 BBL Forth Reference MU/MOD ( num-64 denom-32 -- rem-32 quot-64 ) Unsigned floored division with a 32-bit remainder and 64-bit quotient. DON'T CONFUSE THIS WITH UM/MOD. UM/MOD gives a 32-bit quotient. UMMOD will get just the remainder, but there is no operator to get just the quotient. There is no signed version of this operator. c.f. division UMMOD UM/MOD **N** words that begin with N N>LINK ( nfa -- lfa ) Not normally used by programmers. Converts nfa (name field address) to lfa (link field address). Once you have the lfa, you must do a LINK@ to get the predecessor's nfa. This link uses the hash threads. c.f. >BODY >NAME >LINK BODY> NAME> LINK> L>NAME PREV- NFA pronounced "name-to-link" NAME> ( nfa -- cfa ) Not normally used by programmers. Converts nfa (name field address) to cfa (code field address). c.f. >BODY >NAME >LINK BODY> LINK> N>LINK L>NAME PREV- NFA pronounced "from-name" NAND ( 32b1 32b2 -- 32b3 ) Logical NAND. b3 is the one's complement of the logical AND of b1 and b2. For example BINARY 0101 1100 NAND is 1011 -- if both bits are 1 the result is 0, If either of the bits is a 0, the result is a 1. Equivalent to but faster than AND NOT. Note that b1 NOT b2 NOT AND is better expressed as b1 b2 NOR and b1 NOT b2 NOT OR is better expressed as b1 b2 NAND. c.f. AND OR NOR XOR NEGATE NOT NAME> ( nfa -- cfa ) converts a name field address to the code field address NEGATE ( n1 -- n2 ) Changes the sign of a value. n2 is the two's complement of n1, i.e. -n1 or difference of zero less n1. The value -231 cannot be properly negated because it +231 cannot be expressed in 32 bits. Thus this value is left unchanged. Note SWAP- is much faster than - NEGATE or SWAP -. In contrast NOT calculates the one's complement. c.f. subtraction, SWAP- ?NEGATE ABS \BBL\BBL.DOC -75- last updated 1986 October 14 21:30 BBL Forth Reference NEXT-NFA ( nfa1 -- nfa2 ) Used to find the word in the compiled into the same vocabulary immediately after the given word. If there is no successor, the result is 0. NEXT-NFA is used in conjunction with EARLIEST-NFA to chase through all the words in a vocabulary. NEXT-NFA does NOT use the hash threads. c.f. EARLIEST-NFA LATEST-NFA PREV-NFA LATEST NIL ( -- ) Does nothing very quickly. It can be used as a do- nothing routine in a CASE or JUMP. Can also be used as ['] NIL to pass a do-nothing routine as a parameter. Do not confuse with NULL X whose real name is a HEX 00 used to terminate interpretation of a screen or the TIB. c.f. NULL X NIP ( n1 n2 -- n2 ) Drops second from top of data stack. Equivalent to but faster than SWAP DROP c.f DROP TUCK SWAP NOR ( 32b1 32b2 -- 32b3 ) Logical NOR. b3 is the one's complement of the logical inclusive OR of b1 and b2. For example BINARY 0101 1100 NAND is 0010. Equivalent to but faster than OR NOT. Note that b1 NOT b2 NOT AND is better expressed as b1 b2 NOR and b1 NOT b2 NOT OR is better expressed as b1 b2 NAND. c.f. OR XOR AND NAND NOT NOT ( 32b1 -- 32b2 ) 32b2 is the one's complement of 32b1. For example BINARY 1010 is 0101 -- every 1 turns into a zero and every 0 turns into a one.. NOT is similar but not identical to 0=. Watch out! In Forth-79 NOT and 0= were synonymous. In Forth-83, only for canonical flags are NOT and 0= synonymous. If you use canonical flags, NOT behaves just like the word "not" in English. Use NEGATE to get the two's complement. c.f. 0= NEGATE NAND NOR \BBL\BBL.DOC -76- last updated 1986 October 14 21:30 BBL Forth Reference NUMBER ( Addr -- d ) converts ascii to binary using the current BASE. At addr there is a counted string (usually at HEREB) that must be followed by a SPACE or HEX 00. NUMBER aborts with an "Undefined" message if invalid characters are found in the string. The string may have a leading minus sign, but not a trailing one. The string may not have any plus signs. NUMBER leaves DPL=-1 if there are no decimals otherwise DPL is the number of digits to the right of the decimal. Nutty as it sounds, though the string must begin with a count, the count byte itself is ignored. This is a tradition from PC Forth Plus. It allow arbitrarily long strings with many lead zeros to be handled properly. Note that the result is always signed double precision. There is no word to give you single precision directly. NUMBER was designed to parse inline literals, and is probably of not too much use generally. c.f. CONVERT NULL ( -- ) real name is hex 0 length 1 alias X. It terminates interpretation of the input stream. this word gets executed at the end of interpreting the TIB or a block. It acts like EXIT terminating INTERPRET. IT DOES NOT PUSH OR EMIT A NULL CHAR! c.f. ;S NIL **O** words that begin with O OFF ( addr -- ) Stores a 32-bit 0 at addr. Equivalent to but faster than 0 SWAP ! c.f. ON 0! ! ERASE ON ( addr -- ) Stores a 32-bit -1 at addr. Equivalent to but faster than -1 SWAP ! c.f. OFF 0! ! \BBL\BBL.DOC -77- last updated 1986 October 14 21:30 BBL Forth Reference ONLY ( -- ) Select the ONLY vocabulary as both the transient vocabulary and the resident vocabulary in the search order. All other vocabularies -- even FORTH are no longer searched. It does not change the CURRENT (DEFINITIONS) vocabulary. When you want to set up a new set of multiple vocabularies to search you would use ONLY like this: ONLY FORTH ALSO EDITOR ALSO HIDDEN DEFINITIONS This would set up the search to first look in HIDDEN, then in EDITOR then in FORTH, then in ONLY. New definitions would be added to the HIDDEN vocabulary. c.f. ALSO FORTH ORDER WORDS FORGET DEFINITIONS SEAL VOCABULARY OPEN-CACHE ( -- ) opens the CACHE file with current CACHE-NAME. DISK- ERROR @ is 0 if ok, 4 if could not open. c.f. USING CLOSE-CACHE CACHE-NAME SAVE-BUFFERS FLUSH EMPTY-BUFFERS DISK-ERROR LAST-SCR OR ( 32b1 32b2 -- 32b3 ) Inclusive logical-or on all 32 bits. b3 is the logical or of b1 and b2. For example BINARY 0101 0011 OR is 0111. In other words, if either bit is is one, the result is a 1. If both bits are 0, the result is a 0. Note that b1 NOT b2 NOT AND is better expressed as b1 b2 NOR and b1 NOT b2 NOT OR is better expressed as b1 b2 NAND. If you use canonical flags, this bit-wise OR behaves just like "and/or" in English. In particular if n1 and n2 are canonical flags (0 or -1) then: true true -- true false true -- true true false -- true false false -- false c.f. XOR NOR AND NAND NOT XOR ORDER ( -- ) Display the vocabulary names forming the search order in their present search order sequence. Then show the vocabulary into which the new definitions will be placed CURRENT (DEFINITIONS). Note this does not show all vocabularies -- just the ones being searched now. c.f. VOCABULARY VOC-LIST CURRENT CONTEXT WORDS FOR- EACH-VOC OVER (32b1 32b2 -- 32b1 32b2 32b3 ) 32b3 is a copy of 32b1. Duplicate 2nd from top of data stack. \BBL\BBL.DOC -78- last updated 1986 October 14 21:30 BBL Forth Reference **P** words that begin with P PW! ( uw port# -- ) writes least significant 2 bytes to an i/o port. I/O ports are numbered 0 .. FFFF. This bypasses DOS and goes directly to the hardware. The address need not be canonical. c.f. PUW@ PC@ PC! PUW@ ( port# -- uw ) reads 2 bytes from an i/o port. I/O ports are numbered 0 .. FFFF. This bypasses DOS and goes directly to the hardware. c.f. PW! PC@ PC! PAD ( -- addr ) The lower address of a scratch area used to hold data for intermediate processing. The address or contents of PAD may change and the data lost if the address of the next available dictionary location is changed. The minimum capacity of PAD is 84 characters. Equivalent to HERE 256 +. Every time you ALLOT the PAD moves. When you use words like <# # and #> the string is built just under the PAD. PC! ( c port# -- ) writes last significant 1 byte to i/o port. I/O ports are numbered 0 .. FFFF. This bypasses DOS and goes directly to the hardware. The address need not be canonical. c.f. PC@ PW! PC! PC@ ( port# -- c ) reads a byte from an i/o port. I/O ports are numbered 0 .. FFFF. This bypasses DOS and goes directly to the hardware. c.f. PC! PUW@ PW! PEMIT ( c -- ) The least-significant 8-bit ASCII character is emitted to the printer printer. PEMIT can be used directly, but more often it is vectored into EMIT via PRINTER. c.f. PRINTER EMIT 'EMIT PTYPE 'TYPE SEMIT STYPE PICK ( +n -- 32b ) 32b is a copy of the +nth data stack value, not counting +n itself. {0 the number of elements on stack-1} 0 PICK is equivalent to DUP 1 PICK is equivalent to OVER \BBL\BBL.DOC -79- last updated 1986 October 14 21:30 BBL Forth Reference PREV-NFA ( nfa1 -- nfa2 ) If nfa1 is the name field address of a word in any vocabulary, then nfa2 will be the name field address of the word compiled just previously in the dictionary. IF nfa2 is 0, this means there is no predecessor. WORDS uses LATEST-NFA and PREV-NFA to chase through all the words in a vocabulary in reverse order, regardless of hash thread. In contrast the lfas refer to the hash threads. Nfa1 must be expressed in such a fashion that the segment portion covers the predecessor nfa2. This requirement should usually come out in the wash without special consideration. c.f. NEXT-NFA LATEST-NFA EARLIEST-NFA WORDS N>LINK LINK@ >LINK LINK> PRINTER ( -- ) redirects EMIT and TYPE output to printer, by setting up the 'EMIT and 'TYPE vectors. PRINTER is defined as: : PRINTER ['] PEMIT 'EMIT ! ['] PTYPE 'TYPE ! ; c.f. CONSOLE EMIT TYPE 'EMIT 'TYPE PEMIT PTYPE PTYPE ( addr len -- ) TYPEs string to printer. w characters are printed from memory beginning with the character at addr and continuing through consecutive addresses. Addr must cover the string and +w must be under 64K. It can be used directly, but normally it is vectored into the TYPE routine via the word PRINTER. c.f. PRINTER TYPE 'TYPE PEMIT **Q** words that begin with Q Q* ( n1-32 n2-32 -- n3-32 ) fast form of * multiplication that works if you can guarantee that n1 and n2 are all in the range 0 .. 65535. Works slightly faster if n1 > n2. c.f. * pronounced "quick-star" or "queue-star" Q/ ( n1-num-32 n2-denom-32 -- n3-quot-32 ) Quick form of / or U/ division that works if you can guarantee that n1 is greater than or equal to 0, that n2 is in the range 1 .. 65535, and n3 is in the range 0..65535. WARNING: Overflow of the quotient over 65535 or division by 0 is a error and will result in an INT 0 divide by zero program crash. c.f. Q/MOD QMOD / U/ pronounced "quick-divide" or "queue-slash" \BBL\BBL.DOC -80- last updated 1986 October 14 21:30 BBL Forth Reference Q/MOD ( n1-num-32 n2-denom-32 -- n3-rem-32 n4-quot-32 ) Quick form of /MOD or U/MOD that works if you can guarantee that n1 is greater than or equal to 0, that n2 is in the range 1 .. 65535, and n3 and n4 are in the range 0..65535. WARNING: Overflow of the quotient over 65535 or division by 0 is a error and will result in an INT 0 divide by zero program crash. c.f. Q/ QMOD /MOD U/MOD pronounced "quick-slash-mod" or "queue-slash-mod" QMOD ( n1-num-32 n2-denom-32 -- n3-rem-32 ) Quick form of MOD or UMOD that works if you can guarantee that n1 is greater than or equal to 0, that n2 is in the range 1 .. 65535, and n3 and n4 are in the range 0..65535. WARNING: Overflow of the implied quotient over 65535 or division by 0 is a error and will result in an INT 0 divide by zero program crash. pronounced "quick-mod" or "queue-mod" QCONSTANT ( 32b -- ) A defining word executed in the form: 32b QCONSTANT <name> Creates a dictionary entry for <name> so that when <name> is later executed, 32b will be left on the data stack. The value must not be a relocatable address. QCONSTANT is used as a quick version of CONSTANT when you can live with the restriction that the value is NOT an absolute address in the program. It can be a number, a relative address, or an absolute address outside the program e.g. in ROM BIOS or DOS. c.f. CONSTANT, ADCON QUERY ( -- ) Gets one line of keyboard input into the TIB. Always goes to the keyboard -- not BLOCK. Characters are received and transferred into the memory area addressed by TIB . The transfer terminates when either a "return" is received or the number of characters transferred reaches the size of the area addressed by TIB . The values of >IN and BLK are set to zero and the value of #TIB is set to the value of SPAN . WORD may be used to accept text from this buffer. c.f. EXPECT input stream pronounced "query" QUIT ( -- ) Clears the return stack, sets interpret state ( [ i.e. STATE OFF), accepts new input from the current input device, and begins text interpretation. No message is displayed. In contrast ABORT also clears the data stack and sets the context vocabulary to FORTH. c.f. ABORT ABORT" RP! SP! \BBL\BBL.DOC -81- last updated 1986 October 14 21:30 BBL Forth Reference QVARIABLE ( -- ) compiling ( -- addr ) exectuting A defining word executed in the form: QVARIABLE <name> This is almost identical to VARIABLE except that the PFA is alloctated in the root segment right after the PFA. This means its pfa has the form CS:offset which can be easily accessed by code words using a simple CS: override rather than having to set up ES for an ES: override. In addition the code at the cfa is inline taking up more space but executing more rapidly than the usual VARIABLE cfa code. If you wish to allocate more space after the pfa you must use ALLOCTC instead of ALLOT. A dictionary entry for <name> is created and four bytes (32 bits) are allotted in its parameter field. This parameter field is to be used for contents of the variable. The application is responsible for initializing the contents of the variable which it creates if it is other than 0. When <name> is later executed, the address of its parameter field is placed on the data stack. Watch out the FORTH-79 used to be 0 VARIABLE X, rather than VARIABLE X. c.f. VARIABLE **R** words that begin with R R0@ ( -- addr ) Gets the address of the base of the return stack. The segment part of his address will always be SS:. Roughly equivalent to R0 @. however for speed and safety we ignore R0. R0 is maintained for reference only ) R> ( -- 32b ) 32b is removed from the return stack and transferred to the data stack. You must always pair >R and R> within a routine. See the dire warnings on its use under the heading Return Stack. c.f. >R R@ RDROP EXIT pronounced "r-from" R@ ( -- 32b ) 32b is a copy of the top of the return stack. It does not disturb the return stack. c.f. >R R> RDROP EXIT pronounced "r-fetch" \BBL\BBL.DOC -82- last updated 1986 October 14 21:30 BBL Forth Reference RDROP ( -- ) drops top element of return stack. See dire warnings under the heading Return Stack. DO NOT PLAY WITH THIS WORD UNLESS YOU ARE PREPARED FOR A SYSTEM CRASH. c.f. >R R> R@ EXIT R2DROP ( -- ) drops top two elements of return stack. See dire warnings under the heading Return Stack. DO NOT PLAY WITH THIS WORD UNLESS YOU ARE PREPARED FOR A SYSTEM CRASH. c.f. RDROP 2DROP R3DROP ( -- ) drops top three elements of return stack. See dire warnings under the heading Return Stack. DO NOT PLAY WITH THIS WORD UNLESS YOU ARE PREPARED FOR A SYSTEM CRASH. c.f. RDROP 3DROP R4DROP ( -- ) drops top four elements of return stack. See dire warnings under the heading Return Stack. DO NOT PLAY WITH THIS WORD UNLESS YOU ARE PREPARED FOR A SYSTEM CRASH. c.f. RDROP 4DROP REBUILD-VOC ( -- ) rebuilds the CURRENT (DEFINITIONS) vocabulary dictionary region. It first allocates a chunk of space equal to the contents of the VOC-SIZE variable for the new vocabulary region. Then it decides on the optimal number of hashing threads for a dictionary of that size, then in rebuilds the vocabulary headers. You do this if one of your vocabularies is getting full or is getting sluggish at searching. Normally you increase VOC-SIZE before using REBUILD-VOC. Once you find he optimal sizes of your vocabularies, you can set VOC- SIZE just prior to defining the vocabulary in the first place. This is much more efficient because the old dictionary space is not reclaimed unless you do it yourself through some heroic effort. REBUILD-VOC is also used to rebuild the FORTH vocabulary at startup. This is done because Microsoft assembler is not smart enough to directly generate the code for a multi-thread dictionary. If you closely examine the BBL source listings you will see that FORTH is built as a multithread dictionary, but there is only one thread! c.f. VOCABULARY VOC-SIZE \BBL\BBL.DOC -83- last updated 1986 October 14 21:30 BBL Forth Reference RECURSE ( -- ) If you want to recursively call the routine you are defining you use the word RECURSE instead of the true name of the routine. If you used the true name of the routine you would get the OLD version (if any) of the same routine. In older Forth versions this was called MYSELF. e.g. : FACTORIAL ( n -- : computes N factorial ) DUP 1 > IF DUP 1- RECURSE * ELSE DROP 1 THEN ; c.f. SMUDGE UNSMUDGE REL> ( 32-bit relative address -- absolute SEG:OFF) convert a relative address to address to an absolute canonical one with the offset in the range 0..15. It really only useful on addresses in the pfa part of the dictionary or on addresses outside the program. It does not cleverly handle addresses in the code segment to make them have a segment equal to CS:. Neither does it handles addresses in the stack segment to make them have a segment equal to SS:. Neither does it handle addresses in the vocabulary segments to make them have segments equal to the start of the vocabulary region. See the warning about comparing addresses. c.f. >REL >REL> pronounced "from-relative REPEAT ( -- ) ( back-addr 1 -- ) (compiling) Used in the form: BEGIN ... flag WHILE ... REPEAT At execution time, REPEAT continue. c.f. BEGIN WHILE UNTIL ROLL ( +n -- ) The +nth data stack value, not counting +n itself is first removed and then transferred to the top of the data stack, moving the remaining values into the vacated position. {0..the number of elements on the data stack-1) 2 ROLL is equivalent to ROT 1 ROLL is equivalent to SWAP 0 ROLL is a null operation ROT ( 32b1 32b2 32b3 -- 32b2 32b3 32b1 ) The top three data stack entries are rotated, bringing the deepest to the top. c.f. -ROT 2ROT pronounced "rote" \BBL\BBL.DOC -84- last updated 1986 October 14 21:30 BBL Forth Reference RP! ( -- ) DO NOT USE THIS WORD UNLESS YOU REALLY KNOW WHAT YOU ARE DOING. Clears the return stack. Unlike PC Forth Plus RP! does not expect R0 on the data stack. For safety and speed we ignore R0. c.f. QUIT ABORT RP@ ( -- addr ) address of the current top of the return stack. Note address returned is not canonical because the segment portion is always equal to SS:. **S** words that begin with S S0@ ( -- addr ) The address of the RAM base of the data stack. This is roughly equivalent to S0 @ However, for speed and safety we ignore S0. S0 is maintained for reference only. Note address returned is not canonical because the segment portion is always SS: S= ( addr1 addr2 length -- FLAG ) Compares two strings. The flag is true if strings equal. Length is under 64K. The addresses need not be canonical but they must cover both ends of the strings. The length may also be 0 or 1, but not negative. The addresses need not be canonical. Two zero length strings will always compare as equal. S>D ( n -- d ) converts single to double precision by sign extending. If n is known to be positive a faster way of doing this is to push a 0 to the data stack. By convention, when you use this short form write 0 ( S>D ). c.f. 0 D>S SAVE-BUFFERS ( -- ) The contents of all block buffers marked as Updated are written to their corresponding mass storage blocks. All buffers are marked as no longer being modified, but remain assigned. BBL remembers the contents of the buffers in contrast to FLUSH which does not. c.f. EMPTY-BUFFERS FLUSH pronounced "save-buffers" \BBL\BBL.DOC -85- last updated 1986 October 14 21:30 BBL Forth Reference SCAN ( addr len char -- index, true: if found.) ( addr len char -- false : if not found) scan string left to right searching for char. The left most character is index 0. If the length of the string is 0, SCAN will always return false. The len may be 0..64K but not negative. Addr need not be canonical but it must cover both ends of the string. c.f. <SCAN WSCAN SEARCH <SEARCH SEAL ( -- ) Delete all occurrences of ONLY from the search order. The effect is that only specified application dictionaries will be searched. You can use it to keep users out of your private vocabularies, but give them free reign to use others. The tiny ONLY vocabulary contains the keys to the general vocabulary switching mechanism. You use it like this: ONLY PUBLIC ALSO PUBLIC2 SEAL to lock the user forever into using just the PUBLIC and PUBLIC2 vocabularies. SEARCH ( addr1 len1 addr2 len2 -- offset true if found) ( addr1 len1 addr2 len2 -- false if not found ) Searches string-1 for the first occurrence of string2. Searches left to right. Addr1 need not be canonical but is must cover both ends of string-1. Addr2 need not be canonical but is must cover both ends of string- 2. Either or both of len1 and len2 may be 0. ??? Later documentation will be inserted to define results for zero length strings. c.f. <SEARCH SCAN <SCAN WSCAN SEMIT ( char -- ) emits char to screen. Usually EMIT is vectored to SEMIT via CONSOLE which does ['] SEMIT 'EMIT !. If EMIT is vectored to PEMIT the printer, you can still get at the screen with SEMIT. SEMIT does not bypass DOS. Thus it is slow, but it can be redirected with DOS C:> commands on the command line. If you want high speed screen painting you must use the S! verbs in the Abundance compiler than bypass DOS and get at the hardware directly c.f. EMIT PEMIT 'EMIT CONSOLE STYPE PTYPE 'TYPE SHIFT ( n1 p -- n2 ) Shift n1 by p bits. Multiplies n1 by 2**p with a logical unsigned shift. p>0 shifts left, p<0 shifts right logically. c.f. multiplication division * 2* 4* 8* 10* 16* 64* 256* 2/ D2/ D2* \BBL\BBL.DOC -86- last updated 1986 October 14 21:30 BBL Forth Reference SIGN ( n -- ) If n is negative, an ASCII "-" (minus sign) is appended to the pictured numeric output string, otherwise does nothing. Typically used between <# and #>. Typically the sign is hidden on the return stack during conversion then popped out at the last moment for SIGN. c.f. <# # SIGN #> SIXTEEN ( -- 16 ) no matter what BASE is, you always get a decimal 16. c.f. 10 TEN SMUDGE ( -- ) Not normally used by programmers. Makes LATEST definition invisible in the search order by setting the smudge bit in the nfa. Done by Colon to temporarily hide a definition until it is finished. Watch out in Forth-79 SMUDGE toggled the smudge bit instead of setting it. c.f. UNSMUDGE SP! ( -- ) clears data stack. Unlike SP!in PC Forth Plus, SP! does not expect S0 on the data stack!!!. For safety and speed we ignore S0. Changing the value of S0 will have no effect on the next SP!. SP@ ( -- addr ) addr is the address of the current top of the RAM-based data stack just before SP@ was executed. NOTE this points actually to second from top of logical stack as actual. The top of data stack is kept in a register pair CX:BX. See notes under DATA STACK in BBLDOC.ASM. Note address returned is NOT canonical because the segment portion is always SS: SPACE ( -- ) Displays an ASCII space. Equivalent to BL EMIT. SPACES ( +n -- ) Displays +n ASCII spaces. Nothing is displayed if +n is zero. N cannot be negative. SPAN ( -- addr ) A variable containing the count of characters actually received and stored by the last execution of EXPECT not counting the return or hex 00 null. SPAN is not used internally by BBL. c.f. EXPECT \BBL\BBL.DOC -87- last updated 1986 October 14 21:30 BBL Forth Reference STATE ( -- addr ) A variable that keeps track of whether BBL should compile or execute the next word. True if compiling (i.e. in middle of a colon definition). More precisely STATE is a variable containing the compilation state. A -1 content indicates compilation is occurring (we are in the middle of compiling a colon definition), a 0 content indicates that execution (sometimes called "interpreting") is occurring. A standard program may not directly modify this variable. STREAM ( -- addr ) Not normally used by programmers. Get the next char in either input stream (BLK or TIB). Does NOT increment >IN. Just uses >IN to offset into the block. We cannot simply set BLOCK up once at LOAD time because there might be LIST commands in the block that could ruin the buffer.. We thus must call STREAM before each word is parsed. The main user of STREAM is WORD. STYPE ( addr len -- ) TYPEs string to screen. +len characters are displayed from memory beginning with the character at addr and continuing through consecutive addresses. Nothing is displayed if +n is zero. Addr must cover the string and +w must be under 64K. STYPE can be used on its own, but normally TYPE is vectored to STYPE via CONSOLE which does ['] STYPE 'TYPE !. Note that STYPE does not bypass DOS in any way. Thus is is slow as molasses, but can be redirected via DOS C:> command line prompts. If you are serious about quick screen I/O you must use the SCMOVE SVCMOVE etc verbs in the Abundance compiler than get at the video hardware directly bypassing DOS. SWAP ( 32b1 32b2 -- 32b2 32b1 ) The top two data entries are exchanged. SWAP- ( a b -- b-a ) does SWAP then subtract. Surprisingly SWAP- is faster than plain -. c.f. NEGATE - SWAP pronounced "swap-minus" \BBL\BBL.DOC -88- last updated 1986 October 14 21:30 BBL Forth Reference SWEEP ( -- addr ) variable that controls the optimization algorithm used by BLOCK and BUFFER. If SWEEP=0 a standard round robin algorithm will be used that works well for random accesses all over the screens. If SWEEP=1 then the algorithm will be modified for passing the screens sequentially. If SWEEP=-1 then the algorithm will be modified for passing the screens sequentially but in reverse order. Note that DOS passes screens in reverse order very slowly because of its internal FAT tables. To find the 500th cluster of a file, DOS will chase down a chain in the FAT table 500 links long. However if you have just accessed the 500th cluster, DOS remembers its place in the chain, so if you then ask for the 501st cluster it can find it in one jump. But if you ask for the 499th cluster, it has to start at the top and chase down all 499 links. For this reason DOS has reasonably good performance if files are processed sequentially but utterly abysmal performance if you ask it to process large files in reverse. SWEEP cannot do a thing about this. All it can do is manage the internal FORTH buffers more efficiently. When sweep is 1, and you access screen N with BLOCK, it will preferentially steal the buffer with screen N-1 in it - - even though it way very recently used. DOS is still far from optimal on handling sequential i/o. It should read several screen ahead while your program continues to process. If you update a screen, the write should be done right away before you have moved the disk heads away. Again there is nothing I can do about these DOS internal problems. c.f. BLOCK BUFFER OPEN-CACHE CLOSE-CACHE CACHE-HANDLE CACHE-NAME SAVE-BUFFERS FLUSH EMPTY-BUFFERS LAST-SCR **T** words that begin with T T! ( value address -- ) Stores low order 3 bytes of value at address. Works on both signed and unsigned quantities. Value is MSW on top of the data stack, LSW first in memory. Address is seg:offset -- not necessarily canonical c.f. T@ UT@ ! pronounced "t-bang" T@ ( addr -- value ) fetches 3 bytes - with sign extend. Value is MSW on top of the data stack, LSW first in memory. c.f. UT@ T! @ \BBL\BBL.DOC -89- last updated 1986 October 14 21:30 BBL Forth Reference TASK ( -- ) does nothing -- last word in dictionary. Often used in form : TASK ; ... FORGET TASK TEN ( -- 10 ) no matter what BASE is, you always get a decimal 10. c.f. 10 SIXTEEN THEN ( -- : executing ) ( backaddr 2 : compiling ) Used in the form: flag IF ... ELSE ... THEN or flag IF ... THEN THEN is the point where execution continues after ELSE, or IF when no ELSE is present. In earlier versions of Forth THEN was sometimes called ENDIF. For a long while there was a battle between the logicians who thought ENDIF more closely described this function, and the people who hate typing who like the nice short THEN. The THEN folks finally prevailed. If you want old ENDIF back: ' THEN ALIAS ENDIF IMMEDIATE c.f. IF ELSE THRU ( n1 n2 -- ) Load multiple screens. Loads screen n1 then n1+1 then ... up to n2. You have to decide on a method --> which are embedded on the screens or using THRU. You cannot mix them. c.f. LOAD TIB ( -- addr ) The address of the text input buffer. This buffer is used to hold characters when the input stream is coming from the current input device. The capacity of TIB is 132 characters. pronounced "t-i-b" TOGGLE ( addr 8-bit-mask -- ) Toggles the bits in the byte at addr using the mask. Only the bits corresponding to ones in the mask get toggled. Toggling means changing all ones to zeros and all zeros to ones. Effectively does a C@ of the addr, then XOR with the mask then C!. Most commonly used to turn or or off the IMMEDIATE bit in the nfa. c.f. XOR SMUDGE UNSMUDGE \BBL\BBL.DOC -90- last updated 1986 October 14 21:30 BBL Forth Reference TOKEN! ( cfa addr2 -- ) store the cfa as a 16-bit token at addr2. . The cfa must either me a standard cfa with the segment portion equal to CS: or a relative address. Addr2 is not necessarily canonical, but is usually at an even address. The actual code for TOKEN! is the same as the code for W!, but we use TOKEN! in preference to make it clear we are storing a token. This will make it easier to modify the code later if ever the tokenizing scheme is changed. c.f. TOKEN@ TOKEN, W! @ pronounced "token-bang" TOKEN, ( cfa --- ) Compiles the cfa as a 16-bit token into the pfa portion of the dictionary. . The cfa must either me a standard cfa with the segment portion equal to CS: or a relative address. Addr2 is not necessarily canonical, but is usually at an even address. The actual code for TOKEN, is the same as the code for W, but we use TOKEN, in preference to make it clear we are compiling a token. This will make it easier to modify the code later if ever the tokenizing scheme is changed. c.f. TOKEN! TOKEN@ W, pronounced "token-comma" TOKEN@ ( addr1 -- cfa ) fetches 16-bit token and fluffs it up to an absolute address by prefixing the offset with a segment equal to CS:. Note this is not synonymous with W@. c.f. TOKEN! TOKEN, TRIM-NUM ( D -- D or n ) trims double to single if DPL=-1. Used by INTERPRET after NUMBER to handle literals. TUCK ( n1 n2 -- n2 n1 n2 ) duplicates the top of the data stack and squirrels it away deep in the data stack. Equivalent to but faster than DUP ROT ROT c.f. NIP DUP ROT TUCK \BBL\BBL.DOC -91- last updated 1986 October 14 21:30 BBL Forth Reference TYPE ( addr +w -- ) +w characters are displayed from memory beginning with the character at addr and continuing through consecutive addresses. Nothing is displayed if +n is zero. Addr must cover the string and +w must be under 64K. TYPE can be redirected to the screen with CONSOLE or to the printer with PRINTER. TYPE is defined as an optimized version of : TYPE 'TYPE @ EXECUTE ; Thus you can redirect TYPE by providing your own type routine and vectoring it in with ['] MY-TYPE 'TYPE !. Normally when you redirect TYPE you also redirect EMIT. c.f. 'TYPE CONSOLE PRINTER STYPE PTYPE EMIT 'EMIT SEMIT PEMIT GTYPE. **U** words that begin with U U. ( u -- ) u is displayed as an unsigned number in a free-field format. pronounced "u-dot" U. ( u --- : prints a 32-bit unsigned number followed by a space ) U.R ( u +n -- ) u is converted using the value of BASE and then displayed as an unsigned number right aligned in a field +n characters wide. If the number of characters required to display u is greater than +n, an error condition exists. c.f. number conversion pronounced "u-dot-r" U/ ( num-32 denom-32 -- quot-32 ) Unsigned floored division giving just the quotient. To get the remainder as well use U/MOD. To get just the remainder use UMOD. The slower signed version is called /. c.f. division U/MOD UMOD / pronounced "u-slash" U/MOD ( num-32 denom-32 -- rem-32 quot-32 ) Unsigned floored division. To get just the remainder use UMOD. To get just the quotient use U/. The slower running signed version is called /MOD. c.f. division Q/MOD UMOD U/ /MOD pronounced "u-slash-mod" \BBL\BBL.DOC -92- last updated 1986 October 14 21:30 BBL Forth Reference U< ( u1 u2 -- flag ) flag is true is u1 is less than u2 using unsigned compares. See the warning about comparing addresses. c.f. < U<= D< <= > U> D> >= = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "u-less-than" U<= ( u1 u2 -- flag ) flag is true is u1 is less or equal to u2 using unsigned compares. See the warning about comparing addresses. c.f. <= U<= D< < > U> D> >= = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "u-less-or-equal" U> ( u1 u2 -- flag ) true if u1 is greater than n2 using unsigned compares. See the warning about comparing addresses. c.f. < U< D< <= > D> >= = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "u-greater" U>= ( u1 u2 -- flag ) true if u1 is greater than or equal to n2 using unsigned compares. See the warning about comparing addresses. c.f. >= < U< D< <= > D> = D= <> MIN MAX NOT 0< 0<= 0> 0>= 0= D0= 0<> AND NAND OR NOR XOR NEGATE pronounced "u-greater-or-equal" UM* ( u1 u2 -- ud : 32-bit * 32-bit = 64-bit unsigned ) ud is the unsigned product of u1 times u2. All values and arithmetic are unsigned. pronounced "u-m-star" UM/ ( num-64 denom-32 -- quotient-32 : unsigned floored division ) To get both the remainder and quotient use UM/MOD. To get just the remainder use UMMOD. The slower-running signed version is called M/. c.f. division UM/MOD UMMOD M/ pronounced "u-m-slash" UM/MOD ( num-64 denom-32 -- rem-32 quot-32 unsigned floored division ) DON'T CONFUSE THIS WITH MU/MOD which gives 64-bit quotient. To get just the remainder use UMMOD. To get just the quotient, use UM/. The slower-running signed version is called M/MOD. c.f. division UMMOD UM/ M/MOD pronounced "u-m-divide-mod" \BBL\BBL.DOC -93- last updated 1986 October 14 21:30 BBL Forth Reference UM/MOD-OVL ( num-64 denom-32 -- rem-32 quot-32 unsigned floored division ) Handles overflow case for UM/MOD. Not normally called directly but will work faster than UM/MOD if you know there will be overflow. To get just the remainder use UMMOD. To get just the quotient, use UM/. The slower-running signed version is called M/MOD. c.f. division UMMOD UM/ M/MOD pronounced "u-m-slash-mod-oval" UMOD ( num-32 denom-32 -- rem-32) uses unsigned floored division to get the remainder. To get both the remainder and quotient use U/MOD. To get just the quotient use U/. Note that UMOD is faster than the signed version called MOD. c.f. division MOD QMOD U/MOD U/ MOD. uncreate ( -- ) Not normally used by programmers. Unallots the code at the cfa put there by CREATE so that some other code can be put there instead. CREATE places an 11-byte inline cfa. UNSMUDGE ( -- ) makes the latest definition visible by clearing the smudge bit in the nfa. CREATE does a built-in UNSMUDGE. Colon SMUDGEs the current definition name and semicolon UNSMUDGEs it. UNTIL ( flag -- ) ( BEGIN addr 1 UNTIL --) ( compiling ) Used in the form: BEGIN ... flag UNTIL Marks the end of a BEGIN-UNTIL loop which will terminate based on flag. If flag is true, the loop is terminated. If flag is false, execution continues to just after the corresponding BEGIN. A BEGIN-UNTIL loop runs at least once. In contrast a BEGIN WHILE REPEAT loop may execute the loop zero times. c.f. BEGIN WHILE REPEAT. UPDATE ( -- : marks most recently BLOCKed buffer as changed/dirty) The currently valid block buffer is marked as modified. Blocks marked as modified will subsequently be automatically transferred to mass storage should its memory buffer be needed for storage of a different block or upon execution of FLUSH or SAVE-BUFFERS. \BBL\BBL.DOC -94- last updated 1986 October 14 21:30 BBL Forth Reference USING ( used in form USING C:\BBL\FORTH.BLK ) FLUSHes the current cache buffers and closes the cache file. Then it reopens it with the given external DOS file name. c.f. CACHE-NAME OPEN-CACHE CLOSE-CACHE BLOCK BUFFER EMPTY-BUFFERS FLUSH SAVE-BUFFERS LAST-SCR UT@ ( addr -- ut ) fetches 3-byte 24-bit unsigned value stored it RAM at addr with no sign extension. The value stored least significant byte first in memory. T! is used to store both signed and unsigned 24-bit quantities. c.f. T@ T! @ UW@ ( addr -- uw ) fetches 2-byte 16-bit unsigned value stored in RAM at addr with no sign extension. The value stored least significant byte first in memory. W! is used to store both signed and unsigned 16-bit quantities. c.f. W@ W! @ **V** words that begin with V VARIABLE ( -- ) A defining word executed in the form: VARIABLE <name> A dictionary entry for <name> is created and four bytes (32 bits) are allotted in its parameter field. This parameter field is to be used for contents of the variable. The application is responsible for initializing the contents of the variable which it creates if it is other than 0. When <name> is later executed, the address of its parameter field is placed on the data stack. Watch out the FORTH-79 used to be 0 VARIABLE X, rather than VARIABLE X. c.f. QVARIABLE VOC-LINK ( --- addr ) a variable that contains the head of the VOC-LINK chain. This chain threads all the vocabularies together independently of the current search order. VOC-LINK @ points to the back pointer in the newest vocabulary. VOC-LINK @ 4- points to the pfa of the newest vocabulary. c.f. FOR-EACH-VOC VOCABULARY \BBL\BBL.DOC -95- last updated 1986 October 14 21:30 BBL Forth Reference VOC-LIST ( -- ) lists all possible vocabularies along with a few facts about them. This list includes vocabularies not currently being searched. In contrast ORDER shows only those vocabularies currently being searched. c.f. VOCABULARY ORDER FOR-EACH-VOC VOC-SIZE ( -- addr ) The name of a variable that contains the size in bytes to allocate to newly created vocabulary regions. You must set the VOC-SIZE before you define the new vocabulary e.g. 2048 VOC-SIZE ! VOCABULARY MY-VOC VOC-SIZE is also used by REBUILD-VOC to determine the new size of a rebuilt existing vocabulary. The maximum size a vocabulary can have is 65520 bytes, and the minimum size is 96 bytes. VOC-SIZE must be a multiple of 16. If for any reason you violate these constraints, VOC-SIZE will be automatically adjusted to a reasonable value just prior to creating a new vocabulary. Note that the vocabulary region contains only the names of words, -- not their definitions. The vocabulary region contains the nfas (name field addresses) and lfas (link field addresses) and hashing threads. The pfas (parameter field addresses) forming the body of the definition goes in a different segment. The cfas (code field addresses) go in yet another segment. In practice then the 65520 byte limit per vocabulary should never cause a problem. As well as determining the size of the area reserved for the vocabulary storage region, VOC-SIZE indirectly determines the number of hashing threads. The more hashing threads the faster the compilation because there are fewer words on each thread to search during a FIND. The number of hashing threads is calculated by dividing the VOC-SIZE by 10 then rounding up to the next power of 2 e.g. 16, 32, 64, ... 4096. Finally the number of threads in corralled to a value between 16 and 4096. c.f. VOCABULARY REBUILD-VOC HERER \BBL\BBL.DOC -96- last updated 1986 October 14 21:30 BBL Forth Reference VOCABULARY ( -- ) ( VOCABULARY XX -- : create a new vocabulary ) Run time code when the new vocabulary e.g. EDITOR executes it makes this vocabulary the first context vocabulary searched for words. It does not effect the resident context or the CURRENT vocabulary where new definitions are placed. New vocabularies are not usually IMMEDIATE, unless you append the word IMMEDIATE. New vocabularies are usually placed in the ONLY vocabulary e.g. ONLY DEFINITIONS VOCABULARY MY- VOC. If you want a legalistic definition, VOCABULARY is a defining word executed in the form: VOCABULARY <name> A dictionary entry for <name> is created which specifies a new ordered list of word definitions. Subsequent execution of <name> replaces the first vocabulary in the search order with <name>. When <name> becomes the compilation vocabulary new definitions will be appended to <name>'s list. c.f. DEFINITIONS CURRENT CONTEXT ONLY ALSO FOR-EACH- VOC VOC-LINK **W** words that begin with W W! ( 16b address -- ) Stores low order 16 bits at address. Value is MSW on top of the data stack, LSW first in memory. Address is seg:offset -- not necessarily canonical. Works on both signed and unsigned quantities. c.f. W@ UW@ ! pronounced "w-bang" W, ( w --- ) Compiles a 16-bit value into pfa dictionary. c.f. , W,C W,C ( w --- ) Not normally used by programmers. Compiles a 16-bit value into cfa dictionary. The only time you would use this word is if you were generating assembler code. W>< ( n1 -- n2) n2 is n1 with high and low 16-bit words swapped. c.f. >< \BBL\BBL.DOC -97- last updated 1986 October 14 21:30 BBL Forth Reference W@ ( addr -- value-16bits ) fetches 2 bytes - sign extended. Value is MSW on top of the data stack, LSW first in memory. UW@ does not sign extend. Thus W@ is used for signed quantities and UW@ for unsigned ones. W! is used to store both signed and unsigned 16-bit quantities. c.f. UW@ W! @ WHILE ( flag -- ) ( BEGIN addr 1 WHILE addr 4 REPEAT) (compiling) used in the form: BEGIN ... flag WHILE ...REPEAT Selects conditional execution based on flag. When flag is true, execution continues to just after the WHILE through to the REPEAT which then continues execution back to just after the BEGIN. When flag is false, execution continues to just after the REPEAT, exiting the control structure. In this implementation LEAVE cannot be used to EXIT a BEGIN WHILE REPEAT loop. c.f. BEGIN REPEAT UNTIL. WORD ( char -- addr ) Parses next word in the input stream. Generates a counted string by non-destructively accepting characters from the input stream until the delimiting character char is encountered or the input stream is exhausted. Leading delimiters are ignored. The entire character string is stored in memory beginning at addr (built at HEREB not HERE) as a sequence of bytes. The string is followed by a blank which is not included in the count. The first byte of the string is the number of characters {0..255}. If the string is longer than 255 characters, the count is unspecified. If the input stream is already exhausted as WORD is called, then a zero length character string will result. If the delimiter is not found the value of >IN is the size of the input stream. If the delimiter is found >IN is adjusted to indicate the offset to the character following the delimiter. #TIB is unmodified. The counted string returned by WORD resides at HEREB in the vocabulary region not at HERE -- all ready to be converted to an NFA, but it is not ready to be converted to an inline literal until it is moved to HERE. c.f. ENCLOSE BLK >IN \BBL\BBL.DOC -98- last updated 1986 October 14 21:30 BBL Forth Reference WORDS ( -- ) Display the word names in the CONTEXT transient vocabulary, starting with the most recent definition. It prints out the words in just one vocabulary -- not all the vocabularies in the current search order. The display can be paused by hitting Ctrl-Numlock. The display can be interrupted by hitting any other key. Usually used in the form: MY-VOC WORDS c.f. ORDER VOC-LIST VOCABULARY FOR-EACH-VOC WSCAN ( addr len w -- index of found WORD, true: if found ) ( addr len w -- false : if not found ) Scans string left to right searching for 16-bit w. Left most WORD is index 0, next is 1. i.e. offsets and counts in words not bytes. c.f. SCAN SCAN<> **X** words that begin with X XOR ( n1 n2 -- exclusive-or on all 32 bits ) b3 is the exclusive logical or of b1 and b2. For example BINARY 1100 0101 XOR is 1001 i.e. the result is 0 where the bits match and 1 where they differ. If you use canonical flags, this bit-wise XOR behaves just like "or ... but not both" in English. In particular if n1 and n2 are canonical flags (0 or -1) then: true true -- false false true -- true true false -- true false false -- false If you are comparing canonical flags, XOR is a faster equivalent to <>. XOR has a magical property useful in encryption. If K is a secret key, and M is a message then M K XOR is a scrambled version of that message. To descramble the message you simply K XOR again and out pops M. For doubly linked lists you need to store both forward and backward pointers. But if you are short of space, you can store both pointers in the same slot by storing the XOR of the forward and back pointers. You can then reconstruct the forward pointer by XORing with the known back pointer and visa versa. Xor has the following properties: A xor A = 0 A xor B = B xor A A xor -1 = not A A xor 0 = A c.f. <> OR NOR AND NAND NOT pronounced "x-or" \BBL\BBL.DOC -99- last updated 1986 October 14 21:30 BBL Forth Reference **Y** words that begin with Y **Z** words that begin with Z **[** words that begin with [ [ ( -- : suspend compilation ) Sets interpret state. The text from the input stream is subsequently interpreted i.e. we are effectively executing not compiling a colon definition. Implemented as STATE OFF Most often used in the form [ x y + ] LITERAL to evaluate expressions at compile time to literals. c.f. ] STATE pronounced "left-bracket" ['] ( -- cfa ) ( -- ) (compiling) Used in the form: ['] <name> Compiles the compilation address addr of <name> as a literal. When the colon definition is later executed the cfa is left on the data stack. An error condition exists if <name> is not found in the currently active search order. When you are outside a colon definition you have to use ' <name> instead. I.e. Use : X ['] Y EXECUTE ; and ' Y EXECUTE outside colon definitions. Warning! in Forth79 ' was STATE-smart and returned the pfa instead of the cfa. c.f. LITERAL ' EXECUTE PERFORM pronounced "bracket-tick" [COMPILE] ( -- ) ( -- ) (compiling) Used in the form: [COMPILE] <name> Forces compilation of the following word <name>. This allows immediate compilation of an immediate word when it would otherwise have been executed. Usually found in the definition of a new immediate word that is a variant of some existing immediate word -- e.g. a new kind of IF that does the same thing as the old IF but a little bit extra. c.f. COMPILE [ ] IMMEDIATE pronounced "bracket-compile" \BBL\BBL.DOC -100- last updated 1986 October 14 21:30 BBL Forth Reference \ ( -- ) The rest of line is treated as a comment. Must be followed by at least one blank. Can only be used on screens, not when keying directly. c.f. ( ) **]** words that begin with ] ] ( - : resume compilation ) Sets compilation state. The text from the input stream is subsequently compiled. I.e. we are effectively back inside a colon definition. Implemented as STATE ON. Most often used in the form [ x y + ] LITERAL to evaluate expressions at compile time to literals. c.f. [ STATE pronounced "right-bracket" **^** words that begin with ^ **_** words that begin with _ _ ( -- ) at compile time ( -- c ) at run time. Used to create character literals. _ A compiles the constant 65. At run time, the literal is placed on the stack. _ is a synonym for ASCII. A state-smart literal that can be used inside or outside colon definitions. c.f. ASCII **`** words that begin with ` **{** words that begin with { **|** words that begin with | **}** words that begin with } **~** words that begin with ~ \BBL\BBL.DOC -101- last updated 1986 October 14 21:30