write_pdfa3u.rs

//! Writes a quarter's meter readings claiming the third part of the archival
//! standard, at level U.
//!
//! The third part is the one that lets a record carry a file of any kind inside
//! it, and level U adds that every mark of ink says which letter it stands for.
//! A person opens the record and reads the page; a billing system opens the
//! same file and reads the table.
//!
//! Whether the result really is PDF/A-3U is not for us to say. `veraPDF` says,
//! and `scripts/check_archival.sh` asks it.
//!
//! The words of the page and of its metadata are held in `Words`, once per
//! language, and `HQF_PDF_LANG` picks which set the record is written in.
//!
//! Usage: `cargo run --example write_pdfa3u -- tmp/pdfa3u.pdf [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_pdfa3u -- tmp/pdfa3u_fr.pdf`

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

use hqf_pdf::content::Content;
use hqf_pdf::layout::Align;
use hqf_pdf::metadata::attachment::{Attachment, Relationship};
use hqf_pdf::metadata::xmp::{Metadata, PdfA};
use hqf_pdf::{Document, Error, Font, FontHandle, Page, TextFlow};

#[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")
}

/// When the record was drawn up, and when the file it carries was last changed.
/// The library never reads the clock, so the caller says when.
const ISSUED: &str = "2026-04-05T07:30:00+02:00";
const CHANGED: &str = "2026-04-05T07:25:00+02:00";

/// Who the file says wrote it, and what produced it, in every language alike.
const AUTHOR: &str = "HQF Development";
const PRODUCER: &str = "hqf-pdf-server";

/// The file the record carries. What it is to the record is said in `Words`.
const CARRIED_NAME: &str = "readings.csv";
const CARRIED_TYPE: &str = "text/csv";
const CARRIED: &str = "month,reading_kwh\n2026-01,4118\n2026-02,3902\n2026-03,3447\n";

/// The readings themselves, beside the months they were taken in. Figures and
/// units are the same in every language.
const READINGS: &str = "4 118 kWh\n3 902 kWh\n3 447 kWh";

/// The words the record is written in, one set per language.
#[derive(Debug)]
struct Words {
    /// What the file says it is, in its metadata.
    title: &'static str,
    /// What the file says it is about, in its metadata.
    subject: &'static str,
    /// What the carried file says it is to the record.
    carried_what: &'static str,
    /// The heading at the top of the page.
    heading: &'static str,
    /// What the page says of the part it claims.
    body: &'static str,
    /// What each line of the record asks, one a line.
    labels: &'static str,
}

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

/// The record in English.
const ENGLISH: Words = Words {
    title: "Meter readings, first quarter 2026",
    subject: "A record that carries the figures behind it and reads back word for word",
    carried_what: "The readings the page states, as a machine reads them",
    heading: "Meter readings, first quarter 2026",
    body: "This record claims the third part of the archival standard at the level between the \
        plain one and the tagged one: it may carry a file of any kind, and every mark of ink on \
        its pages says which letter it stands for. The figures below are also carried inside the \
        file, as the comma-separated table a machine reads. A person opens the record and reads \
        the page; a program opens the same record and takes the figures without reading anything \
        at all.",
    labels: "January\nFebruary\nMarch",
};

/// The record in French.
const FRENCH: Words = Words {
    title: "Relevés de compteur, 1er trimestre 2026",
    subject: "Un document qui contient les chiffres dont il découle et se relit mot pour mot",
    carried_what: "Les relevés que la page indique, sous la forme que lit une machine",
    heading: "Relevés de compteur, 1er trimestre 2026",
    body: "Ce document déclare suivre la troisième partie de la norme d’archivage, au niveau \
        situé entre le plus simple et le balisé : il peut contenir un fichier de toute nature, \
        et chaque trace d’encre de ses pages dit quelle lettre elle représente. Les chiffres \
        ci-dessous sont aussi contenus dans le fichier, sous la forme du tableau à valeurs \
        séparées par des virgules que lit une machine. Une personne ouvre le document et lit la \
        page ; un programme ouvre le même document et prend les chiffres sans rien lire.",
    labels: "Janvier\nFévrier\nMars",
};

/// The record in German.
const GERMAN: Words = Words {
    title: "Zählerstände, erstes Quartal 2026",
    subject: "Ein Dokument, das die Zahlen dahinter enthält und sich Wort für Wort auslesen lässt",
    carried_what: "Die Zählerstände dieser Seite, so wie eine Maschine sie liest",
    heading: "Zählerstände, erstes Quartal 2026",
    body: "Dieses Dokument erklärt Konformität mit dem dritten Teil der Archivnorm, auf \
der Stufe zwischen der einfachen und der strukturierten: Es darf eine Datei \
beliebiger Art enthalten, und jede Druckspur auf seinen Seiten gibt an, für \
welchen Buchstaben sie steht. Die Zahlen unten stecken außerdem in der Datei, \
als kommagetrennte Tabelle, die eine Maschine liest. Ein Mensch öffnet das \
Dokument und liest die Seite; ein Programm öffnet dasselbe Dokument und \
übernimmt die Zahlen, ohne überhaupt etwas zu lesen.",
    labels: "Januar\nFebruar\nMärz",
};

/// The record in Spanish.
const SPANISH: Words = Words {
    title: "Lecturas del contador, 1.er trimestre 2026",
    subject: "Un documento que contiene las cifras en que se basa y cuyo texto se copia \
palabra por palabra",
    carried_what: "Las lecturas que indica la página, tal como las lee una máquina",
    heading: "Lecturas del contador, 1.er trimestre 2026",
    body: "Este documento declara cumplir la tercera parte de la norma de archivo, en el \
nivel intermedio entre el básico y el etiquetado: puede llevar un fichero de \
cualquier tipo y cada trazo de tinta de sus páginas dice qué letra representa. \
Las cifras de abajo también van dentro del fichero, como la tabla separada por \
comas que lee una máquina. Una persona abre el documento y lee la página; un \
programa abre el mismo documento y toma las cifras sin leer nada en absoluto.",
    labels: "Enero\nFebrero\nMarzo",
};

/// The record in Italian.
const ITALIAN: Words = Words {
    title: "Letture del contatore, primo trimestre 2026",
    subject: "Un documento che contiene le cifre da cui nasce e ne restituisce il testo \
parola per parola",
    carried_what: "Le letture indicate nella pagina, come le legge una macchina",
    heading: "Letture del contatore, primo trimestre 2026",
    body: "Questo documento dichiara di rispettare la terza parte della norma di \
archiviazione, al livello fra quello di base e quello etichettato: può \
contenere un file di qualsiasi tipo e ogni segno d’inchiostro delle sue pagine \
dice quale lettera rappresenta. Le cifre qui sotto sono contenute anche nel \
file, come la tabella separata da virgole che una macchina legge. Una persona \
apre il documento e legge la pagina; un programma apre lo stesso documento e \
prende le cifre senza leggere nulla.",
    labels: "Gennaio\nFebbraio\nMarzo",
};

/// The record in Portuguese.
const PORTUGUESE: Words = Words {
    title: "Leituras do contador, 1.º trimestre de 2026",
    subject: "Um documento que contém os números que lhe dão origem e cujo texto se recupera \
palavra a palavra",
    carried_what: "As leituras que a página indica, tal como uma máquina as lê",
    heading: "Leituras do contador, 1.º trimestre de 2026",
    body: "Este documento declara cumprir a terceira parte da norma de arquivo, no nível entre o \
        básico e o etiquetado: pode conter um ficheiro de qualquer tipo e cada traço de tinta \
        das suas páginas diz que letra representa. Os números abaixo também estão dentro do \
        ficheiro, como a tabela separada por vírgulas que uma máquina lê. Uma pessoa abre o \
        documento e lê a página; um programa abre o mesmo documento e recolhe os números sem ler \
        absolutamente nada.",
    labels: "Janeiro\nFevereiro\nMarço",
};

/// The record in Dutch.
const DUTCH: Words = Words {
    title: "Meterstanden, eerste kwartaal 2026",
    subject: "Een document dat de cijfers erachter bevat en woord voor woord terug te lezen is",
    carried_what: "De meterstanden op de pagina, zoals een machine ze leest",
    heading: "Meterstanden, eerste kwartaal 2026",
    body: "Dit document verklaart te voldoen aan het derde deel van de archiefnorm, op \
het niveau tussen het eenvoudige en het getagde: het mag een bestand van elke \
soort bevatten, en elk inktspoor op zijn pagina’s zegt voor welke letter het \
staat. De cijfers hieronder zitten ook in het bestand, als de door komma’s \
gescheiden tabel die een machine leest. Een mens opent het document en leest \
de pagina; een programma opent hetzelfde document en neemt de cijfers over \
zonder iets te lezen.",
    labels: "Januari\nFebruari\nMaart",
};

/// 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),
];

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

/// Writes the file, and says where it went.
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 languages do not overwrite each other in `tmp/`.
    let path = args
        .next()
        .unwrap_or_else(|| language.file_name(&out::default_path("pdfa3u")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    doc.set_conformance(PdfA::A3U);

    let mut facts = Metadata::default();
    facts.title = Some(words.title.to_owned());
    facts.author = Some(AUTHOR.to_owned());
    facts.subject = Some(words.subject.to_owned());
    facts.producer = Some(PRODUCER.to_owned());
    facts.created = Some(ISSUED.to_owned());
    doc.set_metadata(facts);

    doc.attach(Attachment::new(
        CARRIED_NAME,
        words.carried_what,
        CARRIED_TYPE,
        Relationship::Data,
        CHANGED,
        CARRIED.as_bytes().to_vec(),
    ));

    let font = doc.add_font(Font::parse(fs::read(&font_path)?)?);
    doc.add_page(sheet(&font, words)?)?;

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

/// The box the heading is set in.
const HEADING_BOX: Block = Block {
    size: 20.0,
    left: 72.0,
    top: 782.0,
    width: 451.0,
    set: None,
};

/// The box the body is set in.
const BODY_BOX: Block = Block {
    size: 11.0,
    left: 72.0,
    top: 736.0,
    width: 451.0,
    set: Some((16.0, Align::Justify)),
};

/// The box the labels of the record are set in, one a line.
const LABELS_BOX: Block = Block {
    size: 11.0,
    left: 72.0,
    top: 596.0,
    width: 228.0,
    set: Some((17.0, Align::Left)),
};

/// The box the figures are set in, beside the labels.
const FIGURES_BOX: Block = Block {
    size: 11.0,
    left: 300.0,
    top: 596.0,
    width: 223.0,
    set: Some((17.0, Align::Left)),
};

/// The one page, block by block.
fn sheet(font: &FontHandle, words: &Words) -> Result<Page, Error> {
    let mut c = Content::new();

    block(&mut c, font, &HEADING_BOX, words.heading)?;
    block(&mut c, font, &BODY_BOX, words.body)?;
    block(&mut c, font, &LABELS_BOX, words.labels)?;
    block(&mut c, font, &FIGURES_BOX, READINGS)?;

    let mut page = Page::a4();
    page.content = c.into_bytes();
    Ok(page)
}

/// The box one block of words goes in: its upper-left corner, how far it runs,
/// the size it is set at, and the leading and alignment where the block states
/// them.
struct Block {
    size: f64,
    left: f64,
    top: f64,
    width: f64,
    set: Option<(f64, Align)>,
}

/// Draws one block of words in the box it is given.
fn block(c: &mut Content, font: &FontHandle, at: &Block, text: &str) -> Result<(), Error> {
    let mut flow = TextFlow::new(font, at.size);
    if let Some((leading, align)) = at.set {
        flow = flow.leading(leading).align(align);
    }
    let lines = flow.break_lines(text, at.width);
    c.begin_text();
    flow.draw(c, &lines, at.left, at.top, at.width)?;
    c.end_text();
    Ok(())
}

#[cfg(test)]
mod tests {
    use hqf_pdf::{Document, Font, FontHandle, TextFlow};

    use super::{
        BODY_BOX, Block, FIGURES_BOX, HEADING_BOX, LABELS_BOX, WORDS, default_font, language,
    };

    /// The lines two languages are allowed to write the same way. No two
    /// languages write one alike.
    const SPARED: [&str; 0] = [];

    /// The least room left between a label and the column beside it.
    const GAP: f64 = 8.0;

    /// How many lines `text` takes in the box `at`.
    fn lines(font: &FontHandle, at: &Block, text: &str) -> usize {
        let mut flow = TextFlow::new(font, at.size);
        if let Some((leading, _)) = at.set {
            flow = flow.leading(leading);
        }
        flow.break_lines(text, at.width).len()
    }

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

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

    /// Every box on the page holds its words: a line meant to stand alone stays
    /// on one line, and the body ends a line above the block under it. Nothing
    /// else on the page says so when a language runs over.
    #[test]
    fn every_language_fits_the_boxes_the_page_sets_it_in() {
        let mut doc = Document::new();
        let font = doc.add_font(
            Font::parse(std::fs::read(default_font()).expect("the committed font is there"))
                .expect("the committed font parses"),
        );

        for (named, words) in WORDS {
            let code = named.code();
            assert_eq!(
                lines(&font, &HEADING_BOX, words.heading),
                1,
                "the {code} record breaks {:?} over two lines",
                words.heading
            );

            let count = lines(&font, &BODY_BOX, words.body);
            let (leading, _) = BODY_BOX.set.expect("the body states its leading");
            let held = f64::from(u32::try_from(count).expect("a body is a few lines")) * leading;
            assert!(
                held <= BODY_BOX.top - LABELS_BOX.top,
                "the {code} body takes {count} lines from {}, and the next block \
                 starts at {}",
                BODY_BOX.top,
                LABELS_BOX.top
            );

            let room = FIGURES_BOX.left - LABELS_BOX.left - GAP;
            for label in words.labels.lines() {
                let measured = font.measure(label, LABELS_BOX.size);
                assert!(
                    measured <= room,
                    "the {code} record sets {label:?} over {measured:.1} points, \
                     and it has {room:.1} before the column beside it"
                );
            }
        }
    }
}