Une carte d'embarquement

//! Draws an airline boarding pass: the passenger and their flight, the route,
//! the times and the seat, a detachable stub down the side, and the code the
//! gate scanner reads.
//!
//! The code is not decoration. It carries an IATA Resolution 792 bar coded
//! boarding pass: one fixed-width line, every field at its appointed offset,
//! starting `M1` for a single leg and running through the name, the booking
//! reference, the two airports, the carrier, the flight, the Julian day, the
//! compartment, the seat, the check-in sequence and the passenger status. A
//! mobile pass carries that line as a two-dimensional symbol, and this one
//! carries it as a QR code.
//!
//! Whether that code boards is not for the page to say, and not for an eye: a
//! scanner says. `scripts/check_qr.sh` points a decoder at the rendered page
//! and reads the line back.
//!
//! Every word the page draws is held in `Words`, once per language, and
//! `HQF_PDF_LANG` picks which one is drawn. The passenger, the booking
//! reference, the airports, the flight, the times, the seat and the line the
//! gate scanner reads are the same in both.
//!
//! Usage: `cargo run --example write_boarding_pass -- tmp/pass.pdf [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_boarding_pass --
//! tmp/carte.pdf`

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

use hqf_pdf::content::Content;
use hqf_pdf::cos::Name;
use hqf_pdf::{Document, Font, FontHandle, Page, QrCode, Rgb};

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

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

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

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 card, in points: the width of an A4 sheet, a third of its height.
const PAGE_WIDTH: f64 = 595.276;
const PAGE_HEIGHT: f64 = 283.465;

/// The card's left edge, the right edge of the part the passenger keeps, and
/// the perforation the stub tears along.
const LEFT: f64 = 24.0;
const MAIN_RIGHT: f64 = 416.0;
const PERFORATION: f64 = 430.0;
/// The stub's own left edge and, mirrored from the card, its right.
const STUB_LEFT: f64 = 444.0;
const STUB_RIGHT: f64 = PAGE_WIDTH - LEFT;
/// The band across the head of the card, from this height to the top.
const BAND_BOTTOM: f64 = PAGE_HEIGHT - 40.0;
/// The right edge of the column the fields are set in, left of the code.
const FIELDS_RIGHT: f64 = 296.0;

/// The ink the airport codes and the head band are drawn in, the grey of the
/// labels and the small print, and the near-black of the values.
const ACCENT: Rgb = Rgb {
    r: 0.11,
    g: 0.33,
    b: 0.55,
};
const MUTED: Rgb = Rgb {
    r: 0.42,
    g: 0.42,
    b: 0.45,
};
const INK: Rgb = Rgb {
    r: 0.1,
    g: 0.1,
    b: 0.12,
};

/// Who is flying, and under which booking.
const PASSENGER: &str = "MOREAU/CLAIRE MS";
const PNR: &str = "K4RT9Z";

/// The flight: where from, where to, whose aircraft, and which number. The
/// carrier is the two-letter designator the operator files under.
const FROM: &str = "MRS";
const TO: &str = "LHR";
const CARRIER: &str = "HQ";
const FLIGHT: &str = "0421";

/// The day of the flight, as the card writes it and as the code writes it: the
/// ordinal day of the year, which is what Resolution 792 carries.
const DATE: &str = "20 JUL 2026";
const JULIAN: &str = "201";

/// When boarding opens and when the aircraft leaves, and where to be.
const BOARDING: &str = "09:35";
const DEPARTURE: &str = "10:05";
const GATE: &str = "B14";

/// The seat, its compartment, the order the passenger checked in, and whether
/// they are checked in: status `1` is.
const SEAT: &str = "014A";
const COMPARTMENT: &str = "Y";
const SEQUENCE: &str = "0031";
const STATUS: &str = "1";

/// Every word the page draws, in one language.
///
/// What is not language stays out of it: the passenger, the booking reference,
/// the airports, the flight, the times, the seat and the line the gate scanner
/// reads are drawn from constants of their own and read the same in every
/// language.
#[derive(Debug)]
struct Words {
    /// The words the document's title is built from, and the words set at the
    /// right of the head band.
    title: &'static str,
    heading: &'static str,
    /// The three fields across the top of the card, and what the last of them
    /// says.
    passenger: &'static str,
    booking_ref: &'static str,
    status_label: &'static str,
    status_value: &'static str,
    /// What the two airports are called under their codes.
    from_name: &'static str,
    to_name: &'static str,
    /// The eight field names down the card, and what the class field says.
    flight: &'static str,
    date: &'static str,
    boarding: &'static str,
    departs: &'static str,
    gate: &'static str,
    seat: &'static str,
    class_label: &'static str,
    class_value: &'static str,
    sequence: &'static str,
    /// The two field names the stub adds for the route.
    from_label: &'static str,
    to_label: &'static str,
    /// What stands under the code, and the notice at the foot of the card.
    caption: &'static str,
    notice: &'static str,
    /// The two lines at the foot of the stub.
    retain_first: &'static str,
    retain_second: &'static str,
}

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

/// The card in English.
const ENGLISH: Words = Words {
    title: "Boarding pass",
    heading: "BOARDING PASS",
    passenger: "PASSENGER",
    booking_ref: "BOOKING REF",
    status_label: "STATUS",
    status_value: "CHECKED IN",
    from_name: "Marseille Provence",
    to_name: "London Heathrow",
    flight: "FLIGHT",
    date: "DATE",
    boarding: "BOARDING",
    departs: "DEPARTS",
    gate: "GATE",
    seat: "SEAT",
    class_label: "CLASS",
    class_value: "ECONOMY",
    sequence: "SEQ",
    from_label: "FROM",
    to_label: "TO",
    caption: "IATA BCBP — scan at the gate",
    notice: "Boarding closes 15 minutes before departure. Passport and this pass \
             are asked for at the gate.",
    retain_first: "Please retain this stub",
    retain_second: "until the end of the journey.",
};

/// The card in French.
const FRENCH: Words = Words {
    title: "Carte d'embarquement",
    heading: "CARTE D'EMBARQUEMENT",
    passenger: "PASSAGER",
    booking_ref: "RÉSERVATION",
    status_label: "STATUT",
    status_value: "ENREGISTRÉ",
    from_name: "Marseille Provence",
    to_name: "Londres Heathrow",
    flight: "VOL",
    date: "DATE",
    boarding: "EMBARQUEMENT",
    departs: "DÉPART",
    gate: "PORTE",
    seat: "SIÈGE",
    class_label: "CLASSE",
    class_value: "ÉCONOMIE",
    sequence: "SÉQ",
    from_label: "DE",
    to_label: "À",
    caption: "IATA BCBP — à scanner à la porte",
    notice: "L'embarquement ferme 15 minutes avant le départ. Une pièce \
             d'identité et cette carte sont demandées à la porte.",
    retain_first: "Conservez ce talon",
    retain_second: "jusqu'à la fin du voyage.",
};

/// 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 side of one module, in points. Four pixels to a module at 288dpi, so
/// every module's edge lands on a pixel boundary.
const MODULE: f64 = 3.0;

/// The line the code carries: an IATA Resolution 792 boarding pass, mandatory
/// items only.
///
/// Every field is fixed-width and padded with spaces to its size, because a
/// reader takes each one by its offset and never looks for a separator: the
/// name takes 20, the booking reference 7, each airport 3, the carrier 3, the
/// flight number 5 — four digits and an operational suffix left blank — the
/// Julian day 3, the compartment 1, the seat 4, the check-in sequence 5 and the
/// passenger status 1. The two hex digits that close the line are the size of
/// the conditional items that follow, and `00` says none do.
fn boarding_pass_code() -> String {
    format!(
        "M1{PASSENGER:<20}E{PNR:<7}{FROM}{TO}{CARRIER:<3}{FLIGHT:<5}{JULIAN}\
         {COMPARTMENT}{SEAT}{SEQUENCE:<5}{STATUS}00"
    )
}

/// Draws a line of text, left-aligned, in a colour of its own.
fn text(content: &mut Content, font: &FontHandle, size: f64, x: f64, y: f64, color: Rgb, s: &str) {
    let _ = content.set_fill(color);
    content.begin_text();
    let _ = content.set_font(font.name(), size);
    let _ = content.text_origin(x, y);
    content.show_glyphs(&font.glyphs(s));
    content.end_text();
}

/// Draws a line of text whose right edge sits at `right`.
fn text_right(
    content: &mut Content,
    font: &FontHandle,
    size: f64,
    right: f64,
    y: f64,
    color: Rgb,
    s: &str,
) {
    text(
        content,
        font,
        size,
        right - font.measure(s, size),
        y,
        color,
        s,
    );
}

/// One labelled field: its name above in small grey capitals, its value on the
/// baseline `y`.
fn field(
    content: &mut Content,
    font: &FontHandle,
    x: f64,
    y: f64,
    label: &str,
    value: &str,
    size: f64,
) {
    text(content, font, 7.0, x, y + 14.0, MUTED, label);
    text(content, font, size, x, y, INK, value);
}

/// A horizontal rule from `x0` to `x1` at height `y`.
fn rule(
    content: &mut Content,
    x0: f64,
    x1: f64,
    y: f64,
    width: f64,
    color: Rgb,
) -> Result<(), hqf_pdf::Error> {
    content.set_stroke(color)?;
    content.set_line_width(width)?;
    content.move_to(x0, y)?;
    content.line_to(x1, y)?;
    content.stroke();
    Ok(())
}

/// Draws the head band: the operator's mark across a filled strip, and the word
/// the card is.
fn band(content: &mut Content, font: &FontHandle, words: &Words) -> Result<(), hqf_pdf::Error> {
    content.set_fill(ACCENT)?;
    content.rect(0.0, BAND_BOTTOM, PAGE_WIDTH, PAGE_HEIGHT - BAND_BOTTOM)?;
    content.fill();

    let white = Rgb::gray(1.0);
    let pale = Rgb::gray(0.85);
    text(content, font, 15.0, LEFT, 261.0, white, "HQF Development");
    text(
        content,
        font,
        7.0,
        LEFT,
        250.0,
        pale,
        "High Quality Foundations · www.hqf.fr",
    );
    text_right(content, font, 15.0, STUB_RIGHT, 258.0, white, words.heading);
    Ok(())
}

/// Draws the tear line: the stub's tinted ground and the dashes the passenger
/// tears along.
fn perforation(content: &mut Content) -> Result<(), hqf_pdf::Error> {
    content.set_fill(Rgb::gray(0.96))?;
    content.rect(PERFORATION, 0.0, PAGE_WIDTH - PERFORATION, BAND_BOTTOM)?;
    content.fill();

    content.set_stroke(Rgb::gray(0.6))?;
    content.set_line_width(0.6)?;
    for index in 0..28_u32 {
        let y = f64::from(index).mul_add(8.0, 8.0);
        content.move_to(PERFORATION, y)?;
        content.line_to(PERFORATION, y + 4.0)?;
    }
    content.stroke();
    Ok(())
}

/// Draws the part the passenger shows at the gate: who, where to, when, and the
/// scannable line.
fn main_portion(
    content: &mut Content,
    font: &FontHandle,
    words: &Words,
) -> Result<(), Box<dyn std::error::Error>> {
    field(content, font, LEFT, 210.0, words.passenger, PASSENGER, 13.0);
    field(content, font, 200.0, 210.0, words.booking_ref, PNR, 13.0);
    field(
        content,
        font,
        300.0,
        210.0,
        words.status_label,
        words.status_value,
        13.0,
    );
    rule(content, LEFT, MAIN_RIGHT, 198.0, 0.6, Rgb::gray(0.8))?;

    text(content, font, 30.0, LEFT, 166.0, ACCENT, FROM);
    text(content, font, 7.5, LEFT, 152.0, MUTED, words.from_name);
    text_right(content, font, 30.0, FIELDS_RIGHT, 166.0, ACCENT, TO);
    text_right(
        content,
        font,
        7.5,
        FIELDS_RIGHT,
        152.0,
        MUTED,
        words.to_name,
    );
    let arrow = "→";
    let arrow_x = 165.0 - font.measure(arrow, 18.0) / 2.0;
    text(content, font, 18.0, arrow_x, 166.0, ACCENT, arrow);
    rule(content, LEFT, FIELDS_RIGHT, 140.0, 0.6, Rgb::gray(0.8))?;

    let flight = format!("{CARRIER} {FLIGHT}");
    field(content, font, LEFT, 112.0, words.flight, &flight, 9.5);
    field(content, font, 92.0, 112.0, words.date, DATE, 9.5);
    field(content, font, 170.0, 112.0, words.boarding, BOARDING, 9.5);
    field(content, font, 232.0, 112.0, words.departs, DEPARTURE, 9.5);

    field(content, font, LEFT, 72.0, words.gate, GATE, 9.5);
    field(content, font, 92.0, 72.0, words.seat, SEAT, 9.5);
    field(
        content,
        font,
        170.0,
        72.0,
        words.class_label,
        words.class_value,
        9.5,
    );
    field(content, font, 232.0, 72.0, words.sequence, SEQUENCE, 9.5);

    // The code sits at the right of this part, drawn as a square from its
    // lower-left corner. Nothing is drawn within its quiet zone, which is the
    // caller's to leave: the fields stop at `FIELDS_RIGHT` and the tear line
    // stands off to the right of it.
    let code = QrCode::new(&boarding_pass_code())?;
    let side = f64::from(u32::try_from(code.size())?) * MODULE;
    let code_x = MAIN_RIGHT - side;
    let code_bottom = 46.0;
    content.set_fill(Rgb::gray(0.0))?;
    content.draw_qr(&code, code_x, code_bottom, side)?;
    let caption_x = code_x + (side - font.measure(words.caption, 6.5)) / 2.0;
    text(
        content,
        font,
        6.5,
        caption_x,
        code_bottom - 14.0,
        MUTED,
        words.caption,
    );

    text(content, font, 6.5, LEFT, 20.0, MUTED, words.notice);
    Ok(())
}

/// Draws the stub the passenger tears off and keeps: the same flight, said
/// again in the width of a thumb.
fn stub(content: &mut Content, font: &FontHandle, words: &Words) {
    let pair = STUB_LEFT + 64.0;
    field(
        content,
        font,
        STUB_LEFT,
        208.0,
        words.passenger,
        PASSENGER,
        9.0,
    );
    let flight = format!("{CARRIER} {FLIGHT}");
    field(content, font, STUB_LEFT, 174.0, words.flight, &flight, 9.0);
    field(content, font, pair, 174.0, words.date, DATE, 8.0);
    field(content, font, STUB_LEFT, 140.0, words.from_label, FROM, 9.0);
    field(content, font, pair, 140.0, words.to_label, TO, 9.0);
    field(content, font, STUB_LEFT, 106.0, words.gate, GATE, 9.0);
    field(content, font, pair, 106.0, words.seat, SEAT, 9.0);
    field(
        content,
        font,
        STUB_LEFT,
        72.0,
        words.class_label,
        words.class_value,
        9.0,
    );
    field(content, font, pair, 72.0, words.sequence, SEQUENCE, 9.0);

    text(
        content,
        font,
        6.5,
        STUB_LEFT,
        40.0,
        MUTED,
        words.retain_first,
    );
    text(
        content,
        font,
        6.5,
        STUB_LEFT,
        30.0,
        MUTED,
        words.retain_second,
    );
}

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 path = args
        .next()
        .unwrap_or_else(|| language.file_name(&out::default_path("boarding_pass")));
    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(
        Name::new("Title"),
        &format!("{} {CARRIER} {FLIGHT}", words.title),
    );

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

    let mut content = Content::new();
    band(&mut content, &font, words)?;
    perforation(&mut content)?;
    main_portion(&mut content, &font, words)?;
    stub(&mut content, &font, words);

    let mut page = Page::new(PAGE_WIDTH, PAGE_HEIGHT);
    page.content = content.into_bytes();
    doc.add_page(page)?;

    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, {CARRIER} {FLIGHT} {FROM}–{TO} seat {SEAT}",
        bytes.len()
    );
    Ok(())
}

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

    /// The lines two languages are allowed to write the same way, each with
    /// what makes the two the same word.
    const SPARED: [&str; 2] = [
        // A day is headed by the same word in French as in English.
        r#"date: "DATE""#,
        // An airport keeps the name of the place it stands in.
        r#"from_name: "Marseille Provence""#,
    ];

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

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