Node:FDBG Writing Visualizers, Next:, Previous:FDBG Customizing Output, Up:FDBG Advanced Usage

Writing Visualizers

For more complicated problems you might want to change the output more drastically. In this case you have to write and use your own visualizers, which could naturally be problem specific, not like fdbg_show/2 and fdbg_label_show/3. As we described earlier, currently there are two types of visualizers:

constraint visualizer

MyGlobalVisualizer([+Arg1, +Arg2, ...] +Constraint, +Actions)

This visualizer is passed in the constraint_hook option. It must have at least two arguments, these are the following:

the constraint that was handled by the dispatcher
the action list returned by the dispatcher

Other arguments can be used for any purpose, for example to select the verbosity level of the visualizer. This way you don't have to modify your code if you would like to see less or more information. Note however, that the two obligatory arguments must appear at the end of the argument list.

When passing as an option to fdbg_on/1, only the optional arguments have to be specified; the two mandatory arguments should be omitted. See FDBG Debugging Global Constraints, for an example.

labeling visualizer

MyLabelingVisualizer([+Arg1, +Arg2, ...] +Event, +ID, +Var)

This visualizer is passed in the labeling_hook option. It must have at least three arguments, these are the following:

a term representing the labeling event, can be one of the following:
labeling has just started for a variable
labeling has just failed for a variable
variable has been constrained in a labeling step described by the compound term Step, which is either created by library(clpfd)'s labeling predicates (in this case, simply print it--FDBG will know how to handle it) or by you; see FDBG Annotation.

identifies the labeling session, i.e. binds step and fail events to the corresponding start event
the variable being the subject of labeling

The failure of a visualizer is ignored and multiple choices are cut by FDBG. Exceptions, on the other hand, are not caught.

FDBG provides several predicates to ease the work of the visualizer writers. These predicates are the following:

fdbg_annotate(+Term0, -Term, -Variables)
fdbg_annotate(+Term0, +Actions, -Term, -Variables)
Replaces each constraint variable in Term0 by a compound term describing it and returns the result in Term. Also, collects these compound terms into the list Variables. These compound terms have the following form:
fdvar(Name, Var, FDSet)
is the name of the variable (auto-generated, if necessary; see FDBG Name Auto-Generation)
is the variable itself
is the domain of the variable after narrowing with Actions, if specified; otherwise, it is the current domain of the variable

Prints a legend of Vars, which is a list of fdvar/3 compound terms returned by fdbg_annotate/[3,4].
fdbg_legend(+Vars, +Actions)
Prints a legend of Vars followed by some conclusions regarding the constraint (exiting, failing, etc.) based on Actions.