NAME

Review::Helper::Split - Pick a file's kind and lay out an agent's sections.

DESCRIPTION

The tool does not split code itself: the agent filling the review names a file's sections through the fill sheet (see "Sections" in the format specification, standards/FORMAT.md in the share directory), covering every line of the file or none. This module lays out those sections, and picks each file's kind for highlighting and images.

A section is a hashref:

{
    name       => 'sub foo',
    package    => 'Foo::Bar' | undef,
    ranges     => [[$start, $end], ...],    # code lines, 1-based, inclusive
    doc_ranges => [[$start, $end], ...],    # its documentation
}

Sections must not share lines. A run of lines in no section must be all blank; it joins the section holding the line before it, as code or documentation like that line; at the top of the file it joins the section holding the line after it.

Sections come back in file order of their first line, code or documentation.

SYNOPSIS

use Review::Helper::Split;

my $kind     = Review::Helper::Split->kind_for('lib/Foo.pm', $first_line);
my $lines    = Review::Helper::Split->lines($text);
my $sections = Review::Helper::Split->assemble(\@units, $lines);

PUBLIC METHODS

$kind = Review::Helper::Split->kind_for($path)
$kind = Review::Helper::Split->kind_for($path, $first_line)

Returns the file's kind: perl, javascript, typescript, css, html, xml, markdown, shell, sql, json, yaml, ini, toml, python, ruby, go, rust, c, cpp, java, makefile, dockerfile, diff, image, or text, by file extension, or by file name for Makefile and Dockerfile. SVG is text: it is diffed and takes line feedback like any text file. A file with no known extension or name takes its kind from a #! line in $first_line: Perl, a shell (sh, bash, zsh, ksh, dash, ash), Node, Python or Ruby, run directly or through env. Whether a file is binary is decided by the caller.

$lines = Review::Helper::Split->lines($text)

Returns the lines of $text without their newlines. A final newline does not start another line.

$sections = Review::Helper::Split->assemble(\@units, \@lines)

Copies of the units (each with ranges and doc_ranges, sorted, sharing no line) for a file of @lines (as lines() gives them), with the blank runs described above joined to them. Croaks when a line in no unit is not blank, unless there are no units: then the file is left whole, with no sections.

$ranges = Review::Helper::Split->to_ranges(@lines)

The line numbers as a sorted range list, [[$start, $end], ...].

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/