You have probably seen this before: you've made a program, compiled it and it doesn't work. Then you start putting code at strategic places, trying to pinpoint the error. And when you're finally done, you've got to revisit all of these places to remove that code. And you probably forget a few..
4tH has a built-in facility which allows to put that code there, debug your program and remove the debugging code from your program by changing a single line.
It is called "assertion" and those of you who have ever worked with C probably know what we're talking about.
An assertion is a line of code that will evaluate an expression. If the expression evaluates to false, it will exit the program with an error message. Let's take a look at this simple colon-definition:
: add \ expects two numbers on the stack + ;
If we call add by writing:
it will fail. Now we add this assertion:
assert( depth 2 >= )
It will evaluate to false when there are less than two items on the stack. The program will be terminated and the appropriate error message will be issued. You may think that this is nice, but you still have to remove all assertion manually.
Not true! If you tried this out already you will see that you won't find an assertion anywhere. It's gone! True, if you want to use assertions you have to enable them. You do that with the word '[ASSERT]':
[assert] : add assert( depth 2 >= ) + ; 1 add
Now assertions will compile and work. If you remove the word '[ASSERT]' all assertions will disappear like they were comment. '[ASSERT]' works just like '[DECIMAL]', '[HEX]', etc. They work linear and do not follow the program flow. If you put '[ASSERT]' halfway your source-file you will notice that assertions work from that point:
: add assert( depth 2 >= ) \ assertions disabled + ; [assert] \ enable assertions : print-hex base @ >r hex assert( depth 1 >= ) \ assertions enabled . cr r> base ! ;
Assertions are only enabled in "PRINT-HEX". The assertion inside "ADD" will be removed and thus be disabled. But there is more to '[ASSERT]' than the eye meets. It doesn't enable assertions, it toggles them. When the 4tH compiler starts, assertions are disabled. The first '[ASSERT]' enables them. A second '[ASSERT]' will disable them again:
[assert] \ enable assertions : add assert( depth 2 >= ) \ assertions enabled + ; [assert] \ disable assertions : print-hex base @ >r hex assert( depth 1 >= ) \ assertions disabled . cr r> base ! ;
There are many possibilities:
You are not limited to range-checking when using 'ASSERT('. Any expression that evaluates to TRUE is allowed:
[assert] : add assert( ." ADD starts at " here . cr true ) assert( depth 2 >= ) assert( ." Values: " over over . . cr true ) + ;
We're sure you can come up with more useful ideas. We did too.