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).
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.
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.
