new¶

  my $collection = Devel::Cover::Collection->new(%options);

Creates a new Collection object. All options are optional and have sensible defaults.

Read-Only Attributes¶

These attributes can only be set via the constructor.

bin_dir

Directory containing the "cover" binary. Used when running coverage commands.

cpancover_dir

Directory for CPANCover-specific files and configuration.

cpan_dir

An arrayref of CPAN directories to search for build directories. Defaults to "~/.cpan" and "~/.local/share/.cpan" if they exist.

results_dir

Directory where coverage results are stored. Required for most operations.

dryrun

Boolean. If true, commands are printed but not executed. Default: 0.

env

Environment identifier (e.g., 'prod', 'dev'). Default: 'prod'.

force

Boolean. If true, re-run coverage even for already-covered modules. Default: 0.

output_file

Filename for the main output file. Default: 'index.html'.

report

Report format to generate. Default: 'html_basic'.

timeout

Timeout in seconds for coverage runs. Default: 1800 (30 minutes).

verbose

Boolean. If true, print additional progress information. Default: 0.

workers

Number of parallel workers for coverage runs. Default: 0 (no parallelism).

docker

Docker command to use. Default: 'docker'.

local

Boolean. If true, run in local mode without Docker. Default: 0.

Read-Write-Private Attributes¶

These attributes have public readers but private setters. Use the provided methods to modify them.

build_dirs

Arrayref of build directories to process. Modify via "add_build_dirs".

modules

Arrayref of module names to process. Modify via "add_modules" or "set_modules".

module_file

Path to a file containing module names (one per line). Set via "set_module_file".

Read-Write Attributes¶

These attributes can be read and written directly.

dir

  $collection->dir("/path/to/dir");
  my $dir = $collection->dir;

Working directory for the current operation.

file

  $collection->file("/path/to/file");
  my $file = $collection->file;

Current file being processed.

Module Management¶

add_modules

  $collection->add_modules(@module_names);

Appends modules to the list of modules to process.

set_modules

  $collection->set_modules(@module_names);

Replaces the entire module list with the given modules.

set_module_file

  $collection->set_module_file("/path/to/modules.txt");

Sets the path to a file containing module names.

process_module_file

  $collection->process_module_file;

Reads module names from the file specified by "module_file" and adds them to the modules list. Blank lines and lines starting with "#" are ignored.

Build Operations¶

build_modules

  $collection->build_modules;

Builds all modules in the modules list using "cpan -Ti". If "force" is true, uses the "-f" flag.

add_build_dirs

  $collection->add_build_dirs;

Scans the CPAN directories for build directories and adds them to "build_dirs".

local_build

  $collection->local_build;

Orchestrates a complete local build workflow: processes the module file, builds modules, adds build directories, and runs coverage on all.

Coverage Operations¶

run

  $collection->run($build_dir);

Runs coverage analysis on a single build directory. Creates coverage reports in the results directory.

run_all

  $collection->run_all;

Runs coverage analysis on all directories in "build_dirs", using parallel workers if configured.

cover_modules

  $collection->cover_modules;

Covers all modules using Docker containers. Processes the module file, then runs coverage for each module in parallel.

Report Generation¶

generate_html

  $collection->generate_html;

Generates HTML coverage reports for all modules in the results directory. Creates an index page, per-module pages, and an about page.

coverage_class

  my $css_class = $collection->coverage_class($percentage);

Converts a coverage percentage to a CSS class name for HTML reports:

  n/a     -> "na"
  < 75    -> "c0"
  < 90    -> "c1"
  < 100   -> "c2"
  100     -> "c3"

write_summary

  $collection->write_summary($vars);

Writes the HTML summary pages using Template Toolkit. Called by "generate_html".

write_json

  $collection->write_json($vars);

Writes a JSON file ("cpancover.json") containing coverage data for all modules.

Status Tracking¶

is_covered

  if ($collection->is_covered($module_dir)) { ... }

Returns true if coverage results exist for the given module directory.

is_failed

  if ($collection->is_failed($module_dir)) { ... }

Returns true if the module has been marked as failed.

set_covered

  $collection->set_covered($module_dir);

Marks a module as successfully covered (removes any failure marker).

set_failed

  $collection->set_failed($module_dir);

Marks a module as failed by creating a timestamp file in the failed directory.

Path Methods¶

made_res_dir

  my ($path, $output) = $collection->made_res_dir;
  my ($path, $output) = $collection->made_res_dir($subdir);

Creates and returns the results directory path. If $subdir is provided, creates that subdirectory within the results directory.

covered_dir

  my $path = $collection->covered_dir($module_dir);

Returns the path where coverage results for a module are stored.

failed_dir

  my $path = $collection->failed_dir;

Returns the path to the directory containing failure markers.

failed_file

  my $path = $collection->failed_file($module_dir);

Returns the path to the failure marker file for a module.

dc_file

  my $path = $collection->dc_file;

Returns the path to the "dc" utility script.

Maintenance¶

compress_old_versions

  $collection->compress_old_versions($num_versions_to_keep);

Compresses old coverage results, keeping only the specified number of most recent versions for each module.

get_latest

  $collection->get_latest;

Fetches and prints the latest CPAN release information using CPAN::Releases::Latest.

System Commands¶

sys

  my $output = $collection->sys(@command);

Runs a system command, displaying the first portion of output immediately and buffering the rest. Returns the output on success, empty string on failure.

bsys

  my $output = $collection->bsys(@command);

Like "sys", but buffers all output (no immediate display).

fsys

  my $output = $collection->fsys(@command);

Like "sys", but dies on failure.

fbsys

  my $output = $collection->fbsys(@command);

Like "bsys", but dies on failure.

Devel::Cover::Collection::Template::Provider¶

A subclass of Template::Provider that provides built-in templates for HTML report generation. The following templates are available:

• colours - CSS colour definitions
• html - Base HTML wrapper
• summary - Main index page
• about - About page
• module_by_start - Module listing by first letter