Annotation of gforth/compat/assert.fs, revision 1.1
1.1 ! anton 1: \ assertions
! 2:
! 3: \ This file is in the public domain. NO WARRANTY.
! 4:
! 5: \ It is a good idea to make your programs self-checking, in
! 6: \ particular, if you use an assumption (e.g., that a certain field of a
! 7: \ data structure is never zero) that may become wrong during maintenance.
! 8: \ Gforth supports assertions for this purpose. They are used like this:
! 9:
! 10: \ assert( FLAG )
! 11:
! 12: \ The code between `assert(' and `)' should compute a flag, that
! 13: \ should be true if everything is alright and false otherwise. It should
! 14: \ not change anything else on the stack. The overall stack effect of the
! 15: \ assertion is `( -- )'. E.g.
! 16:
! 17: \ assert( 1 1 + 2 = ) \ what we learn in school
! 18: \ assert( dup 0<> ) \ assert that the top of stack is not zero
! 19: \ assert( false ) \ this code should not be reached
! 20:
! 21: \ The need for assertions is different at different times. During
! 22: \ debugging, we want more checking, in production we sometimes care more
! 23: \ for speed. Therefore, assertions can be turned off, i.e., the assertion
! 24: \ becomes a comment. Depending on the importance of an assertion and the
! 25: \ time it takes to check it, you may want to turn off some assertions and
! 26: \ keep others turned on. Gforth provides several levels of assertions for
! 27: \ this purpose:
! 28:
! 29: \ `assert0(' -- gforth ``assert-zero''
! 30: \ important assertions that should always be turned on
! 31:
! 32: \ `assert1(' -- gforth ``assert-one''
! 33: \ normal assertions; turned on by default
! 34:
! 35: \ `assert2(' -- gforth ``assert-two''
! 36: \ debugging assertions
! 37:
! 38: \ `assert3(' -- gforth ``assert-three''
! 39: \ slow assertions that you may not want to turn on in normal debugging;
! 40: \ you would turn them on mainly for thorough checking
! 41:
! 42: \ `assert(' -- gforth ``assert(''
! 43: \ equivalent to assert1(
! 44:
! 45: \ `)' -- gforth ``close-paren''
! 46: \ end an assertion
! 47:
! 48: \ `Assert(' is the same as `assert1('. The variable `assert-level'
! 49: \ specifies the highest assertions that are turned on. I.e., at the
! 50: \ default `assert-level' of one, `assert0(' and `assert1(' assertions
! 51: \ perform checking, while `assert2(' and `assert3(' assertions are
! 52: \ treated as comments.
! 53:
! 54: \ Note that the `assert-level' is evaluated at compile-time, not at
! 55: \ run-time. I.e., you cannot turn assertions on or off at run-time, you
! 56: \ have to set the `assert-level' appropriately before compiling a piece
! 57: \ of code. You can compile several pieces of code at several
! 58: \ `assert-level's (e.g., a trusted library at level 1 and newly written
! 59: \ code at level 3).
! 60:
! 61: \ `assert-level' -- a-addr gforth ``assert-level''
! 62: \ all assertions above this level are turned off
! 63:
! 64: \ The program uses the following words
! 65: \ from CORE :
! 66: \ Variable ! : @ > IF POSTPONE THEN ; immediate 0=
! 67: \ from BLOCK-EXT :
! 68: \ \
! 69: \ from EXCEPTION-EXT :
! 70: \ abort"
! 71: \ from FILE :
! 72: \ (
! 73:
! 74: variable assert-level ( -- a-addr ) \ gforth
! 75: \ all assertions above this level are turned off
! 76: 1 assert-level !
! 77:
! 78: : assertn ( n -- ) \ gforth assert-n
! 79: \ this is internal (it is not immediate)
! 80: assert-level @ >
! 81: if
! 82: POSTPONE (
! 83: then ;
! 84:
! 85: : assert0( ( -- ) \ gforth assert-zero
! 86: \ important assertions that should always be turned on
! 87: 0 assertn ; immediate
! 88: : assert1( ( -- ) \ gforth assert-one
! 89: \ normal assertions; turned on by default
! 90: 1 assertn ; immediate
! 91: : assert2( ( -- ) \ gforth assert-two
! 92: \ debugging assertions
! 93: 2 assertn ; immediate
! 94: : assert3( ( -- ) \ gforth assert-three
! 95: \ slow assertions that you may not want to turn on in normal debugging;
! 96: \ you would turn them on mainly for thorough checking
! 97: 3 assertn ; immediate
! 98: : assert( ( -- ) \ gforth
! 99: \ equivalent to assert1(
! 100: POSTPONE assert1( ; immediate
! 101:
! 102: : (endassert) ( flag -- ) \ gforth-internal
! 103: \ inline argument sourcepos
! 104: 0= abort" assertion failed" ;
! 105:
! 106: : ) ( -- ) \ gforth close-paren
! 107: \ end an assertion
! 108: POSTPONE (endassert) ; immediate
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>