A self-paginating table

//! Hands a long table over whole, and lets it decide how many pages it needs.
//!
//! This is the shape a document server wants: build the table, say what box it
//! gets on the first page and what box it gets on the ones after, and call
//! `paginate` once. It answers with one placement per page. The caller makes
//! each page — here, by stamping it onto an imported stationery template — and
//! draws the placement onto it. No loop to write, and no way to write it wrong:
//! a table that could not advance is an error, not another blank page.
//!
//! Two things the table does on its own, which is why the caller no longer can
//! get them wrong:
//!
//!   - the heading row is drawn again at the top of every page;
//!   - the footnote row is drawn again under the last line of every page;
//!   - a section title is kept with the rows under it, so it is never stranded
//!     at the foot of a page away from what it introduces.
//!
//! Under each page the caller adds a note of its own, saying which of the
//! table's rows the page carried and hanging its page number on the grid line
//! between the two columns. The placement is asked for all of it: where its
//! rows ended, where that grid line fell, and which rows it took.
//!
//! Every word the statement draws is held in `Words`, once per language, and
//! `HQF_PDF_LANG` picks which one is drawn. The amounts are the same in both.
//!
//! Usage: `cargo run --example write_table_paginated -- tmp/paginated.pdf
//! [stationery.pdf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_table_paginated --
//! tmp/releve.pdf`

use std::env;
use std::fs;
use std::path::{Path, PathBuf};

use hqf_pdf::content::Content;
use hqf_pdf::layout::{
    Area, Border, Cell, ColumnWidth, Columns, Frame, Margin, Padding, Placement, Row, Rule, Stroke,
    Table, VAlign,
};
use hqf_pdf::read::Reader;
use hqf_pdf::{Align, Document, Font, FontHandle, Page, Rgb};

#[path = "shared/out.rs"]
mod out;

#[path = "shared/licence.rs"]
mod licence;

#[path = "shared/language.rs"]
mod language;

use language::Language;

/// The font the example draws with.
fn default_font() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fonts")
        .join("DejaVuSans.ttf")
}

/// A4's width, and the margins the table is laid out between.
const PAGE_WIDTH: f64 = 595.276;
const MARGIN: f64 = 56.0;
const TABLE_WIDTH: f64 = PAGE_WIDTH - 2.0 * MARGIN;

/// The table starts below the letterhead on the first page, and higher up on
/// every page after it: that is the whole reason `paginate` takes two boxes.
const FIRST_TOP: f64 = 700.0;
const NEXT_TOP: f64 = 800.0;
/// The lowest either may reach.
const BOTTOM: f64 = 64.0;

/// How many sections the statement has, and how many lines in all.
const SECTION_COUNT: usize = 4;
const LINE_COUNT: usize = 15;

/// The words the statement is written in, one set per language.
///
/// What is not language stays out of it: the amounts, the company's name and
/// its address read the same in every language.
#[derive(Debug)]
struct Words {
    /// The line the letterhead of the stationery carries.
    letterhead: &'static str,
    /// The two column headings.
    description: &'static str,
    amount: &'static str,
    /// What each section is called, in the order `SECTIONS` gives them.
    sections: [&'static str; SECTION_COUNT],
    /// What each billed line is called, section after section.
    lines: [&'static str; LINE_COUNT],
    /// The label of the boxed total.
    total: &'static str,
    /// The footnote repeated under the last line of every page.
    footnote: &'static str,
    /// The caller's own note, cut where the row numbers go into it.
    rows_before: &'static str,
    rows_between: &'static str,
    rows_of: &'static str,
    /// The same for the page number.
    page_before: &'static str,
    page_of: &'static str,
}

impl Words {
    /// The words the statement is written in, in `language`.
    fn of(language: Language) -> &'static Self {
        language::pick(&WORDS, language)
    }
}

/// The statement in English.
const ENGLISH: Words = Words {
    letterhead: "ACME Ltd — statement of services",
    description: "Description",
    amount: "Amount",
    sections: [
        "Development",
        "Reworking what was there",
        "Support",
        "Audit",
    ],
    lines: [
        "Rendering engine",
        "Font engine",
        "Glyph subsetting",
        "Charstring interpreter",
        "Tables and layout",
        "Invoice template",
        "Data migration",
        "Acceptance testing and fixes",
        "Team training",
        "Standby cover for the release night",
        "First year of support",
        "Technical documentation",
        "Performance audit",
        "Security audit",
        "Architecture review",
    ],
    total: "Total due",
    footnote: "Amounts in euros, exclusive of value added tax. ACME Ltd, \
               Bureau 4, 12 rue des Fabriques, 59000 Lille.",
    rows_before: "Rows ",
    rows_between: " to ",
    rows_of: " of ",
    page_before: "Page ",
    page_of: " of ",
};

/// The statement in French.
const FRENCH: Words = Words {
    letterhead: "ACME Ltd — relevé de prestations",
    description: "Désignation",
    amount: "Montant",
    sections: [
        "Développement",
        "Reprise de l'existant",
        "Assistance",
        "Audit",
    ],
    lines: [
        "Moteur de rendu",
        "Moteur de polices",
        "Réduction des polices aux glyphes utilisés",
        "Interpréteur de contours de glyphes",
        "Tableaux et mise en page",
        "Modèle de facture",
        "Migration des données",
        "Recette et corrections",
        "Formation de l'équipe",
        "Astreinte la nuit de la mise en production",
        "Première année d'assistance",
        "Documentation technique",
        "Audit de performance",
        "Audit de sécurité",
        "Revue d'architecture",
    ],
    total: "Total dû",
    footnote: "Montants en euros, hors taxe sur la valeur ajoutée. ACME Ltd, \
               Bureau 4, 12 rue des Fabriques, 59000 Lille.",
    rows_before: "Lignes ",
    rows_between: " à ",
    rows_of: " sur ",
    page_before: "Page ",
    page_of: " sur ",
};

/// Every language the example is written in. A language is added by writing its
/// own set of words and naming it here.
static WORDS: [(Language, &Words); 2] =
    [(Language::English, &ENGLISH), (Language::French, &FRENCH)];

/// The stationery every page is stamped onto, for when the caller has none.
fn a_stationery(
    font_path: &Path,
    words: &'static Words,
) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    let font = doc.add_font(Font::parse(fs::read(font_path)?)?);

    let mut content = Content::new();
    content.save_state();
    content.set_fill_rgb(0.91, 0.94, 0.98)?;
    content.rect(0.0, 812.0, PAGE_WIDTH, 30.0)?;
    content.fill();
    content.set_fill_rgb(0.2, 0.35, 0.6)?;
    content.rect(0.0, 809.0, PAGE_WIDTH, 3.0)?;
    content.fill();
    content.restore_state();

    content.begin_text();
    content.set_font(font.name(), 13.0)?;
    content.text_origin(MARGIN, 820.0)?;
    content.show_glyphs(&font.glyphs(words.letterhead));
    content.end_text();

    let mut page = Page::a4();
    page.content = content.into_bytes();
    doc.add_page(page)?;

    Ok(doc.to_bytes()?)
}

/// One section of the statement: what each of its lines is billed, in the order
/// `Words::lines` names them.
struct Section {
    lines: &'static [f64],
}

/// The statement's sections. Long enough to run over several pages.
const SECTIONS: [Section; SECTION_COUNT] = [
    Section {
        lines: &[7440.0, 4960.0, 2480.0, 3720.0, 5580.0],
    },
    Section {
        lines: &[1440.0, 2700.0, 2880.0],
    },
    Section {
        lines: &[1500.0, 1200.0, 4200.0, 1260.0],
    },
    Section {
        lines: &[2760.0, 3100.0, 1850.0],
    },
];

/// An amount, as a statement writes it: "4 250.00 EUR".
fn amount(value: f64) -> String {
    let fixed = format!("{value:.2}");
    let (units, hundredths) = fixed.split_once('.').unwrap_or((fixed.as_str(), "00"));

    let mut grouped = String::new();
    for (index, digit) in units.chars().enumerate() {
        if index > 0 && (units.len() - index) % 3 == 0 {
            grouped.push(' ');
        }
        grouped.push(digit);
    }
    format!("{grouped}.{hundredths} EUR")
}

/// The statement, as one table: a heading, then every section, four times over
/// so that it runs well past a single page.
fn statement<'a>(text: &'a FontHandle, words: &'static Words) -> Result<Table<'a>, hqf_pdf::Error> {
    let columns = Columns::new(
        vec![ColumnWidth::Fraction(1.0), ColumnWidth::Points(110.0)],
        TABLE_WIDTH,
    )?;

    let mut table = Table::new(columns);
    // The heading row is drawn again at the top of every page, and the footnote
    // row under the last line of every page.
    table.header(1);
    table.footer(1);
    table
        .rule(Rule::Frame, Stroke::black(0.8))
        .rule(Rule::HorizontalOther, Stroke::new(0.25, Rgb::gray(0.75)))
        .rule(Rule::Horizontal(1), Stroke::black(0.8));
    // The shading is said once, for the table, rather than cell by cell: every
    // other row faintly, and the heading over the top of that.
    table
        .fill(Area::EvenRows, Rgb::gray(0.97))
        .fill(Area::Header, Rgb::gray(0.88));

    let pad = Padding::symmetric(5.0, 4.0);
    let heading = |label: &str, align| {
        Cell::new(text, 9.0, label)
            .padding(pad)
            .align(align)
            .valign(VAlign::Middle)
    };
    table.push(
        Row::new()
            .cell(heading(words.description, Align::Left))
            .cell(heading(words.amount, Align::Right))
            .min_height(20.0),
    );

    for round in 0..4 {
        let mut line = 0;
        for (section, title) in SECTIONS.iter().zip(words.sections) {
            // The section title is kept with the first line under it: a title
            // alone at the foot of a page introduces nothing.
            table.push(
                Row::new()
                    .cell(
                        Cell::new(text, 9.5, format!("{title} ({})", round + 1))
                            .padding(pad)
                            .span(2)
                            .fill(Rgb::gray(0.93))
                            .border(&Border::none().bottom(&Stroke::black(0.5))),
                    )
                    .min_height(18.0)
                    .keep_with_next(),
            );

            for value in section.lines {
                let label = words.lines[line];
                line += 1;
                table.push(
                    Row::new()
                        .cell(Cell::new(text, 9.0, label).padding(pad))
                        .cell(
                            Cell::new(text, 9.0, amount(*value))
                                .padding(pad)
                                .align(Align::Right),
                        )
                        .min_height(16.0),
                );
            }
        }
    }

    // The total, boxed, and kept with nothing: it ends the table.
    let total: f64 = SECTIONS.iter().flat_map(|s| s.lines.iter()).sum::<f64>() * 4.0;
    let rule = Stroke::black(0.8);
    table.push(
        Row::new()
            .cell(
                Cell::new(text, 10.0, words.total)
                    .padding(pad)
                    .align(Align::Right)
                    .margin(Margin::symmetric(0.0, 2.0))
                    .border(&Border::none().top(&rule).bottom(&rule).left(&rule)),
            )
            .cell(
                Cell::new(text, 10.0, amount(total))
                    .padding(pad)
                    .align(Align::Right)
                    .margin(Margin::symmetric(0.0, 2.0))
                    .border(&Border::none().top(&rule).bottom(&rule).right(&rule)),
            )
            .min_height(20.0),
    );

    // The footnote, repeated under the last line of every page.
    table.push(
        Row::new()
            .cell(
                Cell::new(text, 7.5, words.footnote)
                    .padding(pad)
                    .span(2)
                    .color(Rgb::gray(0.45)),
            )
            .space(6.0, 0.0),
    );

    Ok(table)
}

/// Draws the caller's own note under a page's table.
///
/// Everything it needs comes from the placement: where the rows ended, where
/// the table's left edge and the grid line between its two columns fell, and
/// which of the table's rows this page carried. Nothing here counts rows or
/// adds heights on the side, so the note cannot drift away from the table it
/// describes.
fn continuation_note(
    content: &mut Content,
    text: &FontHandle,
    words: &'static Words,
    placed: &Placement<'_>,
    page: usize,
    pages: usize,
    rows: usize,
) -> Result<(), hqf_pdf::Error> {
    let Some(body) = placed.body_rows() else {
        return Ok(());
    };
    let baseline = placed.bottom() - 12.0;

    content.save_state();
    content.set_fill_rgb(0.45, 0.45, 0.45)?;

    content.begin_text();
    content.set_font(text.name(), 7.5)?;
    content.text_origin(placed.x(), baseline)?;
    content.show_glyphs(&text.glyphs(&format!(
        "{}{}{}{}{}{rows}",
        words.rows_before,
        body.start,
        words.rows_between,
        body.end - 1,
        words.rows_of
    )));
    content.end_text();

    if let Some(x) = placed.column_x(1) {
        content.begin_text();
        content.set_font(text.name(), 7.5)?;
        content.text_origin(x, baseline)?;
        content.show_glyphs(&text.glyphs(&format!(
            "{}{}{}{pages}",
            words.page_before,
            page + 1,
            words.page_of
        )));
        content.end_text();
    }

    content.restore_state();
    Ok(())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let language = Language::from_environment()?;
    let words = Words::of(language);

    let mut args = env::args().skip(1);
    // A named file is written as named; the default one carries the language,
    // so the two languages do not overwrite each other in `tmp/`.
    let out = args
        .next()
        .unwrap_or_else(|| language.file_name(&out::default_path("paginated")));
    let font_path = default_font();

    // The stationery every page is stamped onto: the caller's, or one made
    // here.
    let stationery = match args.next() {
        Some(given) => fs::read(given)?,
        None => a_stationery(&font_path, words)?,
    };
    let reader = Reader::new(stationery)?;

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    let template = doc.import_page(&reader, 0)?;
    let text = doc.add_font(Font::parse(fs::read(&font_path)?)?);

    let table = statement(&text, words)?;

    // The whole of pagination: one call, one placement per page.
    let pages = table.paginate(
        Frame::new(MARGIN, FIRST_TOP, FIRST_TOP - BOTTOM),
        Frame::new(MARGIN, NEXT_TOP, NEXT_TOP - BOTTOM),
    )?;

    for (index, placed) in pages.iter().enumerate() {
        let mut content = Content::new();
        // The stationery goes down first, and the table on top of it.
        content.draw_form(template.name(), 0.0, 0.0, 1.0)?;
        placed.draw(&mut content)?;
        continuation_note(
            &mut content,
            &text,
            words,
            placed,
            index,
            pages.len(),
            table.row_count(),
        )?;

        let mut page = Page::a4();
        page.content = content.into_bytes();
        // The stationery is a form, and a page may only draw what its resources
        // name.
        template.add_to(&mut page);
        doc.add_page(page)?;
    }

    let bytes = doc.to_bytes()?;
    if let Some(parent) = Path::new(&out).parent() {
        fs::create_dir_all(parent)?;
    }
    fs::write(&out, &bytes)?;
    println!(
        "wrote {out}: {} bytes, {} pages, {} rows",
        bytes.len(),
        pages.len(),
        table.row_count()
    );
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::{WORDS, language};

    /// The lines two languages are allowed to write the same way, each with
    /// what makes the two the same word.
    const SPARED: [&str; 3] = ["\"Audit\"", "\"Page \"", "page_before: \"Page \""];

    #[test]
    fn every_language_draws_the_statement_in_its_own_words() {
        let untranslated = language::untranslated_lines(&WORDS, &SPARED);

        assert!(
            untranslated.is_empty(),
            "the statement says these in more than one language: {untranslated:?}"
        );
    }
}