A.8 library( debug ): Some reusable code to help debugging applications

This library provides an structured alternative for putting print-statements into your source-code to trace what is going on. Debug messages are organised in topics that can be activated and de-activated without changing the source. In addition, if the application is compiled with the -O flag these predicates are removed using goal_expansion/2.

Although this library can be used through the normal demand-loading mechanism it is adviced to load it explicitely before code using it to profit from goal-expansion, which removes these calls if compiled with optimisation on and records the topics from debug/3 and debugging/1 for list_debug_topics/0.

debug(+Topic, +Format, +Args)

If Topic is a selected debugging topic (see debug/1) a message is printed using print_message/2 with level informational. Format and Args are interpreted by format/2. Here is a typical example:

        ...,
        debug(init, 'Initialised ~w', [Module]),
        ...,

Topic can be any Prolog term. Compound terms can be used to make categories of topics that can be activated using debug/1.

debugging(+Topic)

Succeeds if Topic is a selected debugging topic. It is intended to execute arbitrary code depending on the users debug topic selection. The construct (debugging(Topic) -> Code ; true) is removed if the code is compiled in optimise mode.

debug(+Topic)

Select all registered topics that unify with Topic for debugging. This call is normally used from the toplevel to activate a topic for debugging. If no matching Topic is registered a warning is printed and the topic is registered for debugging as matching debug statements may be loaded later. Topics are de-activated using nodebug/1.

nodebug(+Topic)

Deactivates topics for debugging. See debug/1 for the arguments.

list_debug_topics

List the current status of registered topics. See also debugging/0.

assertion(:Goal)

This predicate is to be compared to the C-library assert() function. By inserting this goal you explicitely state you expect Goal to succeed at this place. As assertion/1 calls are removed when compiling in optimized mode Goal should not have side-effects. Typical examples are type-tests and validating invariants defined by your application.

If Goal fails the system prints a message, followed by a stack-trace and starts the debugger.

In older versions of this library this predicate was called assume/1 . Code using assume/1 is automatically converted while printing a warning on the first occurrence.