### Diff for /gforth/Attic/gforth.ds between versions 1.4 and 1.7

version 1.4, 1995/01/10 18:57:43 version 1.7, 1995/01/24 17:31:22
Line 428  unwary (e.g., floating point addition is Line 428  unwary (e.g., floating point addition is
for the wary. You should not use them unless you know what you are doing  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  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  want to learn about the problems of floating point numbers (and how to
avoid them), you might start with @cite{Goldberg, What every computer  avoid them), you might start with @cite{David (?) Goldberg, What Every
scientist should know about floating-point numbers, Computing Surveys  Computer Scientist Should Know About Floating-Point Arithmetic, ACM
?}.  Computing Surveys 23(1):5@minus{}48, March 1991}.

doc-f+  doc-f+
doc-f-  doc-f-
Line 449  doc-fexpm1 Line 449  doc-fexpm1
doc-fln  doc-fln
doc-flnp1  doc-flnp1
doc-flog  doc-flog
doc-falog
doc-fsin  doc-fsin
doc-fcos  doc-fcos
doc-fsincos  doc-fsincos
Line 800  Therefore we recommend avoiding using @c Line 801  Therefore we recommend avoiding using @c
@var{n}. One alternative is @code{@var{n} S+LOOP}, where the negative  @var{n}. One alternative is @code{@var{n} S+LOOP}, where the negative
case behaves symmetrical to the positive case:  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  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  @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS
Line 884  The standard does not allow using @code{ Line 885  The standard does not allow using @code{
every @code{?DO} etc. there is exactly one @code{UNLOOP} on any path  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  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  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  Another group of control structure words are

Line 1037  locals are initialized with values from Line 1038  locals are initialized with values from
Currently there is no way to define locals with user-defined data  Currently there is no way to define locals with user-defined data
structures, but we are working on it.  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:

* Where are locals visible by name?::    * Where are locals visible by name?::
Line 1496  locals wordset. Line 1498  locals wordset.
@node Programming Tools, Threading Words, Other I/O, Words  @node Programming Tools, Threading Words, Other I/O, Words
@section Programming Tools  @section Programming Tools

* Debugging::                   Simple and quick.
* Assertions::                  Making your programs self-checking.

@node Debugging, Assertions, Programming Tools, Programming Tools
@subsection Debugging  @subsection Debugging

The simple debugging aids provided in @file{debugging.fs}  The simple debugging aids provided in @file{debugging.fs}
Line 1516  query-replace them with nothing). The de Line 1523  query-replace them with nothing). The de
@code{printdebugdata} and @code{printdebugline} control the output of  @code{printdebugdata} and @code{printdebugline} control the output of
@code{~~}. The default source location output format works well with  @code{~~}. The default source location output format works well with
Emacs' compilation mode, so you can step through the program at the  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  Note that the default actions clobber the contents of the pictured
numeric output string, so you should not use @code{~~}, e.g., between  numeric output string, so you should not use @code{~~}, e.g., between
Line 1526  doc-~~ Line 1535  doc-~~
doc-printdebugdata  doc-printdebugdata
doc-printdebugline  doc-printdebugline

@node  @node Assertions,  , Debugging, Programming Tools
@subsection Assertions  @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  @node Threading Words,  , Programming Tools, Words

Line 1631  double numbers. GNU C is available for f Line 1696  double numbers. GNU C is available for f
unimportant) UNIX machines, VMS, 80386s running MS-DOS, the Amiga, and  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  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  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}).}.  ``Look And Feel'', gcc.info, GNU C Manual}).}.

Writing in a portable language has the reputation of producing code that  Writing in a portable language has the reputation of producing code that

 Removed from v.1.4 changed lines Added in v.1.7

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>