/ 
App-FuguWeb-0.11.0
/ App::FuguWeb::Status

NAME

App::FuguWeb::Status - the translation status of a site

SYNOPSIS

use App::FuguWeb::Status;

my $status = App::FuguWeb::Status->new( config => $config );

my $lines = $status->report or die $status->error, "\n";
say for @$lines;            # zh-Hans<TAB>stale<TAB>page<TAB>index.html

$status->record('web/zh-hans/index.body.html')
    or die $status->error, "\n";

DESCRIPTION

A translation follows its source, and a source changes. The record of the site names the version of the default source that each translated file follows, per WEB-STATUS. The class reads the description and the record. It gives each part of a language other than the default that does not follow its source, and it writes the line of a translated file into the record.

The record is the file TRANSLATIONS at the project root, beside .fuguwebrc, per WEB-STATUS-1. It holds one line for each translated file, in the SHA256 manifest form:

SHA256 (web/zh-hans/index.body.html) = 9f86d0...

The path names the translated file from the project root, in UTF-8 bytes, in the form of "canonical_path" in App::FuguWeb: no . step, no empty step, and no final solidus. A path setting of ./web or web/ thus gives the path web/zh-hans/index.body.html. The digest is the SHA-256 of its default source at the time of the translation. Fugu::Signify reads and writes the form, and its writer sorts the lines by path. The description refuses a source path of ASCII white space or a parenthesis, per WEB-SITE-6, so each path fits the form. A record that is absent or empty holds no line.

The record holds one digest for each file. Two parts that name one translated file over two default sources are therefore a fault of the description, per WEB-STATUS-7, and each method refuses it.

The build and the check do not read the record, per WEB-STATUS-6. The status and translated verbs of App::FuguWeb::CLI are the one caller of the class.

Parts

A part is one thing of a language that can come from the default language, per WEB-STATUS-3. Each part has a kind and a name. The name is the name of the block that takes its translation, or the page of a manual:

kind      the part                    the name
site      the site name               the tag of the language
label     the label of a nav entry    the href of the entry
title     the title of a page         the name of the page
page      the source of a page        the name of the page
heading   the heading of a group      the name of the group
manual    the source of a manual      the page of the manual
footer    the footer fragment         the tag of the language

The site name, a label, a title and a heading are values of the description, per WEB-LANGUAGE-8. The other parts are files. A file part whose default language names no source follows no source. Thus the index page of a language can take a body that opens it, when the default index page takes none, and that body takes no state.

States

The states are those of WEB-STATUS-4:

fallback

The part comes from the default language. A value takes this state alone.

unrecorded

The language translates the file, and the record holds no line for it.

stale

The line of the file names a digest other than the one that its default source has now.

METHODS

new

App::FuguWeb::Status->new( config => $config )

The status of the site of one loaded App::FuguWeb::Config. The object reads each default source once, so a caller makes a new object for each question.

report

my $lines = $status->report;

The lines of WEB-STATUS-3 as an array reference, or undef with the reason in "error". A line holds the tag, the state, the kind of the part and its name, with one tab between two fields. The lines follow the order of the languages, and then the order of the description: the site name, each nav label, the title and the source of each page, the heading and the manuals of each group, and the footer. An empty list means that each part follows its source.

The method fails when the record does not parse, when it cannot read the default source of a recorded file, and when the description names one translated file over two default sources. Each such failure is a "fault".

record

$status->record(@files) or die $status->error;

Write the line of each file into the record, with the digest that its default source has now, per WEB-STATUS-2. Each file is a path from the project root, and the method changes it to the form of a path of the record. Thus ./web/a.html and web/a.html name one file. The method keeps each other line of the record.

The method refuses a file that translates no source of the description: a default source, a file of no part, or a file whose default part names no source. One file that it refuses fails the whole call, and a failure writes nothing. The method returns 1, or undef with the reason in "error". It fails with a "fault" as "report" does.

error

The reason of the most recent failure, or undef.

fault

True when the most recent failure is a fault of the project files: a record or a source that does not read, or a description that WEB-STATUS-7 refuses. The CLI gives such a failure the code of a description that does not load, EXIT_CONFIG_ERROR. A file that translates no source is no fault.

CONSTANTS

RECORD

The name of the record, TRANSLATIONS. It sits at the project root, because the build publishes each plain file of the source directory. The description refuses a source directory that is the project root, per WEB-SITE-7.

SEE ALSO

App::FuguWeb, App::FuguWeb::CLI, App::FuguWeb::Config, Fugu::Signify, fuguweb(1)

AUTHOR

Dick Olsson <hi@senzilla.io>