Function

Summary

Displays code coverage in an Editor tool for one file.

Package

hcl

Signature

editor-color-code-coverage filename &key code-coverage-data for-editing show-counters color-covered color-uncovered => result

Arguments

filename

A pathname designator.

code-coverage-data

A code-coverage-data object.

for-editing

A boolean.

show-counters

A boolean.

color-covered

A boolean, controlled by preferences.

color-uncovered

A boolean, controlled by preferences.

font-lock-p

nil, t or the keyword :force. The default value of font-lock-p is t.

comment-counters

A boolean, controlled by preferences.

real-filename

A pathname.

runtime-only

A boolean, controlled by preferences.

Values

result

An editor buffer object, or a list.

Description

The function editor-color-code-coverage displays code coverage in an Editor tool in the LispWorks IDE for one file.

filename must specify a source file, which has code coverage information in the code-coverage-data.

If code-coverage-data is not supplied, it defaults to the internal code coverage data, that is its binary file with code coverage data was loaded in the current image or restore-code-coverage-data was called with data that contains this file. Otherwise, it must specify a code-coverage-data object with data for this file.

for-editing specifies whether is intended that the buffer with the coloring will be editable. When for-editing is nil, a buffer without a pathname is created with a different name from the source file, which prevents accidental overwriting of the source file. If for-editing is non-nil, the file is opened in the normal way, which may mean using an existing editor buffer if it is already opened. Unless you supply show-counters, a buffer that is opened with for-editing non-nil does not contain any modification of the source code. The default value of for-editing is nil.

Depending on the value of comment-counters, the counters may be wrapped by #||#. When show-counters is non-nil, counters are inserted inside the source code. The counters are wrapped in #||#, so the code is still functional, but less readable. The default value of show-counters is (not for-editing).

color-covered and color-uncovered control whether to color covered and uncovered forms respectively. The default value of color-covered is nil. The default value of color-uncovered is t. The default for color-covered and color-uncovered can be set in the LispWorks IDE Preferences... dialog for Code Coverage Browser, tab Coloring .

font-lock-p controls whether font lock (that is, color according to Lisp syntax in the normal way) should be done. When it is t, if the buffer is not already "font locked", it is "font locked" before coloring for code coverage. If font-lock-p is :force, the buffer is always "font locked" first.

comment-counters controls whether to comment counters when they are added. It has no effect when show-counters is nil. When the counters are commented, the code is still valid, because the reader just skips the counters, so you can edit and compile it. When the counters are not commented, the code is not valid, but it is easier to read. The default for comment-counters can be set in the Preferences... dialog for Code Coverage Browser, tab Coloring . The initial default value of comment-counters is t.

runtime-only controls whether to display only run time forms, which means exclude forms that execute only at compile time or load time. The default for runtime-only can be set in the Preferences... dialog for Code Coverage Browser, tab Coloring . The initial default value of runtime-only is nil.

real-filename may be used to specify the actual file to load. When it is non-nil, filename should be a pathname which is the same as the truename that the compiler used when it compiled the file to generate the code coverage. The filename is used to lookup the data in the code-coverage-data object, while real-filename is used as the actual text to load. Note that while filename needs to be the same as the truename that the compiler used, it is not necessarily a real truename on the current machine.

editor-color-code-coverage returns the editor buffer if it is successful. If it fails it returns a list containing a format string followed by format arguments, which can be used to present an error or message to the user.

If editor-color-code-coverage succeeds and for-editing is nil, it remembers that it generated the buffer for the filename, and if it is called again with the same filename and for-editing nil and succeeds, deletes the previous buffer.

See Understanding the code coverage output for details of how to interpret the coloring.

Notes

real-filename is used when the coloring is done on a machine which sees the file via a different pathname than the machine that compiled it, or when the code coverage data is generated from a copy of the source. The mapping in the Code Coverage browser uses it. Figuring out the truename on a different machine is not always easy. The best way is way is to use the one from the data, which you can find either by searching the data using map-code-coverage-data, or from a code-coverage-file-stats object if you already have it.

See also

Understanding the code coverage output
Code Coverage
code-coverage-data