Crate lcov

LCOV tracefile parser/merger/filter in pure Rust.

LCOV is a graphical front-end for coverage testing tool gcov. It collects gcov data for multiple source files and stores them into the file called as "tracefile".

The purpose of this crate is to operate the LCOV tracefile faster than the original LCOV Perl implementation.

Usage

Add this to your Cargo.toml:

[dependencies]
lcov = "0.1"

Performance

See the document of lcov-util.

Data structure

In this crate, the data structure corresponding to each line of the LCOV tracefile is called "LCOV record" and is represented as Record. Each line of the LCOV tracefile is composed of a string representing a kind of the record, a colon, a comma-separated field list:

<KIND>:<field#0>,<field#1>,...<field#N>

LCOV record kind is represented as a variant of Record or RecordKind. Each fields of a LCOV record are represented as fields of a struct-like variant of Record.

For details of the LCOV tracefile syntax, see the manpage of geninfo.

Examples

Parsing a LCOV tracefile:

use lcov::{Record, RecordKind};

// `lcov::open_file` returns `Reader`.
// `Reader` is an iterator that iterates over `Result<lcov::Record, E>` read from the input buffer.
let mut reader = lcov::open_file("tests/fixtures/report.info")?;

// Collect the read records into a vector.
let records = reader.collect::<Result<Vec<_>, _>>()?;
assert_eq!(records[0], Record::TestName { name: "".into() });
assert_eq!(records[1].kind(), RecordKind::SourceFile);

// Outputs the read records in LCOV tracefile format.
for record in records {
    println!("{}", record);
}

Parsing a LCOV infomation from String:

use lcov::{Reader, Record};

let input = "\
TN:test_name
SF:/path/to/source/file.rs
DA:1,2
DA:3,0
DA:5,6
LF:3
LH:2
end_of_record
";

// `&[u8]` implements `BufRead`, so you can pass it as an argument to `Reader::new`.
let mut reader = Reader::new(input.as_bytes());

let records = reader.collect::<Result<Vec<_>, _>>()?;
assert_eq!(records[0], Record::TestName { name: "test_name".into() });
assert_eq!(records[1], Record::SourceFile { path: "/path/to/source/file.rs".into() });

// Creates an `String` in tracefile format. In this example, it is the same as `input`.
let output = records.into_iter().map(|rec| format!("{}\n", rec)).collect::<String>();
assert_eq!(input, output);

Merging tracefiles:

use lcov::{Record, RecordKind, Report};

// Creates an empty `Report`.
let mut report = Report::new();

// Merges a first file.
let reader1 = lcov::open_file("tests/fixtures/report.init.info")?;
report.merge(reader1);

// Merges a second file.
let reader2 = lcov::open_file("tests/fixtures/report.run.info")?;
report.merge(reader2);

// Outputs the merge result in LCOV tracefile format.
for record in report {
    println!("{}", record);
}

Structs

LineFilter	A Report filter that extracts only the records related to the specified line.
LineRange	An range of lines.
Reader	Reading a LCOV records from a buffered reader.
Report	An accumulated coverage information from some LCOV tracefiles.

Enums

MergeError	All possible errors that can occur when merging LCOV records.
ParseRecordError	All possible errors that can occur when parsing LCOV record.
ReadError	All possible errors that can occur when reading LCOV tracefile.
Record	Represents all kinds of LCOV records.
RecordKind	Represents all LCOV record kinds.

Functions

open_file

Opens a LCOV tracefile.