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, andtables, 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 outx_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.missinglists iterations whose head commit is not in the repository; they are not pinned.%paramsmay holdfile(default: NAME.sqlite in the VCS's state directory) andname(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 whenfilenames a path other than the review's registered file. - $id = $importer->check_export($export)
-
Croak unless
$exporthas this format and version, atablesobject, 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
$knownwhen it exists, elsefileor 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
$nameor 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, themetarows, and all feedback and requests stay. A replaced flag's marks move to the flag with the samenote_idin 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 thenopen. - $importer->save_marks($dbh, $numbers)
- $importer->restore_marks($dbh)
-
save_markskeeps the seen marks of iterations$numbersin a temporary table beforeloadreplaces them;restore_marksputs each back on the new flag with the samenote_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
iterationtable 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 anx_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.
loaddefers 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
AUTHORS
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.