write_table.rs

//! Lays an invoice table out across as many pages as its lines need.
//!
//! The table is longer than a page, so it is fitted, drawn, and continued: the
//! row it stopped at is where the next page picks up, and the headings are
//! drawn again at the top of each one.
//!
//! Every word the table draws is held in `Words`, once per language, and
//! `HQF_PDF_LANG` picks which one is drawn. The quantities and the prices are
//! the same in both.
//!
//! Usage: `cargo run --example write_table -- tmp/table.pdf [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_table -- tmp/tableau.pdf`

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

use hqf_pdf::content::Content;
use hqf_pdf::layout::{
    Border, Cell, ColumnWidth, Columns, FitProgress, Margin, Padding, Row, Rule, Stroke, Table,
    TableFrame, VAlign,
};
use hqf_pdf::{Align, Document, Font, Page, Rgb, RichText, Style};

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

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

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

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

use language::Language;

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

/// The margin around the table, in points.
const MARGIN: f64 = 56.0;
/// The top of the table on every page.
const TOP: f64 = 780.0;
/// The lowest the table may reach before it continues on the next page.
const BOTTOM: f64 = 64.0;

/// A4's width, which the table is fitted across.
const PAGE_WIDTH: f64 = 595.276;

/// The width left to the table between the margins.
const TABLE_WIDTH: f64 = PAGE_WIDTH - 2.0 * MARGIN;

/// How many lines the invoice bills.
const ITEM_COUNT: usize = 10;

/// The words the table is written in, one set per language.
///
/// What is not language stays out of it: the quantities and the unit prices are
/// drawn from `ITEMS` and read the same in every language.
#[derive(Debug)]
struct Words {
    /// What each billed line is called, in the order `ITEMS` bills them.
    items: [&'static str; ITEM_COUNT],
    /// The four column headings.
    description: &'static str,
    quantity: &'static str,
    unit_price: &'static str,
    amount: &'static str,
    /// The three totals under the billed lines.
    subtotal: &'static str,
    tax: &'static str,
    total: &'static str,
}

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

/// The table in English.
const ENGLISH: Words = Words {
    items: [
        "Rendering engine development",
        "Font engine integration, including cutting each face down to the glyphs actually drawn",
        "Invoice template rework",
        "Historical data migration",
        "Acceptance testing and fixes",
        "Team training",
        "Standby cover for the release night",
        "Performance audit",
        "Technical documentation",
        "First year of support",
    ],
    description: "Description",
    quantity: "Qty",
    unit_price: "Unit price",
    amount: "Amount",
    subtotal: "Subtotal",
    tax: "VAT at 20 %",
    total: "Total due",
};

/// The table in French.
const FRENCH: Words = Words {
    items: [
        "Développement du moteur de rendu",
        "Intégration du moteur de polices, avec réduction de chaque police aux seuls \
glyphes utilisés",
        "Refonte du modèle de facture",
        "Migration des données historiques",
        "Recette et corrections",
        "Formation de l’équipe",
        "Astreinte la nuit de la mise en production",
        "Audit de performance",
        "Documentation technique",
        "Première année d’assistance",
    ],
    description: "Désignation",
    quantity: "Qté",
    unit_price: "Prix unitaire",
    amount: "Montant",
    subtotal: "Total HT",
    tax: "TVA 20 %",
    total: "Total TTC",
};

/// The table in Dutch.
const DUTCH: Words = Words {
    items: [
        "Ontwikkeling van de opmaakmotor",
        "Integratie van de lettertypemotor, inclusief het inkorten van elke letter tot de werkelijk getekende glyphs",
        "Herziening van het factuursjabloon",
        "Migratie van historische gegevens",
        "Acceptatietests en correcties",
        "Teamtraining",
        "Stand-by voor de lanceringsnacht",
        "Prestatieaudit",
        "Technische documentatie",
        "Eerste jaar ondersteuning",
    ],
    description: "Omschrijving",
    quantity: "Aantal",
    unit_price: "Stukprijs",
    amount: "Bedrag",
    subtotal: "Subtotaal",
    tax: "Btw 20 %",
    total: "Te betalen",
};

/// The table in Portuguese.
const PORTUGUESE: Words = Words {
    items: [
        "Desenvolvimento do motor de paginação",
        "Integração do motor de tipos de letra, incluindo reduzir cada tipo aos glifos de facto desenhados",
        "Remodelação do modelo de fatura",
        "Migração de dados históricos",
        "Testes de aceitação e correções",
        "Formação da equipa",
        "Prevenção para a noite do lançamento",
        "Auditoria de desempenho",
        "Documentação técnica",
        "Primeiro ano de suporte",
    ],
    description: "Descrição",
    quantity: "Qtd.",
    unit_price: "Preço unitário",
    amount: "Montante",
    subtotal: "Subtotal",
    tax: "IVA a 20 %",
    total: "Total a pagar",
};

/// The table in Italian.
const ITALIAN: Words = Words {
    items: [
        "Sviluppo del motore di impaginazione",
        "Integrazione del motore dei font, inclusa la riduzione di ogni font ai glifi effettivamente disegnati",
        "Revisione del modello di fattura",
        "Migrazione dei dati storici",
        "Collaudo e correzioni",
        "Formazione del team",
        "Reperibilità per la notte del rilascio",
        "Verifica delle prestazioni",
        "Documentazione tecnica",
        "Primo anno di assistenza",
    ],
    description: "Descrizione",
    quantity: "Qtà",
    unit_price: "Prezzo unitario",
    amount: "Importo",
    subtotal: "Imponibile",
    tax: "IVA al 20 %",
    total: "Totale dovuto",
};

/// The table in Spanish.
const SPANISH: Words = Words {
    items: [
        "Desarrollo del motor de maquetación",
        "Integración del motor de fuentes, incluido el recorte de cada fuente a los glifos realmente dibujados",
        "Rediseño de la plantilla de factura",
        "Migración de datos históricos",
        "Pruebas de aceptación y correcciones",
        "Formación del equipo",
        "Guardia para la noche del lanzamiento",
        "Auditoría de rendimiento",
        "Documentación técnica",
        "Primer año de soporte",
    ],
    description: "Descripción",
    quantity: "Cant.",
    unit_price: "Precio unitario",
    amount: "Importe",
    subtotal: "Subtotal",
    tax: "IVA al 20 %",
    total: "Total a pagar",
};

/// The table in German.
const GERMAN: Words = Words {
    items: [
        "Entwicklung der Rendering-Engine",
        "Integration der Font-Engine, einschließlich der Beschränkung jedes Schnitts auf die tatsächlich gezeichneten Glyphen",
        "Überarbeitung der Rechnungsvorlage",
        "Migration der Altdaten",
        "Abnahmetests und Korrekturen",
        "Schulung des Teams",
        "Bereitschaft in der Nacht der Auslieferung",
        "Leistungsprüfung",
        "Technische Dokumentation",
        "Erstes Jahr Support",
    ],
    description: "Beschreibung",
    quantity: "Menge",
    unit_price: "Einzelpreis",
    amount: "Betrag",
    subtotal: "Zwischensumme",
    tax: "MwSt. 20 %",
    total: "Zu zahlen",
};

/// 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); 7] = [
    (Language::English, &ENGLISH),
    (Language::French, &FRENCH),
    (Language::German, &GERMAN),
    (Language::Spanish, &SPANISH),
    (Language::Italian, &ITALIAN),
    (Language::Portuguese, &PORTUGUESE),
    (Language::Dutch, &DUTCH),
];

/// One line of the invoice.
struct Item {
    /// How many.
    quantity: u32,
    /// The price of one, before tax.
    unit_price: f64,
}

/// The lines the invoice bills, in the order `Words::items` names them. Long
/// enough to run past one page, and one of them long enough to wrap onto a
/// second line inside its cell.
const ITEMS: [Item; ITEM_COUNT] = [
    Item {
        quantity: 12,
        unit_price: 620.0,
    },
    Item {
        quantity: 8,
        unit_price: 620.0,
    },
    Item {
        quantity: 3,
        unit_price: 480.0,
    },
    Item {
        quantity: 5,
        unit_price: 540.0,
    },
    Item {
        quantity: 6,
        unit_price: 480.0,
    },
    Item {
        quantity: 2,
        unit_price: 750.0,
    },
    Item {
        quantity: 1,
        unit_price: 1200.0,
    },
    Item {
        quantity: 4,
        unit_price: 690.0,
    },
    Item {
        quantity: 3,
        unit_price: 420.0,
    },
    Item {
        quantity: 12,
        unit_price: 350.0,
    },
];

/// An amount, as an invoice 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 colour the grand total's figure is drawn in.
const TOTAL_INK: Rgb = Rgb::new(0.0, 0.3, 0.6);

/// The cell holding one of the totals, `figure` set in `font` at `size`.
///
/// The grand total's figure is drawn in a colour of its own, and its currency
/// in the ink of the rest of the table: one cell, two styles.
fn total_cell(font: &hqf_pdf::FontHandle, size: f64, figure: String, inked: bool) -> Cell<'_> {
    if !inked {
        return Cell::new(font, size, figure);
    }
    let (number, currency) = figure.rsplit_once(' ').unwrap_or((figure.as_str(), ""));
    let plain = Style::new(font, size);
    let ink = plain.clone().color(TOTAL_INK);
    Cell::rich(
        RichText::new()
            .span(number, &ink)
            .span(format!(" {currency}"), &plain),
    )
}

/// The invoice's table: a heading row, the billed lines, and the totals.
fn invoice_table<'a>(
    text: &'a hqf_pdf::FontHandle,
    words: &'static Words,
) -> Result<Table<'a>, hqf_pdf::Error> {
    // The designation takes whatever the three figure columns leave it.
    let columns = Columns::new(
        vec![
            ColumnWidth::Fraction(1.0),
            ColumnWidth::Points(46.0),
            ColumnWidth::Points(94.0),
            ColumnWidth::Points(94.0),
        ],
        TABLE_WIDTH,
    )?;

    let mut table = Table::new(columns);
    table.header(1);
    table
        .rule(Rule::Frame, Stroke::black(0.8))
        .rule(Rule::HorizontalOther, Stroke::new(0.25, Rgb::gray(0.75)))
        .rule(Rule::VerticalOther, Stroke::new(0.25, Rgb::gray(0.75)))
        // Under the headings, and above the totals.
        .rule(Rule::Horizontal(1), Stroke::black(0.8))
        .rule(Rule::HorizontalFromEnd(1), Stroke::black(0.8));

    let pad = Padding::symmetric(5.0, 4.0);
    let heading = |label: &str| {
        Cell::new(text, 9.0, label)
            .padding(pad)
            .fill(Rgb::gray(0.88))
            .valign(VAlign::Middle)
    };

    table.push(
        Row::new()
            .cell(heading(words.description))
            .cell(heading(words.quantity).align(Align::Right))
            .cell(heading(words.unit_price).align(Align::Right))
            .cell(heading(words.amount).align(Align::Right))
            .min_height(20.0),
    );

    // The lines are billed five times over, so that the table runs past a page
    // and its continuation can be seen.
    let mut total = 0.0;
    for (index, item) in ITEMS.iter().cycle().take(ITEMS.len() * 5).enumerate() {
        let label = words.items[index % ITEM_COUNT];
        let line_total = f64::from(item.quantity) * item.unit_price;
        total += line_total;

        let figure = |value: String| {
            Cell::new(text, 9.0, value)
                .padding(pad)
                .align(Align::Right)
                .valign(VAlign::Middle)
        };

        let mut row = Row::new()
            .cell(Cell::new(text, 9.0, label).padding(pad))
            .cell(figure(item.quantity.to_string()))
            .cell(figure(amount(item.unit_price)))
            .cell(figure(amount(line_total)))
            .min_height(18.0);

        // Every other line is shaded, which is what a row fill is for.
        if index % 2 == 1 {
            row = row.fill(Rgb::gray(0.97));
        }
        table.push(row);
    }

    let tax = total * 0.2;
    for (label, value, weight, is_grand_total) in [
        (words.subtotal, total, 9.0, false),
        (words.tax, tax, 9.0, false),
        (words.total, total + tax, 10.0, true),
    ] {
        // The grand total is boxed in a border of its own, held off the grid by
        // a margin so that it reads as a total rather than as one more line of
        // the table. The box is drawn side by side: the label carries its left
        // edge and the figure its right, so the two cells trace one box between
        // them rather than a box each.
        let (label_border, value_border, box_margin) = if is_grand_total {
            let rule = Stroke::black(0.8);
            (
                Border::none().top(&rule).bottom(&rule).left(&rule),
                Border::none().top(&rule).bottom(&rule).right(&rule),
                Margin::symmetric(0.0, 2.0),
            )
        } else {
            (Border::none(), Border::none(), Margin::NONE)
        };

        table.push(
            Row::new()
                .cell(
                    Cell::new(text, weight, label)
                        .span(3)
                        .align(Align::Right)
                        .padding(pad)
                        .margin(box_margin)
                        .border(label_border.clone()),
                )
                .cell(
                    total_cell(text, weight, amount(value), is_grand_total)
                        .align(Align::Right)
                        .padding(pad)
                        .margin(box_margin)
                        .border(value_border.clone()),
                )
                .min_height(18.0),
        );
    }

    Ok(table)
}

fn main() -> std::process::ExitCode {
    failure::reported(run())
}

fn run() -> 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("table")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

    let font = Font::parse(fs::read(&font_path)?)?;
    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    let text = doc.add_font(font);

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

    // Fit, draw, and continue on a new page for as long as rows remain.
    let mut start = 0;
    let mut pages = 0;
    loop {
        let placed = table.fit(TableFrame::new(MARGIN, TOP, TOP - BOTTOM), start)?;

        let mut content = Content::new();
        placed.draw(&mut content)?;

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

        match placed.outcome() {
            FitProgress::Done => break,
            FitProgress::BoxFull { next_row } => start = next_row,
            FitProgress::RowTooTall { row } => {
                return Err(format!("row {row} is taller than a page and cannot be drawn").into());
            }
            outcome => {
                return Err(format!(
                    "the table fitted to {outcome:?}, which this page cannot answer"
                )
                .into());
            }
        }
    }

    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} pages, {} rows",
        bytes.len(),
        table.row_count()
    );
    Ok(())
}

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

    /// The lines two languages are allowed to write the same way, where two
    /// languages spell a word alike. Every word is a word of the language it is
    /// written in.
    const SPARED: [&str; 3] = [
        // Written the same way in Spanish.
        r#"subtotal: "Subtotal""#,
        // Written the same way in Italian.
        r#"tax: "IVA al 20 %""#,
        // Written the same way in Portuguese.
        r#"total: "Total a pagar""#,
    ];

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

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