(IDE/Compiler) Debug Tools: Assertion Testing and Tracing
The tools given to authors for debugging Inform 7 code is rather limited right now. Pinpointing a bug that doesn't generate a compiler or run-time error usually requires a big mess of conditionals and 'say' phrases being thrown into what might otherwise be perfectly sound code to try and pinpoint the bug from it's side effects, and then, when the bug is resolved, those phrases need to be removed. This is hazardous and unnecessary, an avenue for introducing new bugs because you deleted one too many phrases.
I suggest adding formal 'assertion testing' and 'trace' features to Inform 7.
An assertion would basically test the game's logic, checking to ensure the result of a truth statement evaluates true or throws an error otherwise.
To foo (bar - an object):
Assert that bar is not nothing and bar is a thing;
if bar is lit:
now the player carries bar.
If the above assertion failed, it might produce an error like "The assertion 'bar is not nothing and bar is a thing' was false at line 2 of 'example.ni'." The IDE could use the error details to highlight the assertion that failed.
A trace would replace the usage of 'say' in tracking the program's execution.
Dominoes Console is a debug console. It is enabled.
To simulate the dominoes:
trace "simulating step [simulation step count]" to the Dominoes Console;
trace "all dominoes have fallen" to the Dominoes Console when dominoes fallen is total dominoes.
In this mockup implementation, multiple traces are grouped together by their debug console. The console might be presented by the IDE to the author as a seperate text area from the game's output during execution. To keep the code clear and readable, all the lines containing traces corresponding to a disabled debug console could be hidden. This is the reason behind the second version of the trace: if a trace used an 'if' statement to decide if it should be evaluated, it could produce awkward looking code where an 'if' statement has no apparent body.
Naturally, these debug functions should work similarly to headings marked 'Not for Release' and disappear in the release build of the game to ensure the release build is not bogged down by debug code.
My Simple Unit Tests extension is now available. It doesn't give you line numbers for failed assertions, but it will give you the assertion number and which rule it is contained in.
Andrew Plotkin commented
This overlaps the idea of user-inserted run-time error messages: http://inform7.uservoice.com/forums/57320-general/suggestions/1491821-allow-creation-of-customized-runtime-problems
Obviously it's trivial to implement an "assert (c - condition)" phrase that kills the game when the argument is false. The value is in having the IDE display a meaningful run-time error with a link back to the source line that caused the problem. I think this requires compiler assistance, although I could be wrong.
As for tracing, getting messages out of the VM to a separate window is hacky at best. (Yes, the current run-time error system is kind of hacky.) I suspect I'd want trace messages inline *anyway*, so I know how they interleave with normal game output. So this part may not require more than a special say phrase.