A.38.3 Predicate reference

coverage(:Goal)

As call(Goal), collecting coverage information while Goal is running. If Goal succeeds with a choice point, coverage collection is suspended and resumed if we backtrack into Goal. Calls to coverage/1 may be nested.

[semidet]coverage(:Goal, +Options)

Collect and optionally report coverage by Goal. Goal is executed as in once/1. Options processed:

show(+Boolean)

When true (default), call show_coverage/1 passing Options to show the collected coverage data and reset the data. When false, collect the data but do not reset it. If there is already existing data the new data is added.

[det]show_coverage(+Options)

Show collected coverage data. By default it reports the percentage of called and failed clauses related to covered files. Using dir(Dir), detailed line-by-line annotated files are created in the directory Dir. Other options control the level of detail.

all(+Boolean)

When true, report on any file in which some predicate was called.

modules(+Modules)

Only report on files that implement one of the given Modules.

roots(+Directories)

Only report on files below one of the given roots. Each directory in Directories can be a specification for absolute_file_name/3.

annotate(+Bool)

Create an annotated file for the detailed results. This is implied if the ext or dir option are specified.

ext(+Ext)

Extension to use for the annotated file. Default is‘.cov`.

dir(+Dir)

Dump the annotations in the given directory. If not given, the annotated files are created in the same directory as the source file. Each clause that is related to a physical line in the file is annotated with one of:

###	Clause was never executed.
++N	Clause was entered N times and always succeeded
--N	Clause was entered N times and never succeeded
+N-M	Clause has succeeded N times and failed M times
+N*M	Clause was entered N times and succeeded M times

All call sites are annotated using the same conventions, except that --- is used to annotate subgoals that were never called.

line_numbers(Boolean)

If true (default), add line numbers to the annotated file.

color(Boolean)

Controls using ANSI escape sequences to color the output in the annotated source. Default is true.

width(+Columns)

Presumed width of the output window. A value of 40 is considered the minimum. Smaller values are handled as 40.

For example, run a goal and create annotated files in a directory cov using:

?- show_coverage([dir(cov)]).

bug

Color annotations are created using ANSI escape sequences. On most systems these are displayed if the file is printed on the terminal. On most systems less may be used with the -r flag. Alternatively, programs such as ansi2html (Linux) may be used to convert the files to HTML. It would probably be better to integrate the output generation with library(pldoc/doc_htmlsrc).

[semidet,multifile]report_hook(+Succeeded, +Failed)

This hook is called after the data collection. It is passed a list of objects that have succeeded as well as a list of objects that have failed. The objects are one of

ClauseRef

The specified clause

call_site(ClauseRef, PC)

A call was make in ClauseRef at the given program counter.

[det]cov_save_data(+File, +Options)

Save the coverage information to File. Options:

append(true)

Append to File rather than truncating the data if the file exists.

The File is opened using lock(exclusive), which implies that, provided the OS and file system implements file locking, multiple processes may save coverage data to the same file.

The saved data is highly specific to the setup in which it has been created. It can typically only be reloaded using cov_load_data/2 in the same Prolog executable using the same options and with all relevant source file unmodified at the same location.

Reproducibility can be improved by using‘.qlf` files or saved states.

[det]cov_load_data(+File, +Options)

Reload coverage data from File. Options:

load(true)

If specified and the file in which a clauses is expected to exist, load the file using load_files/2 with the same options as used to initially load the file.

silent(+Boolean)

When true, do not emit messages on not loaded source files.

Data is assumed to be reliable if the Nth-clause of a predicate is loaded from the same file at the same line number and has the same size. Unreliable data is ignored, silently if silent(true) is used.

[det]cov_reset

Discard all collected coverage data. This predicate raises a permission error if coverage collection is in progress.

cov_property(?Property)

True when coverage analysis satisfies Property. Currently defined properties are:

active(?Nesting)

True when coverage data is being collected. Nesting expresses the nesting of coverage/1 calls and is normally 1 (one).