\ assertions
\ This file is in the public domain. NO WARRANTY.
\ 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:
\ assert( FLAG )
\ The code between `assert(' and `)' 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 `( -- )'. E.g.
\ 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
\ 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:
\ `assert0(' -- gforth ``assert-zero''
\ important assertions that should always be turned on
\ `assert1(' -- gforth ``assert-one''
\ normal assertions; turned on by default
\ `assert2(' -- gforth ``assert-two''
\ debugging assertions
\ `assert3(' -- gforth ``assert-three''
\ slow assertions that you may not want to turn on in normal debugging;
\ you would turn them on mainly for thorough checking
\ `assert(' -- gforth ``assert(''
\ equivalent to assert1(
\ `)' -- gforth ``close-paren''
\ end an assertion
\ `Assert(' is the same as `assert1('. The variable `assert-level'
\ specifies the highest assertions that are turned on. I.e., at the
\ default `assert-level' of one, `assert0(' and `assert1(' assertions
\ perform checking, while `assert2(' and `assert3(' assertions are
\ treated as comments.
\ Note that the `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 `assert-level' appropriately before compiling a piece
\ of code. You can compile several pieces of code at several
\ `assert-level's (e.g., a trusted library at level 1 and newly written
\ code at level 3).
\ `assert-level' -- a-addr gforth ``assert-level''
\ all assertions above this level are turned off
\ The program uses the following words
\ from CORE :
\ Variable ! : @ > IF POSTPONE THEN ; immediate 0=
\ from BLOCK-EXT :
\ \
\ from EXCEPTION-EXT :
\ abort"
\ from FILE :
\ (
variable assert-level ( -- a-addr ) \ gforth
\ all assertions above this level are turned off
1 assert-level !
: assertn ( n -- ) \ gforth assert-n
\ this is internal (it is not immediate)
assert-level @ >
if
POSTPONE (
then ;
: assert0( ( -- ) \ gforth assert-zero
\ important assertions that should always be turned on
0 assertn ; immediate
: assert1( ( -- ) \ gforth assert-one
\ normal assertions; turned on by default
1 assertn ; immediate
: assert2( ( -- ) \ gforth assert-two
\ debugging assertions
2 assertn ; immediate
: assert3( ( -- ) \ gforth assert-three
\ slow assertions that you may not want to turn on in normal debugging;
\ you would turn them on mainly for thorough checking
3 assertn ; immediate
: assert( ( -- ) \ gforth
\ equivalent to assert1(
POSTPONE assert1( ; immediate
: (endassert) ( flag -- ) \ gforth-internal
\ inline argument sourcepos
0= abort" assertion failed" ;
: ) ( -- ) \ gforth close-paren
\ end an assertion
POSTPONE (endassert) ; immediate
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>