--- gforth/Attic/gforth.ds 1995/01/10 18:57:43 1.4 +++ gforth/Attic/gforth.ds 1995/02/22 18:40:15 1.11 @@ -428,9 +428,9 @@ unwary (e.g., floating point addition is for the wary. You should not use them unless you know what you are doing or you don't care that the results you get are totally bogus. If you want to learn about the problems of floating point numbers (and how to -avoid them), you might start with @cite{Goldberg, What every computer -scientist should know about floating-point numbers, Computing Surveys -?}. +avoid them), you might start with @cite{David Goldberg, What Every +Computer Scientist Should Know About Floating-Point Arithmetic, ACM +Computing Surveys 23(1):5@minus{}48, March 1991}. doc-f+ doc-f- @@ -449,6 +449,7 @@ doc-fexpm1 doc-fln doc-flnp1 doc-flog +doc-falog doc-fsin doc-fcos doc-fsincos @@ -606,6 +607,9 @@ The standard guarantees that addresses r are cell-aligned; in addition, gforth guarantees that these addresses are aligned for all purposes. +Note that the standard defines a word @code{char}, which has nothing to +do with address arithmetic. + doc-chars doc-char+ doc-cells @@ -624,6 +628,10 @@ doc-dfloats doc-dfloat+ doc-dfalign doc-dfaligned +doc-maxalign +doc-maxaligned +doc-cfalign +doc-cfaligned doc-address-unit-bits @node Memory block access, , Address arithmetic, Memory access @@ -800,11 +808,11 @@ Therefore we recommend avoiding using @c @var{n}. One alternative is @code{@var{n} S+LOOP}, where the negative case behaves symmetrical to the positive case: -@code{-2 0 ?DO i . -1 +LOOP} prints @code{0 -1} +@code{-2 0 ?DO i . -1 S+LOOP} prints @code{0 -1} -@code{-1 0 ?DO i . -1 +LOOP} prints @code{0} +@code{-1 0 ?DO i . -1 S+LOOP} prints @code{0} -@code{ 0 0 ?DO i . -1 +LOOP} prints nothing +@code{ 0 0 ?DO i . -1 S+LOOP} prints nothing The loop is terminated when the border between @var{limit@minus{}sgn(n)} and @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS @@ -877,14 +885,14 @@ doc-next doc-leave doc-?leave doc-unloop -doc-undo +doc-done The standard does not allow using @code{cs-pick} and @code{cs-roll} on @i{do-sys}. Our system allows it, but it's your job to ensure that for every @code{?DO} etc. there is exactly one @code{UNLOOP} on any path through the definition (@code{LOOP} etc. compile an @code{UNLOOP} on the fall-through path). Also, you have to ensure that all @code{LEAVE}s are -resolved (by using one of the loop-ending words or @code{UNDO}). +resolved (by using one of the loop-ending words or @code{DONE}). Another group of control structure words are @@ -1037,7 +1045,8 @@ locals are initialized with values from Currently there is no way to define locals with user-defined data structures, but we are working on it. -GNU Forth allows defining locals everywhere in a colon definition. This poses the following questions: +GNU Forth allows defining locals everywhere in a colon definition. This +poses the following questions: @menu * Where are locals visible by name?:: @@ -1496,7 +1505,12 @@ locals wordset. @node Programming Tools, Threading Words, Other I/O, Words @section Programming Tools -@node +@menu +* Debugging:: Simple and quick. +* Assertions:: Making your programs self-checking. +@end menu + +@node Debugging, Assertions, Programming Tools, Programming Tools @subsection Debugging The simple debugging aids provided in @file{debugging.fs} @@ -1516,7 +1530,9 @@ query-replace them with nothing). The de @code{printdebugdata} and @code{printdebugline} control the output of @code{~~}. The default source location output format works well with Emacs' compilation mode, so you can step through the program at the -source level using @kbd{C-x `}. +source level using @kbd{C-x `} (the advantage over a stepping debugger +is that you can step in any direction and you know where the crash has +happened or where the strange data has occurred). Note that the default actions clobber the contents of the pictured numeric output string, so you should not use @code{~~}, e.g., between @@ -1526,9 +1542,65 @@ doc-~~ doc-printdebugdata doc-printdebugline -@node +@node Assertions, , Debugging, Programming Tools @subsection Assertions +It is a good idea to make your programs self-checking, in particular, if +you use an assumption (e.g., that a certain field of a data structure is +never zero) that may become wrong during maintenance. GForth supports +assertions for this purpose. They are used like this: + +@example +assert( @var{flag} ) +@end example + +The code between @code{assert(} and @code{)} should compute a flag, that +should be true if everything is alright and false otherwise. It should +not change anything else on the stack. The overall stack effect of the +assertion is @code{( -- )}. E.g. + +@example +assert( 1 1 + 2 = ) \ what we learn in school +assert( dup 0<> ) \ assert that the top of stack is not zero +assert( false ) \ this code should not be reached +@end example + +The need for assertions is different at different times. During +debugging, we want more checking, in production we sometimes care more +for speed. Therefore, assertions can be turned off, i.e., the assertion +becomes a comment. Depending on the importance of an assertion and the +time it takes to check it, you may want to turn off some assertions and +keep others turned on. GForth provides several levels of assertions for +this purpose: + +doc-assert0( +doc-assert1( +doc-assert2( +doc-assert3( +doc-assert( +doc-) + +@code{Assert(} is the same as @code{assert1(}. The variable +@code{assert-level} specifies the highest assertions that are turned +on. I.e., at the default @code{assert-level} of one, @code{assert0(} and +@code{assert1(} assertions perform checking, while @code{assert2(} and +@code{assert3(} assertions are treated as comments. + +Note that the @code{assert-level} is evaluated at compile-time, not at +run-time. I.e., you cannot turn assertions on or off at run-time, you +have to set the @code{assert-level} appropriately before compiling a +piece of code. You can compile several pieces of code at several +@code{assert-level}s (e.g., a trusted library at level 1 and newly +written code at level 3). + +doc-assert-level + +If an assertion fails, a message compatible with Emacs' compilation mode +is produced and the execution is aborted (currently with @code{ABORT"}. +If there is interest, we will introduce a special throw code. But if you +intend to @code{catch} a specific condition, using @code{throw} is +probably more appropriate than an assertion). + @node Threading Words, , Programming Tools, Words @section Threading Words @@ -1560,10 +1632,11 @@ GForth comes with @file{gforth.el}, an i @file{forth.el} by Goran Rydqvist (icluded in the TILE package). The improvements are a better (but still not perfect) handling of indentation. I have also added comment paragraph filling (@kbd{M-q}), -commenting (@kbd{C-x \}) and uncommenting (@kbd{C-x |}) regions and -removing debugging tracers (@kbd{C-x ~}). I left the stuff I do not use -alone, even though some of it only makes sense for TILE. To get a -description of these features, enter Forth mode and type @kbd{C-h m}. +commenting (@kbd{C-x \}) and uncommenting (@kbd{C-u C-x \}) regions and +removing debugging tracers (@kbd{C-x ~}, @pxref{Debugging}). I left the +stuff I do not use alone, even though some of it only makes sense for +TILE. To get a description of these features, enter Forth mode and type +@kbd{C-h m}. In addition, GForth supports Emacs quite well: The source code locations given in error messages, debugging output (from @code{~~}) and failed @@ -1631,7 +1704,7 @@ double numbers. GNU C is available for f unimportant) UNIX machines, VMS, 80386s running MS-DOS, the Amiga, and the Atari ST, so a Forth written in GNU C can run on all these machines@footnote{Due to Apple's look-and-feel lawsuit it is not -available on the Mac (@pxref{Boycott, , Protect Your Freedom--Fight +available on the Mac (@pxref{Boycott, , Protect Your Freedom---Fight ``Look And Feel'', gcc.info, GNU C Manual}).}. Writing in a portable language has the reputation of producing code that