The line coverage library provides a means to ascertain exactly how many times individual clauses are called during the evaluation of a query.
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, i.e., a sequence of goals separated by commas.
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 the ccompile/1 predicate which can be found in the coverage library.
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:
?- coverage:ccompile(queen). queen.ecl compiled traceable 6016 bytes in 0.01 seconds coverage: inserted 20 coverage counters into module queen Yes (0.14s cpu)
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/2 predicate:
?- queen:queen([1,2,3,4,5,6,7,8,9], Out).
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 ccompile/2 predicate provides for a full list of the available flags.
To generate an HTML file containing the coverage counter results, the result/1 predicate is used:
?- coverage:result(queen). Writing /examples/coverage/queen.html index.pl compiled traceable 335304 bytes in 0.17 seconds Yes (0.18s cpu)
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.