How do I debug in Inform 7?

Question

Plastering "say" all over works, but it has some risks: this code may seep into a release version.

What can I type to narrow down where something is not quite working, with a parser command or with code?

Answer 1

From a macro perspective, the RULES command is useful to see what the program is doing. RULES ON shows the basic rules e.g. "instead of jumping:". RULES ALL shows things like repeat loops, although it doesn't show each value. It also shows which rules don't fire, which can be too wordy.

If you have a bug at the start of the program, you can define acode as follows:

when play begins:
  debug-now;

to debug-now:
  (- RulesOnSub(); -)

RULES is a double-edged sword. A lot of rules fire when you move between rooms. Fortunately, you can cut and paste a transcript from the IDE for a closer look.

Section 24.4 of the Inform manual describes other tests. The most immediately useful are PURLOIN (give the player an item,) ABSTRACT (move an item somewhere) and GONEAR (warp the player.) One not mentioned is PRONOUNS, which tells what the parser currently maps it/them/him/her to.

Answer 2

From a micro perspective, you may just want to track a value inside an activity or action. I've found this code useful.

chapter debug stubs

debug-state is a truth state that varies.

section allow debug text - not for release

when play begins:
  now debug-state is true;
  continue the action;

section conditional print [should not be marked not for release unless you're willing to wipe all debugging]

to d (x - indexed text):
  if debug-state is true:
    say "DEBUG: [x][line break]";

to dn (x - indexed text):
  if debug-state is true:
    say "(D)[x]";

This lets you track actual values in a loop. Or it can just provide text so that you can narrow down a runtime error. It's perfectly acceptable to put

d "1";
(code)
d "2";
(code)
d "3";

Answer 3

I ended up rolling my own logging code. It's available at github at https://github.com/i7/extensions/blob/master/Peter%20Orme/Flexible%20Logger.i7x

It lets you set log levels and log to console or file.

I have a unit testing extension too, in the same github folder. As far as I know nobody uses them except me, but the logging extensions sounds like something that might be a fit for this question.