15.8 Line coverage
The line coverage library provides a means to ascertain exactly how
many times individual clauses are called during the evaluation of a
The library works by placing coverage counters at strategic
points throughout the code being analysed. These counters are
incremented each time the evaluation of a query passes them. There
are three locations in which coverage counters can be inserted.
A code block is defined to be a conjunction of predicate calls. ie. a
sequence of goals separated by commas.
At the beginning of a code block.
- Between predicate calls within a code block.
- At the end of a code block.
The counter values do not only show whether all code points were
reached but also whether subgoals failed or aborted (in which case
the counter before a subgoal will have a higher value than the
counter after it).
In order to add the coverage counters to code, it must be compiled with
predicate which can be found in the
The ccompile/1 predicate (note the initial `c' stands for
coverage) can be used in place of the normal compile/1
predicate to compile a file with coverage counters.
The following shows the results of compiling the n-queens example:
Once compiled, predicates can be called as usual and will (by default)
have no visible side effects. Internally however, the counters will
be incremented as the execution progresses. The following demonstrates
this for a single solution to the queen predicate:
queen.ecl compiled traceable 6016 bytes in 0.01 seconds
coverage: inserted 20 coverage counters into module queen
Yes (0.14s cpu)
The counter results are retrieved as demonstrated in the subsequent section.
The two argument predicate ccompile/2
can take a list of name:value pairs
which can be used to control the exact manner in which coverage
counters are inserted. The documentation for the
provides for a full list of the available flags.
?- queen:queen([1,2,3,4,5,6,7,8,9], Out).
To generate an HTML file
containing the coverage counter results, the
result/1 predicate is used:
This creates the result file coverage/queens.html which
can be viewed using any browser. It contains a pretty-printed form of
the source, annotated with the values of the code coverage counters as
described above. As a side effect, the coverage counters will be reset.
index.pl compiled traceable 335304 bytes in 0.17 seconds
Yes (0.18s cpu)