write_flow_break.rs

//! Sets one paragraph in a column too narrow for a word in it, three times: as
//! it comes, cut to the column, and cut with a hyphen ending each cut line.
//!
//! The paragraph and the three headings are held in `Words`, once per language,
//! and `HQF_PDF_LANG` picks which set is drawn. Each heading opens with the
//! name the library gives its setting, which is the same in every language.
//!
//! Usage: `cargo run --example write_flow_break -- tmp/flow_break.pdf
//! [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_flow_break --
//! tmp/coupure.pdf`

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

use hqf_pdf::content::Content;
use hqf_pdf::layout::Overlong;
use hqf_pdf::{Document, Font, 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: the
/// one committed for the tests, so that the example runs on any machine.
fn default_font() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fonts")
        .join("DejaVuSans.ttf")
}

/// The payment reference the paragraph carries: one word to a line breaker,
/// longer than the column it is put in, and the same in every language.
const REFERENCE: &str = "GB29NWBK60161331926819-2026-07-DEPOSIT";

/// The words the page is written in, one set per language.
///
/// What is not language stays out of it: the payment reference reads the same
/// wherever the page is read, and each heading opens with the name the library
/// gives the setting it stands over.
#[derive(Debug)]
struct Words {
    /// The heading over the setting that leaves the long word whole.
    overflow: &'static str,
    /// The heading over the setting that cuts it.
    breaking: &'static str,
    /// The heading over the setting that cuts it and marks each cut.
    marked: &'static str,
    /// The paragraph, cut where the reference goes into it.
    paragraph_before: &'static str,
    paragraph_after: &'static str,
}

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

    /// The paragraph both settings are given, with the reference in it.
    fn paragraph(&self) -> String {
        format!(
            "{}{REFERENCE}{}",
            self.paragraph_before, self.paragraph_after
        )
    }
}

/// The page in English.
const ENGLISH: Words = Words {
    overflow: "Overflow: the word is left whole, and runs past the edge.",
    breaking: "Break: the word is cut after its last glyph that fits.",
    marked: "Break with a cut mark: each line the cut closes ends on a hyphen.",
    paragraph_before: "Paid by bank transfer, reference ",
    paragraph_after: ", to be matched against the purchase order before the accounts are closed.",
};

/// The page in French.
const FRENCH: Words = Words {
    overflow: "Débordement : le mot reste entier et dépasse le bord.",
    breaking: "Coupure : le mot est coupé après le dernier glyphe qui tient.",
    marked: "Coupure avec marque de coupure : chaque ligne coupée finit par un trait d’union.",
    paragraph_before: "Réglé par virement, référence ",
    paragraph_after: ", à rapprocher du bon de commande avant la clôture des comptes.",
};

/// The page in Dutch.
const DUTCH: Words = Words {
    overflow: "Overlopen: het woord blijft heel en loopt over de rand.",
    breaking: "Afbreken: het woord wordt na zijn laatste passende glyph afgebroken.",
    marked: "Afbreken met koppelteken: elke afgebroken regel eindigt op een koppelteken.",
    paragraph_before: "Betaald per overschrijving, kenmerk",
    paragraph_after: ", af te stemmen met de inkooporder voordat de boeken worden afgesloten.",
};

/// The page in Portuguese.
const PORTUGUESE: Words = Words {
    overflow: "Transbordar: a palavra fica inteira e sai da margem.",
    breaking: "Quebrar: a palavra é cortada após o último glifo que cabe.",
    marked: "Quebrar com marca: cada linha que o corte fecha acaba num hífen.",
    paragraph_before: "Pago por transferência, referência",
    paragraph_after: ", a conferir com a nota de encomenda antes do fecho de contas.",
};

/// The page in Italian.
const ITALIAN: Words = Words {
    overflow: "Sborda: la parola resta intera ed esce dal bordo.",
    breaking: "Spezza: la parola è tagliata dopo l’ultimo glifo che ci sta.",
    marked: "Spezza con segno: ogni riga chiusa dal taglio finisce con un trattino.",
    paragraph_before: "Pagato con bonifico, riferimento",
    paragraph_after: ", da confrontare con l’ordine d’acquisto prima della chiusura dei conti.",
};

/// The page in Spanish.
const SPANISH: Words = Words {
    overflow: "Desbordar: la palabra queda entera y sale del borde.",
    breaking: "Cortar: la palabra se corta tras el último glifo que cabe.",
    marked: "Cortar con marca: cada línea cortada acaba en guion.",
    paragraph_before: "Pagado por transferencia, referencia ",
    paragraph_after: ", que se cotejará con la orden de compra antes del cierre contable.",
};

/// The page in German.
const GERMAN: Words = Words {
    overflow: "Überlauf: Das Wort bleibt ganz und läuft über den Rand hinaus.",
    breaking: "Umbruch: Das Wort wird nach seinem letzten passenden Glyphen getrennt.",
    marked: "Umbruch mit Trennzeichen: Jede getrennte Zeile endet auf einem Bindestrich.",
    paragraph_before: "Bezahlt per Banküberweisung, Verwendungszweck ",
    paragraph_after: ", vor dem Abschluss der Bücher mit der Bestellung abzugleichen.",
};

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

const COLUMN: f64 = 150.0;

/// The left edge of both columns. They are stacked rather than set side by
/// side, so that the overflowing line runs out into the margin and not through
/// the text of the other setting.
const X: f64 = 80.0;

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 paragraph = words.paragraph();

    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("flow_break")));
    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 handle = doc.add_font(font);

    let mut c = Content::new();

    for (top, label, overlong, mark) in [
        (760.0, words.overflow, Overlong::Overflow, None),
        (620.0, words.breaking, Overlong::Break, None),
        (480.0, words.marked, Overlong::Break, Some('-')),
    ] {
        let heading = TextFlow::new(&handle, 8.0);
        let heading_lines = heading.break_lines(label, 400.0);
        c.begin_text();
        heading.draw(&mut c, &heading_lines, X, top, 400.0)?;
        c.end_text();

        let text_top = top - 20.0;
        let flow = TextFlow::new(&handle, 11.0)
            .leading(15.0)
            .overlong(overlong)
            .cut_mark(mark);
        let lines = flow.break_lines(&paragraph, COLUMN);
        c.begin_text();
        flow.draw(&mut c, &lines, X, text_top, COLUMN)?;
        c.end_text();

        // The column's edge, to show what each setting does about it.
        let height = flow.height(&lines);
        c.save_state();
        c.set_stroke_rgb(0.8, 0.8, 0.8)?
            .set_line_width(0.5)?
            .rect(X, text_top - height, COLUMN, height)?
            .stroke();
        c.restore_state();
    }

    let mut page = Page::a4();
    page.content = c.into_bytes();
    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", bytes.len());
    Ok(())
}

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

    /// The lines two languages are allowed to write the same way. There are
    /// none: the reference the paragraph carries is held outside the words.
    const SPARED: [&str; 0] = [];

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

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