One letter each, in one file

//! Writes a run of personal letters into one file, and lets its first sheet
//! jump to any of them.
//!
//! A mailing house receives one PDF and has to know where each letter starts,
//! how many sheets it runs to, and which envelope it goes in. The file says it
//! itself: each recipient is a document part that claims the next so many
//! sheets, counted rather than numbered by hand. The index on the first sheet
//! then leads to the part rather than to a page, so a letter that gains a sheet
//! moves nothing.
//!
//! Both sets of words are held in `Words`, once per language, and
//! `HQF_PDF_LANG` picks which set is drawn.
//!
//! Usage: `cargo run --example write_one_letter_each -- tmp/letters.pdf
//! [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_one_letter_each`

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

use hqf_pdf::content::Content;
use hqf_pdf::layout::Rect;
use hqf_pdf::{
    Document, DocumentPart, DocumentParts, Error, Font, FontHandle, Link, LinkTarget, Page,
    PartData, Rgb, TextFlow, Version,
};

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

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

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

use language::Language;

/// The font the page is set in when the caller names none: the one committed
/// for the tests, so the example runs on any machine.
fn default_font() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fonts")
        .join("DejaVuSans.ttf")
}

/// The words the pages are written in, one set per language.
#[derive(Debug)]
struct Words {
    /// What the file as a whole is called.
    title: &'static str,
    /// What the file carries, said once at the top of the first sheet.
    lead: &'static str,
    /// What the hierarchy says, said in grey at the foot of the first sheet.
    note: &'static str,
    /// The heading above the list of recipients.
    index_heading: &'static str,
    /// Who each of the four letters is for.
    recipients: [&'static str; 4],
    /// Where each of them is sent.
    towns: [&'static str; 4],
    /// The country every recipient is in.
    country: &'static str,
    /// The word a reference is introduced by.
    reference: &'static str,
    /// The word a subject is introduced by.
    subject: &'static str,
    /// What each of the four letters is about.
    subjects: [&'static str; 4],
    /// How a letter opens.
    greeting: &'static str,
    /// What every letter says.
    body: &'static str,
    /// How a letter closes.
    closing: &'static str,
    /// Who signs it.
    signer: &'static str,
    /// What the signer does.
    signer_role: &'static str,
    /// The heading of the sheet that follows the first letter.
    enclosure_title: &'static str,
    /// What that sheet says.
    enclosure: &'static str,
    /// The word a letter is called by.
    letter: &'static str,
    /// The word a sheet is counted by.
    sheet: &'static str,
    /// The word one sheet is counted by, in the middle of a line.
    sheet_one: &'static str,
    /// The word several sheets are counted by, in the middle of a line.
    sheet_many: &'static str,
}

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

/// The pages in English.
const ENGLISH: Words = Words {
    title: "One letter each, in one file",
    lead: "The five sheets that follow are four letters, and this index leads \
           to them. No letter names a page number, and none had to: each \
           recipient claims the next so many sheets, and the index leads to the \
           recipient rather than to a sheet. Give the second letter another \
           page and nothing above has to be counted again.",
    note: "Each entry of the index is a go-to document part action: it names \
           the part that claims the sheet, not the sheet itself, so a reader \
           following it lands on that recipient's first page wherever that page \
           has moved to. A mailing house reads the same parts to know where to \
           cut and what to fold.",
    index_heading: "Who this run is for",
    recipients: [
        "Baker and Sons",
        "Halden Joinery",
        "Westmill Dairy",
        "Corran Bookbinders",
    ],
    towns: ["Bristol", "Kendal", "Truro", "Oban"],
    country: "United Kingdom",
    reference: "Our reference:",
    subject: "Subject:",
    subjects: [
        "Your delivery window from September",
        "The crates returned in July",
        "Collection moved to Tuesdays",
        "The paper stock held for you",
    ],
    greeting: "Dear Sir or Madam,",
    body: "We are writing to every account served from this depot, because the \
           round that reaches you changes at the end of the month. Nothing you \
           have ordered is affected, and the prices agreed in March stand until \
           they are next reviewed. Should the new arrangement not suit you, \
           reply to this letter quoting the reference above and we will keep \
           the old one for you until the end of the year.",
    closing: "Yours faithfully,",
    signer: "R. Alderton",
    signer_role: "Depot manager",
    enclosure_title: "What changes, and when",
    enclosure: "The round leaves the depot an hour earlier and calls in the \
                reverse order, so an address served last is now served first. \
                Deliveries falling on a public holiday move to the working day \
                after it rather than the one before. An order placed after four \
                in the afternoon travels on the round after next, which is one \
                day later than it used to.",
    letter: "Letter",
    sheet: "Sheet",
    sheet_one: "sheet",
    sheet_many: "sheets",
};

/// The pages in French.
const FRENCH: Words = Words {
    title: "Une lettre chacun, dans un seul fichier",
    lead: "Les cinq feuillets qui suivent sont quatre lettres, et le présent \
           sommaire y mène. Aucune lettre ne nomme un numéro de page, et aucune \
           n'a eu à le faire : chaque destinataire prend les feuillets \
           suivants, autant qu'il lui en faut, et le sommaire mène au \
           destinataire plutôt qu'à un feuillet. Donnez une page de plus à la \
           deuxième lettre : rien de ce qui précède n'est à recompter.",
    note: "Chaque ligne du sommaire est une action « aller à une partie » : \
           elle nomme la partie qui revendique le feuillet, et non le feuillet \
           lui-même, de sorte qu'un lecteur qui la suit tombe sur la première \
           page de ce destinataire, où qu'elle soit passée. Un routeur lit les \
           mêmes parties pour savoir où couper et quoi plier.",
    index_heading: "À qui ce lot s'adresse",
    recipients: [
        "Boulangerie Petit",
        "Menuiserie Vallon",
        "Laiterie du Coteau",
        "Reliure de Corran",
    ],
    towns: ["Aix-en-Provence", "Annecy", "Quimper", "Sète"],
    country: "France",
    reference: "Nos références\u{00A0}:",
    subject: "Objet\u{00A0}:",
    subjects: [
        "Votre créneau de livraison à partir de septembre",
        "Les caisses rendues en juillet",
        "Ramassage reporté au mardi",
        "Le papier tenu à votre disposition",
    ],
    greeting: "Madame, Monsieur,",
    body: "Nous écrivons à tous les comptes desservis par ce dépôt, car la \
           tournée qui vous dessert change à la fin du mois. Rien de ce que \
           vous avez commandé n'est touché, et les prix convenus en mars \
           tiennent jusqu'à leur prochaine révision. Si la nouvelle \
           organisation ne vous convient pas, répondez à ce courrier en citant \
           la référence ci-dessus et nous vous garderons l'ancienne jusqu'à la \
           fin de l'année.",
    closing: "Veuillez agréer nos salutations distinguées.",
    signer: "R. Alderton",
    signer_role: "Responsable du dépôt",
    enclosure_title: "Ce qui change, et quand",
    enclosure: "La tournée quitte le dépôt une heure plus tôt et passe dans \
                l'ordre inverse : une adresse desservie en dernier l'est \
                désormais en premier. Une livraison qui tombe un jour férié est \
                reportée au jour ouvré suivant plutôt qu'au précédent. Une \
                commande passée après seize heures part à la tournée d'après, \
                soit un jour plus tard qu'auparavant.",
    letter: "Lettre",
    sheet: "Feuillet",
    sheet_one: "feuillet",
    sheet_many: "feuillets",
};

/// 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 left edge of everything on the pages.
const LEFT: f64 = 72.0;

/// How wide a block of text is.
const WIDTH: f64 = 451.0;

/// The reference each letter is written under.
const REFERENCES: [&str; 4] = ["CT-4711", "CT-4712", "CT-4713", "CT-4714"];

/// How many sheets each letter runs to. The first carries an enclosure; the
/// others are a single sheet.
const SHEETS: [u8; 4] = [2, 1, 1, 1];

/// The first sheet of each letter, counting the index as sheet zero.
///
/// This is the same running count the parts themselves are given, said once so
/// that the index and the hierarchy cannot drift apart.
fn first_sheets() -> [usize; 4] {
    let mut first = [0_usize; 4];
    let mut cursor = 1;
    for (index, run) in SHEETS.iter().enumerate() {
        first[index] = cursor;
        cursor += usize::from(*run);
    }
    first
}

/// Sets a block of words with its first baseline at `top`, and hands back the
/// ordinate the block ends at.
fn block(
    c: &mut Content,
    handle: &FontHandle,
    size: f64,
    top: f64,
    text: &str,
) -> Result<f64, Error> {
    let flow = TextFlow::new(handle, size);
    let lines = flow.break_lines(text, WIDTH);
    c.begin_text();
    flow.draw(c, &lines, LEFT, top, WIDTH)?;
    c.end_text();
    Ok(top - flow.height(&lines))
}

/// Sets one line of the index, and hands back the ordinate it ends at together
/// with the rectangle it covers.
fn index_line(
    c: &mut Content,
    handle: &FontHandle,
    top: f64,
    text: &str,
) -> Result<(f64, Rect), Error> {
    let flow = TextFlow::new(handle, 10.5);
    let lines = flow.break_lines(text, WIDTH);
    let boxes = flow.line_boxes(&lines, LEFT, top, WIDTH);
    c.begin_text();
    flow.draw(c, &lines, LEFT, top, WIDTH)?;
    c.end_text();
    let covered = boxes
        .first()
        .copied()
        .ok_or(Error::NoSuchPage { page: 0 })?;
    Ok((top - flow.height(&lines), covered))
}

/// How a letter is announced in the index.
fn entry(words: &Words, index: usize) -> String {
    let sheets = if SHEETS[index] > 1 {
        words.sheet_many
    } else {
        words.sheet_one
    };
    format!(
        "{} \u{2014} {} \u{2014} {} \u{2014} {} {sheets}",
        words.recipients[index], words.towns[index], REFERENCES[index], SHEETS[index]
    )
}

/// Draws the foot of a sheet: which letter it belongs to, and where it stands
/// in it.
fn foot(
    c: &mut Content,
    words: &Words,
    text: &FontHandle,
    index: usize,
    sheet: usize,
) -> Result<(), Error> {
    let flow = TextFlow::new(text, 8.0);
    let line = format!(
        "{} {}/{} \u{2014} {} \u{2014} {} {}/{}",
        words.letter,
        index + 1,
        SHEETS.len(),
        words.recipients[index],
        words.sheet,
        sheet + 1,
        SHEETS[index]
    );
    c.set_fill(Rgb::gray(0.45))?;
    c.begin_text();
    flow.draw(c, &flow.break_lines(&line, WIDTH), LEFT, 56.0, WIDTH)?;
    c.end_text();
    c.set_fill(Rgb::gray(0.0))?;
    Ok(())
}

/// Draws the index sheet, and hands back the links its entries carry.
fn index_sheet(words: &Words, text: &FontHandle) -> Result<(Vec<u8>, Vec<Link>), Error> {
    let mut c = Content::new();
    let mut top = block(&mut c, text, 17.0, 782.0, words.title)? - 12.0;
    top = block(&mut c, text, 9.5, top, words.lead)? - 26.0;
    top = block(&mut c, text, 13.0, top, words.index_heading)? - 14.0;

    let mut links = Vec::with_capacity(SHEETS.len());
    for (index, first) in first_sheets().into_iter().enumerate() {
        let (below, covered) = index_line(&mut c, text, top, &entry(words, index))?;
        // The link names the part that claims that sheet, not the sheet: the
        // recipient is what a reader is after, and the part is what says where
        // the recipient begins.
        links.push(covered.link(LinkTarget::Part(first)));
        top = below - 7.0;
    }

    c.set_fill(Rgb::gray(0.35))?;
    block(&mut c, text, 8.5, top - 20.0, words.note)?;
    c.set_fill(Rgb::gray(0.0))?;
    Ok((c.into_bytes(), links))
}

/// Draws the sheet one letter is written on.
fn letter_sheet(words: &Words, text: &FontHandle, index: usize) -> Result<Vec<u8>, Error> {
    let mut c = Content::new();
    let mut top = block(&mut c, text, 13.0, 782.0, words.recipients[index])? - 6.0;
    let whereabouts = format!("{}, {}", words.towns[index], words.country);
    top = block(&mut c, text, 9.0, top, &whereabouts)? - 22.0;

    let heading = format!("{} {}", words.reference, REFERENCES[index]);
    top = block(&mut c, text, 9.0, top, &heading)? - 6.0;
    let about = format!("{} {}", words.subject, words.subjects[index]);
    top = block(&mut c, text, 10.0, top, &about)? - 20.0;

    top = block(&mut c, text, 9.5, top, words.greeting)? - 12.0;
    top = block(&mut c, text, 9.5, top, words.body)? - 22.0;
    top = block(&mut c, text, 9.5, top, words.closing)? - 20.0;
    top = block(&mut c, text, 9.5, top, words.signer)? - 4.0;
    block(&mut c, text, 8.5, top, words.signer_role)?;

    foot(&mut c, words, text, index, 0)?;
    Ok(c.into_bytes())
}

/// Draws the sheet enclosed with the first letter.
fn enclosure_sheet(words: &Words, text: &FontHandle) -> Result<Vec<u8>, Error> {
    let mut c = Content::new();
    let top = block(&mut c, text, 13.0, 782.0, words.enclosure_title)? - 14.0;
    block(&mut c, text, 9.5, top, words.enclosure)?;
    foot(&mut c, words, text, 0, 1)?;
    Ok(c.into_bytes())
}

/// What one letter states about itself, for whatever sends it.
fn stated(words: &Words, index: usize) -> Result<PartData, Error> {
    PartData::new()
        .set("Recipient", words.recipients[index])?
        .set("Town", words.towns[index])?
        .set("Reference", REFERENCES[index])?
        .set("Sheets", SHEETS[index])
}

/// The hierarchy: the index, then one part per recipient, each taking the
/// sheets that follow rather than naming them.
fn hierarchy(words: &Words) -> Result<DocumentParts, Error> {
    let mut run = DocumentPart::new().child(
        DocumentPart::new()
            .next_pages(1)
            .data(PartData::new().set("Section", "Index")?),
    );
    for (index, run_of) in SHEETS.iter().enumerate() {
        run = run.child(
            DocumentPart::new()
                .next_pages(usize::from(*run_of))
                .data(stated(words, index)?),
        );
    }
    Ok(DocumentParts::new(run))
}

/// Draws the index and the four letters, and says which sheets belong to whom.
fn build(words: &Words, font: &Path) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    // The hierarchy of document parts, and the action that leads to one, are
    // written on PDF 2.0 and on nothing earlier.
    doc.set_version(Version::V2_0);
    let text = doc.add_font(Font::parse(fs::read(font)?)?);

    let (drawn, links) = index_sheet(words, &text)?;
    let mut index = Page::a4();
    index.content = drawn;
    index.links = links;
    doc.add_page(index)?;

    for (letter, run_of) in SHEETS.iter().enumerate() {
        let mut sheet = Page::a4();
        sheet.content = letter_sheet(words, &text, letter)?;
        doc.add_page(sheet)?;
        if *run_of > 1 {
            let mut enclosed = Page::a4();
            enclosed.content = enclosure_sheet(words, &text)?;
            doc.add_page(enclosed)?;
        }
    }

    doc.set_document_parts(hierarchy(words)?);
    Ok(doc.to_bytes()?)
}

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

    let bytes = build(words, &font_path)?;

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

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

    use super::{REFERENCES, SHEETS, WIDTH, WORDS, default_font, first_sheets, language};

    /// The font the pages are set in, to measure what they draw.
    fn handle() -> FontHandle {
        let mut doc = hqf_pdf::Document::new();
        doc.add_font(
            Font::parse(std::fs::read(default_font()).expect("the test font")).expect("a font"),
        )
    }

    /// The lines two languages are allowed to write the same way: the person
    /// who signs the letters has the same name in both.
    const SPARED: [&str; 1] = ["signer: \"R. Alderton\""];

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

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

    #[test]
    fn the_index_leads_to_the_sheet_each_letter_opens_on() {
        let first = first_sheets();

        // The index is sheet zero, so the first letter opens on sheet one and
        // each one after it opens where the one before it stopped.
        assert_eq!(first, [1, 3, 4, 5]);
        for (index, opening) in first.into_iter().enumerate() {
            let claimed = opening + usize::from(SHEETS[index]);
            assert!(
                index + 1 == SHEETS.len() || first[index + 1] == claimed,
                "letter {index} ends at {claimed} and the next opens elsewhere"
            );
        }
    }

    #[test]
    fn every_letter_has_a_recipient_a_town_a_subject_and_a_reference() {
        for (_, words) in &WORDS {
            assert_eq!(words.recipients.len(), SHEETS.len());
            assert_eq!(words.towns.len(), SHEETS.len());
            assert_eq!(words.subjects.len(), SHEETS.len());
        }
        assert_eq!(REFERENCES.len(), SHEETS.len());
    }

    #[test]
    fn every_entry_of_the_index_is_set_on_one_line() {
        let font = handle();
        for (_, words) in &WORDS {
            for index in 0..SHEETS.len() {
                let entry = super::entry(words, index);
                assert!(
                    font.measure(&entry, 10.5) <= WIDTH,
                    "{entry:?} needs {} of {WIDTH}",
                    font.measure(&entry, 10.5)
                );
            }
        }
    }

    #[test]
    fn every_subject_a_letter_states_fits_the_line_it_is_set_on() {
        let font = handle();
        for (_, words) in &WORDS {
            for subject in words.subjects {
                let line = format!("{} {subject}", words.subject);
                assert!(
                    font.measure(&line, 10.0) <= WIDTH,
                    "{line:?} needs {} of {WIDTH}",
                    font.measure(&line, 10.0)
                );
            }
        }
    }
}