write_codes.rs

//! Draws the two square codes a page can carry — QR and Data Matrix — at the
//! correction levels, the modes, the shapes and the sizes a request can ask
//! for.
//!
//! A square code is a grid of modules with a clear margin round it. Each box on
//! this page is filled the way a request fills it: a margin of `QUIET_ZONE`
//! modules each side — four for a QR code, one for a Data Matrix — and the grid
//! taking the rest of the width.
//!
//! What the page says about the codes is held in `Words`, once per language,
//! and `HQF_PDF_LANG` picks which set the sheet is written in. What the codes
//! carry stands apart from them: a scanner reads it, and it is the same in
//! every language.
//!
//! Usage: `cargo run --example write_codes -- tmp/codes.pdf [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_codes -- tmp/codes_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::qr::{Correction, Mode};
use hqf_pdf::{DataMatrix, Document, Error, Font, FontHandle, Page, QrCode, TextFlow};
use hqf_pdf::{datamatrix, qr};

#[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 words the sheet is written in, one set per language.
#[derive(Debug)]
struct Words {
    /// What the file says it is, in what it says of itself.
    title: &'static str,
    /// The heading at the top of the sheet.
    heading: &'static str,
    /// What stands above each row of codes, in the order the page draws them.
    captions: [&'static str; 4],
}

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

/// The sheet in English.
const ENGLISH: Words = Words {
    title: "The codes a request can ask for by shape, by size, by level and by mode",
    heading: "Codes asked for by shape, by size, by level and by mode",
    captions: [
        "The same text at the four correction levels: low, medium, quartile, high.",
        "One text to a mode: digits, capitals and punctuation, and any byte at all.",
        "A Data Matrix on a strip: the smallest oblong symbol that holds the text.",
        "A Data Matrix of a size the request names: two texts, one symbol size.",
    ],
};

/// The sheet in French.
const FRENCH: Words = Words {
    title: "Les codes qu’une requête peut demander par forme, taille, niveau et mode",
    heading: "Des codes demandés par forme, taille, niveau et mode",
    captions: [
        "Le même texte aux quatre niveaux de correction : faible, moyen, quartile, élevé.",
        "Un texte par mode : chiffres, majuscules et ponctuation, puis n’importe quel octet.",
        "Un Data Matrix en bandeau : le plus petit symbole rectangulaire qui contient le texte.",
        "Un Data Matrix de la taille que nomme la requête : deux textes, une seule taille.",
    ],
};

/// The sheet in German.
const GERMAN: Words = Words {
    title: "Die Codes, die eine Anfrage nach Form, Größe, Stufe und Modus verlangen kann",
    heading: "Codes nach Form, Größe, Stufe und Modus",
    captions: [
        "Derselbe Text in den vier Korrekturstufen: niedrig, mittel, Quartil, hoch.",
        "Ein Text pro Modus: Ziffern, Großbuchstaben mit Satzzeichen, beliebige Bytes.",
        "Ein Data-Matrix-Code als Streifen: das kleinste rechteckige Symbol für den Text.",
        "Ein Data-Matrix-Code in angefragter Größe: zwei Texte, eine Symbolgröße.",
    ],
};

/// The sheet in Spanish.
const SPANISH: Words = Words {
    title: "Los códigos que una solicitud puede pedir por forma, tamaño, nivel y modo",
    heading: "Códigos pedidos por forma, tamaño, nivel y modo",
    captions: [
        "El mismo texto en los cuatro niveles de corrección: bajo, medio, cuartil, alto.",
        "Un texto por modo: cifras, mayúsculas y puntuación, y cualquier byte.",
        "Un Data Matrix en tira: el símbolo rectangular más pequeño que contiene el texto.",
        "Un Data Matrix del tamaño que indica la petición: dos textos, un solo tamaño.",
    ],
};

/// The sheet in Italian.
const ITALIAN: Words = Words {
    title: "I codici che una richiesta può chiedere per forma, misura, livello e modo",
    heading: "Codici chiesti per forma, misura, livello e modo",
    captions: [
        "Lo stesso testo ai quattro livelli di correzione: basso, medio, quartile, alto.",
        "Un testo per ciascun modo: cifre; maiuscole e punteggiatura; qualsiasi byte.",
        "Un Data Matrix a striscia: il simbolo oblungo più piccolo che contiene il testo.",
        "Un Data Matrix della misura indicata dalla richiesta: due testi, una sola misura.",
    ],
};

/// The sheet in Portuguese.
const PORTUGUESE: Words = Words {
    title: "Os códigos que um pedido pode designar por forma, tamanho, nível e modo",
    heading: "Códigos pedidos por forma, tamanho, nível e modo",
    captions: [
        "O mesmo texto nos quatro níveis de correção: baixo, médio, quartil, alto.",
        "Um texto por modo: algarismos, maiúsculas e pontuação, e qualquer byte.",
        "Um Data Matrix em tira: o menor símbolo retangular que contém o texto.",
        "Um Data Matrix do tamanho indicado pelo pedido: dois textos, um só tamanho.",
    ],
};

/// The sheet in Dutch.
const DUTCH: Words = Words {
    title: "De codes die een verzoek naar vorm, grootte, niveau en modus kan opvragen",
    heading: "Codes opgevraagd naar vorm, grootte, niveau en modus",
    captions: [
        "Dezelfde tekst op de vier correctieniveaus: laag, gemiddeld, kwartiel, hoog.",
        "Eén tekst per modus: cijfers, hoofdletters met leestekens, en willekeurige bytes.",
        "Een Data Matrix als strook: het kleinste langwerpige symbool dat de tekst bevat.",
        "Een Data Matrix in de grootte die het verzoek noemt: twee teksten, één symboolgrootte.",
    ],
};

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

/// The box a block of words goes in, and how it is set.
struct Block {
    size: f64,
    left: f64,
    top: f64,
    width: f64,
    set: Option<(f64, Align)>,
}

/// The box a square code goes in: its lower-left corner, its width, and how
/// many modules of margin its symbology reserves each side.
struct Square {
    left: f64,
    low: f64,
    width: f64,
    quiet: usize,
}

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

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    doc.set_info(hqf_pdf::cos::Name::new("Title"), words.title);

    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 one page: every code, each under the words that name it.
fn sheet(font: &FontHandle, words: &Words) -> Result<Page, Error> {
    let mut c = Content::new();

    run_1(&mut c, font, words)?;
    run_2(&mut c, font, words)?;
    run_3(&mut c, font, words)?;
    run_4(&mut c)?;

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

/// The 1ᵗʰ run of what the page draws, in order.
fn run_1(c: &mut Content, font: &FontHandle, words: &Words) -> Result<(), Error> {
    block(
        c,
        font,
        &Block {
            size: 16.0,
            left: 56.000,
            top: 813.200,
            width: 483.000,
            set: None,
        },
        words.heading,
    )?;
    block(
        c,
        font,
        &Block {
            size: 10.5,
            left: 56.000,
            top: 782.600,
            width: 483.000,
            set: None,
        },
        words.captions[0],
    )?;
    square(
        c,
        &QrCode::with_encoding(
            "https://example.test/lot/FR-1964413",
            Mode::Byte,
            Correction::Low,
        )?,
        |c, code, x, y, side| {
            c.draw_qr(code, x, y, side)?;
            Ok(())
        },
        QrCode::size,
        &Square {
            left: 56.000,
            low: 650.000,
            width: 110.000,
            quiet: qr::QUIET_ZONE,
        },
    )?;
    square(
        c,
        &QrCode::with_encoding(
            "https://example.test/lot/FR-1964413",
            Mode::Byte,
            Correction::Medium,
        )?,
        |c, code, x, y, side| {
            c.draw_qr(code, x, y, side)?;
            Ok(())
        },
        QrCode::size,
        &Square {
            left: 180.000,
            low: 650.000,
            width: 110.000,
            quiet: qr::QUIET_ZONE,
        },
    )?;
    square(
        c,
        &QrCode::with_encoding(
            "https://example.test/lot/FR-1964413",
            Mode::Byte,
            Correction::Quartile,
        )?,
        |c, code, x, y, side| {
            c.draw_qr(code, x, y, side)?;
            Ok(())
        },
        QrCode::size,
        &Square {
            left: 304.000,
            low: 650.000,
            width: 110.000,
            quiet: qr::QUIET_ZONE,
        },
    )?;
    Ok(())
}

/// The 2ᵗʰ run of what the page draws, in order.
fn run_2(c: &mut Content, font: &FontHandle, words: &Words) -> Result<(), Error> {
    square(
        c,
        &QrCode::with_encoding(
            "https://example.test/lot/FR-1964413",
            Mode::Byte,
            Correction::High,
        )?,
        |c, code, x, y, side| {
            c.draw_qr(code, x, y, side)?;
            Ok(())
        },
        QrCode::size,
        &Square {
            left: 428.000,
            low: 650.000,
            width: 110.000,
            quiet: qr::QUIET_ZONE,
        },
    )?;
    block(
        c,
        font,
        &Block {
            size: 10.5,
            left: 56.000,
            top: 640.600,
            width: 483.000,
            set: None,
        },
        words.captions[1],
    )?;
    square(
        c,
        &QrCode::with_encoding("31964413000271026", Mode::Numeric, Correction::Medium)?,
        |c, code, x, y, side| {
            c.draw_qr(code, x, y, side)?;
            Ok(())
        },
        QrCode::size,
        &Square {
            left: 56.000,
            low: 500.000,
            width: 110.000,
            quiet: qr::QUIET_ZONE,
        },
    )?;
    square(
        c,
        &QrCode::with_encoding(
            "LOT FR-1964413/2026",
            Mode::Alphanumeric,
            Correction::Medium,
        )?,
        |c, code, x, y, side| {
            c.draw_qr(code, x, y, side)?;
            Ok(())
        },
        QrCode::size,
        &Square {
            left: 180.000,
            low: 500.000,
            width: 110.000,
            quiet: qr::QUIET_ZONE,
        },
    )?;
    square(
        c,
        &QrCode::with_encoding("lot fr-1964413", Mode::Byte, Correction::Quartile)?,
        |c, code, x, y, side| {
            c.draw_qr(code, x, y, side)?;
            Ok(())
        },
        QrCode::size,
        &Square {
            left: 304.000,
            low: 500.000,
            width: 110.000,
            quiet: qr::QUIET_ZONE,
        },
    )?;
    Ok(())
}

/// The 3ᵗʰ run of what the page draws, in order.
fn run_3(c: &mut Content, font: &FontHandle, words: &Words) -> Result<(), Error> {
    block(
        c,
        font,
        &Block {
            size: 10.5,
            left: 56.000,
            top: 490.600,
            width: 483.000,
            set: None,
        },
        words.captions[2],
    )?;
    square(
        c,
        &DataMatrix::rectangular("SN:ACME-4472")?,
        |c, code, x, y, side| {
            c.draw_data_matrix(code, x, y, side)?;
            Ok(())
        },
        DataMatrix::width,
        &Square {
            left: 56.000,
            low: 380.000,
            width: 180.000,
            quiet: datamatrix::QUIET_ZONE,
        },
    )?;
    square(
        c,
        &DataMatrix::rectangular("TUBE-77")?,
        |c, code, x, y, side| {
            c.draw_data_matrix(code, x, y, side)?;
            Ok(())
        },
        DataMatrix::width,
        &Square {
            left: 260.000,
            low: 380.000,
            width: 180.000,
            quiet: datamatrix::QUIET_ZONE,
        },
    )?;
    block(
        c,
        font,
        &Block {
            size: 10.5,
            left: 56.000,
            top: 370.600,
            width: 483.000,
            set: None,
        },
        words.captions[3],
    )?;
    square(
        c,
        &DataMatrix::with_size("FR-1964413", 16, 48)?,
        |c, code, x, y, side| {
            c.draw_data_matrix(code, x, y, side)?;
            Ok(())
        },
        DataMatrix::width,
        &Square {
            left: 56.000,
            low: 240.000,
            width: 240.000,
            quiet: datamatrix::QUIET_ZONE,
        },
    )?;
    Ok(())
}

/// The 4ᵗʰ run of what the page draws, in order.
fn run_4(c: &mut Content) -> Result<(), Error> {
    square(
        c,
        &DataMatrix::with_size("FR-2", 16, 48)?,
        |c, code, x, y, side| {
            c.draw_data_matrix(code, x, y, side)?;
            Ok(())
        },
        DataMatrix::width,
        &Square {
            left: 300.000,
            low: 240.000,
            width: 240.000,
            quiet: datamatrix::QUIET_ZONE,
        },
    )?;
    square(
        c,
        &DataMatrix::with_size("FR-1964413/2026-08", 22, 22)?,
        |c, code, x, y, side| {
            c.draw_data_matrix(code, x, y, side)?;
            Ok(())
        },
        DataMatrix::width,
        &Square {
            left: 56.000,
            low: 120.000,
            width: 120.000,
            quiet: datamatrix::QUIET_ZONE,
        },
    )?;
    Ok(())
}

/// 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(())
}

/// Draws one square code in the box it is given, with a margin of `QUIET_ZONE`
/// modules each side and the grid taking the rest of the width.
fn square<T>(
    c: &mut Content,
    code: &T,
    drawn: impl Fn(&mut Content, &T, f64, f64, f64) -> Result<(), Error>,
    across: impl Fn(&T) -> usize,
    at: &Square,
) -> Result<(), Error> {
    let modules = f64::from(u32::try_from(across(code)).unwrap_or(u32::MAX));
    let quiet = f64::from(u32::try_from(at.quiet).unwrap_or(u32::MAX));
    let unit = at.width / 2.0f64.mul_add(quiet, modules);
    c.save_state();
    c.set_fill_rgb(0.0, 0.0, 0.0)?;
    drawn(
        c,
        code,
        quiet.mul_add(unit, at.left),
        quiet.mul_add(unit, at.low),
        modules * unit,
    )?;
    c.restore_state();
    Ok(())
}

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

    use super::{WORDS, default_font, language};

    /// The width every block of words on the sheet is set in.
    const WIDTH: f64 = 483.0;

    /// The lines two languages are allowed to write the same way. What the
    /// codes carry is read by a scanner and stands apart from `Words`, and no
    /// two languages say the rest alike.
    const SPARED: [&str; 0] = [];

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

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

    /// Each block is set on one line, a row of codes standing a fixed step
    /// under it. A block broken onto a second line is drawn over the codes.
    #[test]
    fn every_block_of_every_language_stays_on_one_line() {
        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 blocks = std::iter::once((16.0, words.heading))
                .chain(words.captions.map(|caption| (10.5, caption)));
            for (size, text) in blocks {
                let lines = TextFlow::new(&font, size).break_lines(text, WIDTH).len();
                assert_eq!(
                    lines,
                    1,
                    "the {} sheet breaks {text:?} onto {lines} lines",
                    named.code()
                );
            }
        }
    }
}