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. Whenfalse
, 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
ordir
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 asansi2html
(Linux) may be used to convert the files to HTML. It would probably be better to integrate the output generation withlibrary(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).