NAME

Review::Helper::Diff - Parse unified diffs, count changed lines, and attribute them to sections.

DESCRIPTION

Pure functions over the text of a single-file unified diff as produced with the fixed options Review::Helper always uses. Nothing here runs git.

A hunk line is a hashref { type, text, old, new }: type is ' ', '-' or '+'; old and new are the line numbers on each side, undef on the side the line does not exist. Lines are 1-based.

Line counts follow one rule everywhere: each run of - lines followed by + lines counts min(removed, added) as changed and the rest as removed or added.

SYNOPSIS

use Review::Helper::Diff qw/parse_diff count_lines attribute/;

my $diff   = parse_diff($text);
my $counts = count_lines($diff->{hunks});    # { added, removed, changed }

attribute($diff->{hunks}, \@sections);       # sets counts on each section

EXPORTS

Nothing is exported by default.

$diff = parse_diff($text)

Returns { binary => $bool, hunks => \@hunks }. Each hunk is { old_start, old_count, new_start, new_count, lines => \@lines }. binary is true when git reported a binary difference. An empty diff (a pure rename or mode change) has no hunks. "No newline at end of file" markers are dropped.

$counts = count_lines(\@hunks)

Returns { added, removed, changed } for the whole diff.

attribute(\@hunks, \@sections)

Sets added, removed, changed and touched on every section hashref. A section is touched when any - or + line is attributed to it; context lines never touch a section. Owners are decided by line_owners(). The counting rule is applied within each run separately per owning section.

$owners = line_owners(\@hunks, \@sections)

Returns, for each hunk, an arrayref parallel to its lines holding the index of the owning section in \@sections, or undef when no section owns the line.

A context or + line belongs to the section whose ranges or doc_ranges hold its new line. A - line belongs to the section whose old_ranges hold its old line; otherwise to the section holding the next new-side line in the hunk, or, when the removal ends the file, the previous one. Sections with deleted set own only through old_ranges.

$hunks = section_hunks(\@hunks, \@new_lines, \@sections, $index)

The diff of the section at $index in \@sections: every line of its ranges and doc_ranges, unchanged ones as context (their text from \@new_lines, the file after the change, one string per line), with the + lines of \@hunks and the - lines line_owners gives the section, in file order. Each unbroken run of one part is a hunk with a part of code or docs and its own line numbers; lines between runs do not appear. A removed line takes the part of the section's next line in its run, else the previous one, else code. A deleted section shows its removed lines. Returns no hunks when the section has no added or removed line.

($ranges, $changed) = move_ranges(\@hunks, \@ranges)

Where the old lines of a range list are on the new side of the diff: the lines the diff keeps, as a range list in new numbering. $changed is true when the diff removes any of them or adds lines inside one of the ranges.

($start, $end) = map_lines(\@hunks, $start, $end)

Where old lines $start..$end are on the new side of the diff. Returns the empty list when the diff removes any of them or adds lines between them. $end may be undef for a single line, and stays undef.

SOURCE

The source code repository for Review-Helper can be found at https://github.com/exodist/Review-Helper.

MAINTAINERS

Chad Granum <exodist7@gmail.com>

AUTHORS

Chad Granum <exodist7@gmail.com>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See https://dev.perl.org/licenses/