CoverageTracker: R6 class for tracking and reporting Arl code execution...

In arl: Embedded Lisp Dialect

R6 class for tracking and reporting Arl code execution coverage

Description

Tracks which lines of .arl source files actually execute during runtime. Maintains execution counts per file/line and generates reports. Supports flexible configuration for tracking custom directories, test files, and custom comment syntax.

Public fields

coverage

Environment mapping "file:line" keys to execution counts

enabled

Logical flag to enable/disable tracking

all_files

Character vector of all .arl files being tracked

code_lines

Environment mapping file paths to integer vectors of code line numbers

coverable_lines

Environment mapping file paths to integer vectors of AST-derived coverable line numbers

Methods

Public methods

• CoverageTracker$new()

• CoverageTracker$track()

• CoverageTracker$register_coverable()

• CoverageTracker$get_summary()

• CoverageTracker$discover_files()

• CoverageTracker$reset()

• CoverageTracker$set_enabled()

• CoverageTracker$report_console()

• CoverageTracker$report_html()

• CoverageTracker$report_json()

• CoverageTracker$clone()

---

Method new()

Initialize the coverage tracker

Usage

CoverageTracker$new(
  search_paths = NULL,
  include_tests = FALSE,
  path_strip_patterns = NULL,
  output_prefix = "arl",
  report_title = "Arl Code Coverage",
  code_line_pattern = "^\\s*[^[:space:];]"
)

Arguments

search_paths

Character vector of directories to search for .arl files (NULL = use stdlib)

include_tests

Whether to include test files in coverage tracking (default: FALSE)

path_strip_patterns

Custom regex patterns for stripping paths in reports (NULL = use defaults)

output_prefix

Subdirectory name for report outputs (default: "arl")

report_title

Title to use in coverage reports (default: "Arl Code Coverage")

code_line_pattern

Regex pattern to identify code lines vs comments/blanks

---

Method track()

Track execution of an expression with source info

Usage

CoverageTracker$track(arl_src)

Arguments

arl_src

Source information object with file, start_line, end_line

---

Method register_coverable()

Register coverable lines from an instrumented source range

Usage

CoverageTracker$register_coverable(file, start_line, end_line)

Arguments

file

Source file path

start_line

Start line of the instrumented form

end_line

End line of the instrumented form

---

Method get_summary()

Get coverage summary as list: file -> line -> count

Usage

CoverageTracker$get_summary()

---

Method discover_files()

Discover all .arl files to track

Searches for .arl files in configured search paths or stdlib by default. By default excludes test files unless include_tests = TRUE.

Usage

CoverageTracker$discover_files()

---

Method reset()

Reset coverage data

Usage

CoverageTracker$reset()

---

Method set_enabled()

Enable/disable tracking

Usage

CoverageTracker$set_enabled(enabled)

Arguments

enabled

Logical value to enable (TRUE) or disable (FALSE) coverage tracking

---

Method report_console()

Generate console coverage report

Usage

CoverageTracker$report_console(output_file = NULL)

Arguments

output_file

Optional file to write report to (default: console only)

---

Method report_html()

Generate HTML coverage report

Usage

CoverageTracker$report_html(output_file)

Arguments

output_file

Path to output HTML file (required)

---

Method report_json()

Generate codecov-compatible JSON format

Usage

CoverageTracker$report_json(output_file)

Arguments

output_file

Path to output JSON file (required)

---

Method clone()

The objects of this class are cloneable with this method.

Usage

CoverageTracker$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Note

This class is exported for use by advanced tooling (CI scripts, IDE plugins, etc.) and for testing purposes. Its API should be considered internal and subject to change without notice. Most users should interact with coverage through the Engine methods enable_coverage(), disable_coverage(), get_coverage(), and reset_coverage() instead.

Examples

# Track coverage of a single stdlib file (logic.arl)
tracker <- CoverageTracker$new()
engine <- Engine$new(coverage_tracker = tracker, load_prelude = FALSE)
logic_file <- system.file("arl", "logic.arl", package = "arl")
engine$load_file_in_env(logic_file, engine$get_env())
engine$eval(engine$read("(not #t)"))
tracker$report_console()

arl documentation built on March 19, 2026, 5:09 p.m.