code-coverage-data-generate-coloring-html target &key code-coverage-data shared-source-directory filter target-type color-uncovered color-covered show-counters counter-space index-filename index-name index-sort index-mark-not-entered index-mark-partial index-show-non-runtime open
A pathname designator.
A code-coverage-data object.
A string, a function or a symbol naming a function.
A string or
A pathname designator or
One of the keywords
code-coverage-data must be a code-coverage-data object to use. Otherwise
code-coverage-data-generate-coloring-html uses the internal data.
cl:enough-namestring) merged with the target directory. The result is a tree of HTML files which is parallel to the tree of the source files.
If shared-source-directory is not supplied, all files that passed the filter are produced, and the target HTML file has the filename of the source file inside the target directory. Note that this may cause clashes if there are files with the same name in the data.
filter can be used to restrict which files HTML is produced for. If filter is a string it is interpreted as a regexp. If the
cl:namestring of the truename of a source file matches filter (as by find-regexp-in-string) then HTML is produced for this source file. If filter is a function (or fbound symbol) it must take two arguments, the truename and the code-coverage-file-stats for this source file, and return a boolean specifying whether to produce HTML for this source file. The stats object can be accessed by the code-coverage-file-stats accessor functions (for example
code-coverage-file-stats-lambdas-count). If filter is not supplied, all files (or, if shared-source-directory is supplied, all those files inside it) are produced.
color-uncovered, color-covered, show-counters and counter-space control the HTML output. See Source files HTML coloring below for details. Note that the colors to actually use are specified by code-coverage-set-html-background-colors.
color-uncovered controls whether uncovered forms are colored. These include forms that did not execute at all, eliminated forms and forms which were partially executed but the unexecuted part is hidden (in a macroexpansion). The default value of color-uncovered is
color-covered controls whether covered forms are colored. These include forms that were fully executed, and those parts of partially executed forms that were executed. The default value of color-covered is
index-filename, index-name, index-sort, index-mark-not-entered, index-mark-partial and index-show-non-runtime control the generation of the index file. See Index file below for the description of the index file's contents.
index-filename, when supplied, specifies the name of the index file. It is merged with the target path to generate the full path. Note that the file type should be included in either index-filename or the target path. If index-filename is not supplied, it defaults to
"code-coverage-index.htm". If index-filename is
nil, no index file is produced.
index-sort controls the order files are listed in the table in the index.
:relative-name means sort by the relative name of the source file with respect to shared-source-directory. If shared-source-directory is not supplied,
:relative-name has the same effect as
:name means sort by the name of the source file.
:uncovered means sort by the number of not fully covered runtime lambdas in the file (the sum of
code-coverage-file-stats-partially-covered called with
:runtime). The default value of index-sort is
open specifies whether the index file should opened (by open-url) once it is generated. The default value of open is
code-coverage-data-generate-coloring-html generates a HTML file for each source file in code-coverage-data that is inside the shared-source-directory (or all source files if shared-source-directory is
nil) and pass the filter (or all if filter is
nil), as described above, and one index file with statistics. It uses background colors to mark various things (see below), and these colors can be set by code-coverage-set-html-background-colors. The colors that are described below are the default colors.
The first column shows the file "relative name", which is relative to the optional shared-source-directory, or just the filename. The rest of the columns contain statistics, which are divided into 2 parts: runtime lambdas and optional non-runtime lambdas. "Lambda" here means a separate piece of code (for example code that is called inline does not count as a separate lambda). Runtime lambdas refer to code that is expected to run at runtime, which includes things like functions and methods. Non-runtimes are other lambdas, like macros and top-level forms (as known as one-shot forms). More accurately, runtime and non-runtime refer to the counts which are returned by the code-coverage-file-stats accessor functions (for example
code-coverage-file-stats-lambdas-count) when they are called with
:non-runtime. See code-coverage-file-stats for details.
The total number of lambdas, as returned by
The number of lambdas that were fully covered, as returned by
The number of lambdas that were partially covered, as returned by
The number of lambdas that were not covered, as returned by
In the runtime columns, Partial and None cells which are non-zero are optionally marked with a colored background. This helps you to see which files contain runtime forms that were not executed. The default color is DarkSalmon, and this can be set by code-coverage-set-html-background-colors with keyword argument marked-cell.
The HTML file corresponding to a source file contains the full text of the source file (including comments), with parts optionally highlighted by background colors, and optional counters and some text added. At the time of writing, the default behavior is to highlight uncovered forms and add counters. The background colors can be changed by code-coverage-set-html-background-colors. The general issues associated with coloring are covered in Understanding the code coverage output.
LispWorks User Guide and Reference Manual - 13 Feb 2015