NAME

Review::Helper::Export - A review file as shareable JSON, and back.

DESCRIPTION

The export is the text form of a review file, for sharing a review with other reviewers: every table the schema defines except feedback, request and flag_seen, since each reviewer keeps their own. Tables are written generically, with their columns and their rows in primary key order, so new columns need no code here.

Extension tables and columns (named x_...) are not carried in this format version. Importing ignores any it finds.

Importing creates a review file in the current repository, or merges an export of a review already here into the file holding it, registers it as open, and pins each iteration whose head commit is present.

SYNOPSIS

use Review::Helper::Export;

my $exporter = Review::Helper::Export->new(db => $db);
print $exporter->encode($exporter->export);

my $importer = Review::Helper::Export->new(repo => $repo);
my $result   = $importer->restore($export, name => 'add-caching');
say $result->{file};
say "fetch $_->{head}" for @{$result->{missing}};

ATTRIBUTES

$db = $export->db()

The Review::Helper::DB to export. Required by export.

$repo = $export->repo()

The repository to import into, a Review::Helper::VCS. Required by restore.

PUBLIC METHODS

$export = $exporter->export()

The review as a hashref: format (review-export), format_version (1), generator, and tables, which maps each table name to { columns => [...], rows => [[...], ...] }.

$table = $exporter->export_table($dbh, $name)

One table as { columns => [...], rows => [[...], ...] }: rows in primary key order, or rowid order for a table without one, leaving out x_ extension columns.

$text = $exporter->encode($export)

The export as UTF-8 JSON text with sorted keys and one table row per line.

$result = $importer->restore($export, %params)

Import a decoded export and return { file => $path, missing => [{ iteration => $n, head => $revision }, ...] }. The review is open and registered as open, whatever state the export records. missing lists iterations whose head commit is not in the repository; they are not pinned. %params may hold file (default: NAME.sqlite in the VCS's state directory) and name (default: the review's title, else its id).

When the review is already registered here with a file that exists, or the target file already holds it, the export is merged into that file: see load; registering is the last step of its transaction. Croaks, leaving no new file behind and an existing file unchanged, when registering fails, when the export is invalid or lacks a table or column this version has (another version built it), when the target file exists and holds another review or has another format version, or when file names a path other than the review's registered file.

$id = $importer->check_export($export)

Croak unless $export has this format and version, a tables object, no feedback, requests or seen marks, and exactly one review row. Returns the review id.

$path = $importer->target_file($builder, $known, $id, $export, %params)

The file to import into: the registered file $known when it exists, else file or the default file, checked for location.

$db = $importer->open_same($file, $id)

Open an existing $file, croaking unless it is a review file holding review $id. A file of another format version is refused as "open" in Review::Helper::DB refuses it.

$path = $importer->default_file($name, $export)

The default file for an import, named after $name or the export's review.

$importer->load($db, $tables)
$importer->load($db, $tables, $then)

Write the exported tables into the review file in one transaction. $then, when given, runs last inside it, after every check: when it dies, nothing is written. The export's review row replaces the file's; each exported iteration replaces the file's iteration of that number with all its commits, files, sections, flags, journal entries and guide steps. Iterations the export lacks, the meta rows, and all feedback and requests stay. A replaced flag's marks move to the flag with the same note_id in that iteration when it covers the same commit, path and lines, unless the export turned it from yellow to red, and are dropped otherwise. The review's state is then open.

$importer->save_marks($dbh, $numbers)
$importer->restore_marks($dbh)

save_marks keeps the seen marks of iterations $numbers in a temporary table before load replaces them; restore_marks puts each back on the new flag with the same note_id, iteration, commit, path and lines, unless that flag is red and was yellow, drops the rest, and removes the temporary table.

$numbers = $importer->exported_iterations($tables)

The iteration numbers the exported iteration table holds.

$importer->clear_iterations($dbh, $numbers)

Delete those iterations and every row under them.

$importer->load_table($dbh, $name, $table)

Insert one exported table's rows, skipping x_ columns. Croaks when the export has no such table or lacks a column the file's table has (other than an x_ one), which would otherwise load as null without a word: a different version of review-helper built the export. A column the file's table lacks fails the insert.

$importer->check_references($dbh)

Croak when a row refers to a row that is not there. load defers foreign keys to the commit and checks them with this before $then, so nothing it runs is followed by a failed commit for want of a row.

$importer->check_pins($db)

Croak unless each iteration's pin is the name the VCS gives it ("pin_name" in Review::Helper::VCS).

$missing = $importer->pin($db)

Pin each iteration of the file whose head is present, including ones pinned before or fetched since, and return the others.

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/