@c Generated by the sb-manual contrib. Do not edit.

@node sb cover
@section sb-cover

The @code{sb-cover} module provides a code coverage tool for SBCL. The
tool has support for expression coverage, and for some branch
coverage. Coverage reports are only generated for code compiled
using @code{compile-file} with the value of the
@code{sb-cover:store-coverage-data} optimization quality set to 3.

As of SBCL 1.0.6, @code{sb-cover} is still experimental, and the
interfaces documented here might change in later versions.

How to use it:

@example
;;; Load SB-COVER
(require :sb-cover)

;;; Turn on generation of code coverage instrumentation in the compiler
(declaim (optimize sb-cover:store-coverage-data))

;;; Load some code, ensuring that it's recompiled with the new optimization
;;; policy.
(asdf:oos 'asdf:load-op :cl-ppcre-test :force t)

;;; Run the test suite.
(cl-ppcre-test:test)

;;; Produce a coverage report
(sb-cover:report "/tmp/report/")

;;; Turn off instrumentation
(declaim (optimize (sb-cover:store-coverage-data 0)))
@end example

@anchor{Function sb-cover report}
@ffindex @sortas{report sb-cover} report [sb-cover]
@deffn{Function} sb-cover:report directory &key form-mode if-matches external-format
Print a code coverage report of all instrumented files into @code{directory}.
If @code{directory} does not exist, it will be created. The main report will be
printed to the file cover-index.html. The external format of the source
files can be specified with the @code{external-format} parameter.

If the keyword argument @code{:form-mode} has the value @code{:car}, the annotations
in the coverage report will be placed on the @code{car}s of any cons-forms,
while if it has the value @code{:whole} the whole form will be annotated (the
default). The former mode shows explicitly which forms were
instrumented, while the latter mode is generally easier to read.

The keyword argument @code{if-matches} should be a designator for a function
of one argument, called for the namestring of each file with code
coverage info. If it returns true, the file's info is included in the
report, otherwise ignored. The default value is @code{cl:identity}.
@end deffn
@anchor{Function sb-cover reset-coverage}
@ffindex @sortas{reset-coverage sb-cover} reset-coverage [sb-cover]
@deffn{Function} sb-cover:reset-coverage &optional object
Reset all coverage data back to the @code{Not executed} state.
@end deffn
@anchor{Function sb-cover clear-coverage}
@ffindex @sortas{clear-coverage sb-cover} clear-coverage [sb-cover]
@deffn{Function} sb-cover:clear-coverage
Clear all files from the coverage database. The files will be re-entered
into the database when the FASL files (produced by compiling
@code{store-coverage-data} optimization policy set to 3) are loaded again into the
image.
@end deffn
@anchor{Function sb-cover save-coverage}
@ffindex @sortas{save-coverage sb-cover} save-coverage [sb-cover]
@deffn{Function} sb-cover:save-coverage
Returns an opaque representation of the current code coverage state.
The only operation that may be done on the state is passing it to
@code{restore-coverage}. The representation is guaranteed to be readably printable.
A representation that has been printed and read back will work identically
in @code{restore-coverage}.
@end deffn
@anchor{Function sb-cover save-coverage-in-file}
@ffindex @sortas{save-coverage-in-file sb-cover} save-coverage-in-file [sb-cover]
@deffn{Function} sb-cover:save-coverage-in-file pathname
Call @code{save-coverage} and write the results of that operation into the
file designated by @code{pathname}.
@end deffn
@anchor{Function sb-cover restore-coverage}
@ffindex @sortas{restore-coverage sb-cover} restore-coverage [sb-cover]
@deffn{Function} sb-cover:restore-coverage coverage-state
Restore the code coverage data back to an earlier state produced by
@code{save-coverage}.
@end deffn
@anchor{Function sb-cover restore-coverage-from-file}
@ffindex @sortas{restore-coverage-from-file sb-cover} restore-coverage-from-file [sb-cover]
@deffn{Function} sb-cover:restore-coverage-from-file pathname
@code{read} the contents of the file designated by @code{pathname} and pass the
result to @code{restore-coverage}.
@end deffn
@anchor{Function sb-cover merge-coverage}
@ffindex @sortas{merge-coverage sb-cover} merge-coverage [sb-cover]
@deffn{Function} sb-cover:merge-coverage coverage-state
Merge the code coverage data to include covered code from an earlier
state produced by @code{save-coverage}.
@end deffn
@anchor{Function sb-cover merge-coverage-from-file}
@ffindex @sortas{merge-coverage-from-file sb-cover} merge-coverage-from-file [sb-cover]
@deffn{Function} sb-cover:merge-coverage-from-file pathname
@code{read} the contents of the file designated by @code{pathname} and pass the
result to @code{merge-coverage}.
@end deffn
