10.15.4.2 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 take at least two arguments, the last two of which being:

Constraint

the constraint that was handled by the dispatcher

Actions

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 do not 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, the last three of which being:

Event

a term representing the labeling event, can be one of the following:

start

labeling has just started for a variable

fail

labeling has just failed for a variable

step(Step)

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.

ID

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

Var

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)

Name

is the name of the variable (auto-generated, if necessary; see FDBG Name Auto-Generation)

Var

is the variable itself

FDSet

is the domain of the variable after narrowing with Actions, if specified; otherwise, it is the current domain of the variable

fdbg_legend(+Vars)

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.