A page whose letters cost one byte each

//! Sets a page whose every letter is one byte in the stream rather than two,
//! and states what that costs and what it buys.
//!
//! A font is reached by glyph index unless it is told otherwise: two bytes a
//! glyph, and every glyph the face holds within reach. Reached through a simple
//! encoding it is addressed by one-byte codes instead, at most 255 of them, and
//! the file states which character each code stands for. The page weighs the
//! same three lines both ways and prints the two figures it measured.
//!
//! The single byte also gives word spacing something to reach: the operator
//! moves the pen at the byte 32 and at no other code, so the last two lines of
//! the page are the same words drawn without it and with it.
//!
//! 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_simple_encoding -- [out.pdf] [face.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_simple_encoding`

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

use hqf_pdf::content::Content;
use hqf_pdf::font::encoding::{Encoding, SimpleEncoding};
use hqf_pdf::{Document, Font, FontHandle, Page, Rgb, 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 page is set in when none is given on the command line: 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 page is written in, one set per language.
#[derive(Debug)]
struct Words {
    /// The page's title.
    title: &'static str,
    /// What the page is about.
    lead: &'static str,
    /// The label over the three lines set through one-byte codes.
    shown: &'static str,
    /// The three lines, drawn through the encoding.
    samples: [&'static str; 3],
    /// The label over the codes the encoding settled.
    codes: &'static str,
    /// The sentence the first of those codes are put into.
    settled: &'static str,
    /// The label over what the two streams weigh.
    weight: &'static str,
    /// The sentence the two weights are put into.
    weighed: &'static str,
    /// The label over the two lines that show word spacing.
    spacing: &'static str,
    /// The line drawn twice, once with word spacing and once without.
    pushed: &'static str,
    /// What those two lines show.
    spread: &'static str,
    /// What an encoding of one byte cannot do.
    caveat: &'static str,
}

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

    /// Every character the page draws through the encoding, the samples first:
    /// the encoding hands out its codes in the order it meets its characters,
    /// so the lines the page lists the codes of are the ones that take the
    /// first codes.
    fn drawn(&self) -> String {
        let mut text = self.samples.concat();
        text.push_str(self.pushed);
        text
    }
}

/// The page in English.
const ENGLISH: Words = Words {
    title: "A page addressed by one-byte codes",
    lead: "Every letter on the three lines below costs one byte of this file's \
           page stream instead of two. A font is reached by glyph index unless \
           it is told otherwise, two bytes a glyph, which puts every glyph the \
           face holds within reach. Reached through an encoding it is addressed \
           by one-byte codes instead: at most 255 of them, each standing for one \
           character, and the file states which character each of them stands \
           for.",
    shown: "Set through one-byte codes",
    samples: [
        "HQF Development",
        "An invoice, a payslip, a delivery note.",
        "One byte a letter, and the file says which.",
    ],
    codes: "The codes it settled",
    settled: "The encoding is fitted to the words this page draws: the space \
              keeps code 32, and every other character takes the lowest code \
              free from 33 up, so nothing in the stream is a byte a reader has \
              to escape. The first of them are %codes%.",
    weight: "What the stream weighs",
    weighed: "Drawn by glyph index, the three lines above cost %identity% bytes \
              of page stream; drawn through one-byte codes, %simple% bytes, \
              which is %saved% less. Both figures are measured by the program \
              that drew this page, not written in by hand.",
    spacing: "What the single byte 32 buys",
    pushed: "Words a reader can push apart.",
    spread: "The two lines above hold the same characters. The second is drawn \
             with word spacing set, which moves the pen at the single byte 32 \
             and at no other code. Under glyph indices no code is a single byte \
             32, so the operator has nothing to reach and the words never move; \
             the space of this encoding sits at 32, so they do.",
    caveat: "One byte addresses 255 characters at a time, so a page of several \
             alphabets is still reached by glyph index. No ligature and no small \
             capital is drawn through an encoding either: those are glyphs no \
             character stands for, and a code stands for a character. A file \
             that claims archival conformance states the Windows encoding as the \
             one its codes are read against, which this one does.",
};

/// The page in French.
const FRENCH: Words = Words {
    title: "Une page adressée par des codes d'un octet",
    lead: "Chaque lettre des trois lignes ci-dessous coûte un octet du flux de \
           cette page, et non deux. Une police est atteinte par indice de dessin \
           tant qu'on ne dit rien d'autre, deux octets par dessin, ce qui met à \
           portée tous les dessins qu'elle porte. Atteinte par un encodage, elle \
           est adressée par des codes d'un octet : 255 au plus, chacun \
           représentant un caractère, et le fichier dit quel caractère chacun \
           d'eux représente.",
    shown: "Composé avec des codes d'un octet",
    samples: [
        "HQF Development",
        "Une facture, un bulletin, un bon de livraison.",
        "Un octet par lettre, et le fichier dit lequel.",
    ],
    codes: "Les codes qu'il a fixés",
    settled: "L'encodage est ajusté aux mots que cette page dessine : l'espace \
              garde le code 32, et chaque autre caractère prend le plus petit \
              code libre à partir de 33, si bien qu'aucun octet du flux n'est à \
              protéger à la lecture. Les premiers sont %codes%.",
    weight: "Ce que le flux pèse",
    weighed: "Dessinées par indice, les trois lignes ci-dessus coûtent \
              %identity% octets de flux de page ; dessinées par des codes d'un \
              octet, %simple% octets, soit %saved% de moins. Les deux chiffres \
              sont mesurés par le programme qui a dessiné cette page, pas écrits \
              à la main.",
    spacing: "Ce que l'octet 32 rapporte",
    pushed: "Des mots qu'un lecteur peut écarter.",
    spread: "Les deux lignes ci-dessus portent les mêmes caractères. La seconde \
             est dessinée avec l'écartement des mots, qui pousse la plume sur \
             l'octet 32 et sur aucun autre code. Par indice de dessin, aucun \
             code ne vaut l'octet 32 seul : l'opérateur n'a rien à atteindre et \
             les mots ne bougent jamais ; l'espace de cet encodage est en 32, \
             donc ils bougent.",
    caveat: "Un octet adresse 255 caractères à la fois : une page qui mêle \
             plusieurs alphabets reste atteinte par indice de dessin. Aucune \
             ligature ni aucune petite capitale ne se dessine non plus par un \
             encodage : ce sont des dessins qu'aucun caractère ne représente, et \
             un code représente un caractère. Un fichier qui revendique \
             l'archivage annonce l'encodage de Windows comme celui contre lequel \
             ses codes se lisent, ce que celui-ci fait.",
};

/// 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 page.
const LEFT: f64 = 72.0;

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

/// The size the three samples are drawn at.
const SAMPLE: f64 = 14.0;

/// The size the two lines showing word spacing are drawn at.
const SPACED: f64 = 12.0;

/// How far apart the second of those two lines pushes its words.
const WORD_SPACING: f64 = 6.0;

/// 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, Box<dyn std::error::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))
}

/// What the three samples cost in a page stream, drawn through `handle`.
///
/// The two handles write the same operators around the same three lines, so
/// what one weighs against the other is what the codes weigh against the
/// indices.
fn stream_bytes(handle: &FontHandle, words: &Words) -> Result<usize, Box<dyn std::error::Error>> {
    let mut c = Content::new();
    let mut top = 700.0;
    for sample in words.samples {
        top = block(&mut c, handle, SAMPLE, top, sample)? - 10.0;
    }
    Ok(c.as_bytes().len())
}

/// The first `count` characters of the samples, each beside the code that
/// reaches it.
fn settled(encoding: &SimpleEncoding, words: &Words, count: usize) -> String {
    let mut seen: Vec<char> = Vec::new();
    for character in words.samples.concat().chars() {
        if character != ' ' && !seen.contains(&character) {
            seen.push(character);
        }
    }
    seen.iter()
        .filter_map(|character| {
            encoding
                .code(*character)
                .map(|code| format!("{character} {code}"))
        })
        .take(count)
        .collect::<Vec<String>>()
        .join(" · ")
}

/// Draws the whole page.
fn build(
    words: &Words,
    font: Font,
    encoding: &SimpleEncoding,
) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let one_byte = font
        .clone()
        .with_encoding(Encoding::Simple(encoding.clone()))?;

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    let text = doc.add_font(font);
    let drawn = doc.add_font(one_byte);

    let mut c = Content::new();
    let mut top = 780.0;
    top = block(&mut c, &text, 18.0, top, words.title)? - 14.0;
    top = block(&mut c, &text, 10.0, top, words.lead)? - 22.0;

    top = block(&mut c, &text, 12.0, top, words.shown)? - 12.0;
    for sample in words.samples {
        top = block(&mut c, &drawn, SAMPLE, top, sample)? - 8.0;
    }

    top -= 14.0;
    top = block(&mut c, &text, 12.0, top, words.codes)? - 10.0;
    let listed = words
        .settled
        .replace("%codes%", &settled(encoding, words, 8));
    top = block(&mut c, &text, 10.0, top, &listed)? - 20.0;

    let (indices, codes) = (stream_bytes(&text, words)?, stream_bytes(&drawn, words)?);
    top = block(&mut c, &text, 12.0, top, words.weight)? - 10.0;
    let said = words
        .weighed
        .replace("%identity%", &spaced(indices))
        .replace("%simple%", &spaced(codes))
        .replace("%saved%", &spaced(indices - codes));
    top = block(&mut c, &text, 10.0, top, &said)? - 20.0;

    top = block(&mut c, &text, 12.0, top, words.spacing)? - 12.0;
    top = block(&mut c, &drawn, SPACED, top, words.pushed)? - 8.0;
    c.set_word_spacing(WORD_SPACING)?;
    top = block(&mut c, &drawn, SPACED, top, words.pushed)? - 18.0;
    c.set_word_spacing(0.0)?;
    top = block(&mut c, &text, 10.0, top, words.spread)? - 20.0;

    c.set_fill(Rgb::gray(0.35))?;
    block(&mut c, &text, 9.0, top, words.caveat)?;

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

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

    let font = Font::parse(fs::read(&face)?)?;
    let encoding = SimpleEncoding::fitting(&font, &words.drawn())?;
    let drawn = build(words, font, &encoding)?;

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

/// A count with a space between its thousands, which is how every language this
/// example is written in writes one.
fn spaced(count: usize) -> String {
    let digits = count.to_string();
    let mut out = String::with_capacity(digits.len() + digits.len() / 3);
    for (index, digit) in digits.chars().enumerate() {
        if index > 0 && (digits.len() - index) % 3 == 0 {
            out.push('\u{00A0}');
        }
        out.push(digit);
    }
    out
}

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

    use super::{SAMPLE, SPACED, WIDTH, WORD_SPACING, WORDS, default_font, language, spaced};

    /// The lines two languages are allowed to write the same way: the name of
    /// the firm is the same whoever reads it.
    const SPARED: [&str; 1] = ["\"HQF Development\""];

    /// The committed font, parsed.
    fn fixture() -> Font {
        Font::parse(std::fs::read(default_font()).expect("the committed font is there"))
            .expect("the committed font parses")
    }

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

    /// A sample wider than the block is broken over two lines, which moves
    /// everything under it up the page.
    #[test]
    fn every_language_writes_samples_that_fit_the_block_they_have() {
        let mut doc = Document::new();
        let handle = doc.add_font(fixture());

        for (named, words) in WORDS {
            for sample in words.samples {
                let measured = handle.measure(sample, SAMPLE);
                assert!(
                    measured <= WIDTH,
                    "the {} page draws {sample:?} over {measured:.1} points, \
                     and it has {WIDTH:.1}",
                    named.code()
                );
            }
        }
    }

    /// Word spacing moves the pen without moving the measurement: the line it
    /// is set on draws wider than the measurement says, by the spacing times
    /// the number of spaces, and the block it is drawn in does not know that.
    #[test]
    fn every_language_pushes_its_words_apart_within_the_block() {
        let mut doc = Document::new();
        let handle = doc.add_font(fixture());

        for (named, words) in WORDS {
            let spaces = u32::try_from(words.pushed.chars().filter(|c| *c == ' ').count())
                .expect("a line of few words");
            let drawn =
                WORD_SPACING.mul_add(f64::from(spaces), handle.measure(words.pushed, SPACED));
            assert!(
                drawn <= WIDTH,
                "the {} page pushes {:?} out to {drawn:.1} points, and it has {WIDTH:.1}",
                named.code(),
                words.pushed
            );
        }
    }

    /// The page states the codes it settled, so it has to have settled them:
    /// the encoding is fitted to what the page draws, and a character it left
    /// out would be drawn as nothing at all.
    #[test]
    fn every_language_has_a_code_for_every_character_it_draws() {
        let font = fixture();

        for (named, words) in WORDS {
            let encoding =
                SimpleEncoding::fitting(&font, &words.drawn()).expect("one page fits 255 codes");

            for character in words.drawn().chars() {
                assert!(
                    encoding.code(character).is_some(),
                    "the {} page draws {character:?}, and no code reaches it",
                    named.code()
                );
            }
        }
    }

    /// Every code the page draws through stands in the printable range, so the
    /// stream holds no byte a reader has to escape.
    #[test]
    fn the_codes_the_page_draws_through_are_all_printable() {
        let font = fixture();

        for (_, words) in WORDS {
            let encoding =
                SimpleEncoding::fitting(&font, &words.drawn()).expect("one page fits 255 codes");

            for character in words.drawn().chars() {
                let code = encoding.code(character).expect("a code reaches it");
                assert!(code >= 32, "{character:?} is reached by {code}");
            }
        }
    }

    #[test]
    fn a_count_is_written_with_a_space_between_its_thousands() {
        assert_eq!(spaced(7), "7");
        assert_eq!(spaced(999), "999");
        assert_eq!(spaced(1000), "1\u{00A0}000");
        assert_eq!(spaced(8117), "8\u{00A0}117");
    }
}