ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! The composition rules, row by row, and the four seats they fill.
//!
//! The ruling this type implements has four clauses and each has a section here: the lossless tail,
//! the composition rules (`_`, `Suppress-Script`, grandfathered), the filter face's shape, and the
//! four columns. The columns and the filter are next door — `storage/tests.rs` and
//! `comparison/tests.rs` — because they are what those modules are; what stays here is the value.

use core::str::FromStr;

use smol_bytes::Utf8Bytes;

use super::{LanguageId, ParseLanguageIdError};
use crate::primitives::lang::{
  Language, ParseLanguageError, ParseRegionError, Region, ScriptSubtag, registry,
};

/// One tag through the door, or the reason it was refused.
fn door(sent: &str) -> Result<LanguageId, ParseLanguageIdError> {
  LanguageId::new(sent)
}

/// One tag the door must take, unwrapped.
fn admitted(sent: &str) -> LanguageId {
  door(sent).unwrap_or_else(|refused| panic!("`{sent}` is a language tag: {refused}"))
}

/// The canonical rendering of one tag, which is what most rows below compare.
fn canonical(sent: &str) -> String {
  admitted(sent).to_string()
}

/// **THE COMPOSITION TABLE**, transcribed from the ruling.
#[test]
fn the_door_applies_every_composition_rule_the_ruling_names() {
  for (sent, held, why) in [
    // `_` is read as `-`, which is what a filename-safe tag uses.
    ("zh_Hans_CN", "zh-Hans-CN", "underscores"),
    ("en_US", "en-US", "underscores"),
    // The SUPPRESSION: a declared script the language already implies carries nothing.
    ("en-Latn", "en", "`en` implies `Latn`"),
    ("en-Latn-US", "en-US", "and the region survives it"),
    ("fr-latn", "fr", "any case"),
    ("he-Hebr", "he", "not only Latin"),
    // …and a language that implies NO script keeps the one it was given.
    ("zh-Hans", "zh-Hans", "`zh` implies nothing"),
    ("zh-Hant", "zh-Hant", "and the two stay apart"),
    ("zh-Hant-TW", "zh-Hant-TW", "with a region beside it"),
    // GRANDFATHERED tags fold by their `Preferred-Value`, before the tag is taken apart.
    ("i-klingon", "tlh", "grandfathered"),
    ("I-KLINGON", "tlh", "grandfathered, any case"),
    ("zh-guoyu", "cmn", "grandfathered"),
    ("art-lojban", "jbo", "grandfathered"),
    ("no-bok", "nb", "grandfathered"),
    (
      "en-GB-oed",
      "en-GB-oxendict",
      "a multi-subtag preferred value",
    ),
    // Each SEAT's own door, applied where it sits.
    // Three folds in one tag: `ger` is an mkv's German, `latn` is the script German already
    // implies, and the trailing `de` is the REGION Germany — which is why the answer keeps a seat
    // the first two lost.
    (
      "GER-latn-de",
      "de-DE",
      "alpha-3, suppression and region case, at once",
    ),
    ("deu-DE", "de-DE", "an mp4's language subtag"),
    ("iw-IL", "he-IL", "a deprecated language"),
    ("de-BU", "de-MM", "a deprecated region"),
    ("EN-us", "en-US", "case on two seats"),
  ] {
    assert_eq!(canonical(sent), held, "`{sent}` — {why}");
  }
}

/// **THE SEATS ARE POSITIONAL**, and each is filled only by a subtag of its own shape.
#[test]
fn each_seat_is_filled_by_the_shape_that_belongs_in_it() {
  let full = admitted("sr-Cyrl-RS");
  assert_eq!(full.language().as_str(), "sr");
  assert_eq!(full.script().map(ScriptSubtag::as_str), Some("Cyrl"));
  assert_eq!(full.region().map(Region::as_str), Some("RS"));
  assert_eq!(full.rest(), None);

  let bare = admitted("de");
  assert_eq!(bare.language().as_str(), "de");
  assert_eq!(bare.script(), None);
  assert_eq!(bare.region(), None);

  // A script is FOUR letters and a region is two letters or three DIGITS, so a two-letter subtag
  // after the language is a region even though a script slot is still open.
  let regional = admitted("de-AT");
  assert_eq!(regional.script(), None);
  assert_eq!(regional.region().map(Region::as_str), Some("AT"));

  // …and an M.49 area code reaches the same seat.
  let area = admitted("es-419");
  assert_eq!(area.region().map(Region::as_str), Some("419"));
  assert!(area.region().expect("a region").is_area());
}

/// **THE TAIL IS LOSSLESS AND VERBATIM** — the ruling's first clause.
///
/// Variants, extensions and the private-use sequence are held exactly as they arrived, rendered
/// back exactly, and counted in equality.
#[test]
fn the_tail_is_held_verbatim_and_rendered_back() {
  for tag in [
    "en-US-posix",
    "de-u-co-phonebk",
    "en-x-lorem",
    "sl-rozaj-biske",
    "en-US-x-Foo",
    "hy-Latn-IT-arevela",
  ] {
    assert_eq!(canonical(tag), tag, "`{tag}` did not round-trip");
  }

  let held = admitted("en-US-x-Foo");
  assert_eq!(held.language().as_str(), "en");
  assert_eq!(held.region().map(Region::as_str), Some("US"));
  assert_eq!(held.rest().map(Utf8Bytes::as_str), Some("x-Foo"));
}

/// **THE TAIL'S CASE IS PART OF IT**, which is the price of the seat being lossless.
///
/// RFC 5646's own canonical form lower-cases a variant and an extension; this seat does not, because
/// a private-use sequence's meaning belongs to the private party that wrote it and this type cannot
/// know its case is insignificant. Two spellings of one tail are two values, and the rest of the tag
/// is unaffected.
#[test]
fn two_spellings_of_one_tail_are_two_values() {
  let upper = admitted("en-US-x-Foo");
  let lower = admitted("en-US-x-foo");

  assert_ne!(upper, lower);
  assert_eq!(upper.language(), lower.language());
  assert_eq!(upper.region(), lower.region());

  // The seats BEFORE the tail are folded, so the difference is the tail's alone.
  assert_eq!(admitted("EN-us-x-Foo"), upper);
}

/// **AN EXTLANG HAS NO SEAT, so it rides the tail — and takes the rest of the tag with it.**
///
/// The consequence the type docs state rather than leave to be discovered: the tail is a TAIL, so
/// once a subtag falls into it every later one does too. The tag round-trips exactly and the
/// language is still filterable, which is the question the ruling names; filtering the script of
/// such a tag is what is lost.
#[test]
fn an_extlang_rides_the_tail_and_takes_the_later_seats_with_it() {
  let cantonese = admitted("zh-yue");
  assert_eq!(cantonese.language().as_str(), "zh");
  assert_eq!(cantonese.rest().map(Utf8Bytes::as_str), Some("yue"));
  assert_eq!(cantonese.to_string(), "zh-yue");

  let swallowed = admitted("zh-yue-Hant-HK");
  assert_eq!(swallowed.language().as_str(), "zh");
  assert_eq!(swallowed.script(), None, "the script is IN the tail");
  assert_eq!(swallowed.region(), None, "and so is the region");
  assert_eq!(swallowed.rest().map(Utf8Bytes::as_str), Some("yue-Hant-HK"));
  assert_eq!(swallowed.to_string(), "zh-yue-Hant-HK", "lossless anyway");

  // The well-formed spelling of the same content has both seats filled and both filterable.
  let plain = admitted("zh-Hant-HK");
  assert_eq!(plain.script().map(ScriptSubtag::as_str), Some("Hant"));
  assert_eq!(plain.region().map(Region::as_str), Some("HK"));
}

/// **THE TAIL'S ENVELOPE IS DELIBERATELY LOOSE** — one to eight ASCII alphanumeric characters per
/// subtag, which is the outer shape of every variant, extension and private-use subtag together.
///
/// `en-USA` is admitted though `USA` is not a legal variant, for the reason an unregistered language
/// subtag is: a container writes what its muxer believed.
#[test]
fn the_tail_admits_what_is_alphanumeric_and_refuses_what_is_not() {
  assert_eq!(
    canonical("en-USA"),
    "en-USA",
    "not a legal variant, and carried"
  );
  assert_eq!(canonical("de-1901"), "de-1901");
  assert_eq!(canonical("en-a-bbb-x-a-ccc"), "en-a-bbb-x-a-ccc");

  assert_eq!(door("en-US-!!"), Err(ParseLanguageIdError::Tail('!')));
  assert_eq!(door("en-US-po six"), Err(ParseLanguageIdError::Tail(' ')));
  assert_eq!(
    door("en-US-abcdefghi"),
    Err(ParseLanguageIdError::TailWidth)
  );
  assert!(door("en-US-abcdefgh").is_ok(), "eight is the ceiling");
}

/// **THE FIVE GRANDFATHERED TAGS WITH NO REPLACEMENT** fall through to the ordinary parse, and two
/// of them turn out to be ordinary compositions.
///
/// The honest handling of a table row that names nothing to fold onto: `cel-gaulish` is a registered
/// collection language with a variant-shaped tail, `zh-min` is Chinese with a tail, and the three
/// beginning `i-` are refused because a one-letter primary subtag is outside the grammar — which is
/// a sentence the language door can state.
#[test]
fn a_grandfathered_tag_with_no_replacement_falls_through_to_the_ordinary_parse() {
  assert_eq!(canonical("cel-gaulish"), "cel-gaulish");
  assert_eq!(admitted("cel-gaulish").language().as_str(), "cel");
  assert_eq!(
    admitted("cel-gaulish").rest().map(Utf8Bytes::as_str),
    Some("gaulish")
  );

  assert_eq!(canonical("zh-min"), "zh-min");
  assert_eq!(
    admitted("zh-min").rest().map(Utf8Bytes::as_str),
    Some("min")
  );

  for refused in ["i-default", "i-mingo", "i-enochian"] {
    assert_eq!(
      door(refused),
      Err(ParseLanguageIdError::Language(ParseLanguageError::TooShort)),
      "`{refused}`"
    );
  }
}

/// **THE GRANDFATHERED LOOKUP'S STACK BUFFER FITS EVERY TAG THE TABLE HOLDS.**
///
/// The lookup lower-cases into a fixed buffer and skips a tag too wide for it, which is what keeps
/// the fold from allocating for every ordinary tag that comes through the door. That shortcut is
/// only sound while no grandfathered tag is wider than the buffer, and this is what says so — a
/// registry that added one would fail here rather than silently stop folding it.
#[test]
fn the_grandfathered_table_fits_the_lookup_buffer() {
  let widest = registry::table::GRANDFATHERED
    .iter()
    .map(|(tag, _)| tag.len())
    .chain(
      registry::table::GRANDFATHERED_KEPT
        .iter()
        .map(|tag| tag.len()),
    )
    .max()
    .expect("twenty-six of them");

  assert!(
    widest <= super::GRANDFATHERED_MAX,
    "the widest grandfathered tag is {widest} bytes and the buffer is {}",
    super::GRANDFATHERED_MAX
  );
}

/// **A STRUCTURAL VIOLATION IS REFUSED, and the refusal carries the SEAT's own words.**
#[test]
fn a_refusal_names_the_seat_and_carries_its_error() {
  assert_eq!(door(""), Err(ParseLanguageIdError::Empty));
  assert_eq!(door("en-"), Err(ParseLanguageIdError::EmptySubtag));
  assert_eq!(door("en--US"), Err(ParseLanguageIdError::EmptySubtag));
  assert_eq!(door("-en"), Err(ParseLanguageIdError::EmptySubtag));

  assert_eq!(
    door("e-US"),
    Err(ParseLanguageIdError::Language(ParseLanguageError::TooShort))
  );
  assert_eq!(
    door("日本語-JP"),
    Err(ParseLanguageIdError::Language(
      ParseLanguageError::NotAlphabetic('日')
    ))
  );

  // A subtag in the region POSITION that is not region-SHAPED is never handed to the region door
  // at all — it falls to the tail, where the looser envelope admits it. So the shape test and the
  // seat's own grammar cannot disagree about one subtag, and a tag like `zh-Hans-XYZ` is carried
  // rather than refused.
  assert_eq!(canonical("zh-Hans-XYZ"), "zh-Hans-XYZ", "the tail took it");
  assert_eq!(
    canonical("de-1a1"),
    "de-1a1",
    "neither two letters nor three digits"
  );
  assert_eq!(
    admitted("de-1a1").rest().map(Utf8Bytes::as_str),
    Some("1a1")
  );
  assert_eq!(admitted("de-1a1").region(), None);
}

/// **EQUALITY IS THE FOUR SEATS**, so two spellings of one identity are one value.
#[test]
fn two_spellings_of_one_identity_are_one_value() {
  let mkv = admitted("GER-latn-de");
  let mp4 = admitted("deu-Latn-DE");
  let bcp47 = admitted("de-DE");

  assert_eq!(mkv, mp4);
  assert_eq!(mp4, bcp47);

  let mut distinct = std::collections::HashSet::new();
  distinct.insert(mkv);
  distinct.insert(mp4);
  distinct.insert(bcp47);
  assert_eq!(distinct.len(), 1, "one identity, one hash bucket");

  // …and a tag with one fewer seat filled is a DIFFERENT identity, which is the other half of the
  // same claim: the fold makes spellings meet, it does not make tags equal.
  assert_ne!(admitted("de"), admitted("de-DE"));
}

/// The rendering and the parse are inverse over canonical text, which is what makes the tag usable
/// as a cursor and as the field a client reads back into an operand.
#[test]
fn the_rendering_and_the_parse_are_inverse() {
  for sent in [
    "de",
    "zh-Hans",
    "en-US",
    "sr-Cyrl-RS",
    "en-US-x-Foo",
    "GER-latn-de",
    "i-klingon",
    "zh_Hans_CN",
  ] {
    let held = admitted(sent);
    let rendered = held.to_string();

    assert_eq!(LanguageId::from_str(&rendered).expect("canonical"), held);
    assert_eq!(admitted(&rendered), held, "the door is idempotent");
  }

  assert_eq!(
    format!("{:?}", admitted("GER-latn-de")),
    r#"LanguageId("de-DE")"#
  );
}

/// **`compose` and the door agree**, which is what keeps a caller building an identity from getting
/// a value the parser could not have produced.
///
/// The suppression fires on both routes: a `LanguageId` built from `en` and `Latn` is `en`.
#[test]
fn building_an_identity_by_parts_applies_the_same_rules() {
  let english = Language::new("en").expect("a language");
  let latin = ScriptSubtag::new("Latn").expect("a script");

  let composed = LanguageId::compose(english.clone(), Some(latin), None, None);
  assert_eq!(composed, admitted("en"));
  assert_eq!(composed.script(), None, "the suppression fired");

  let chinese = Language::new("zh").expect("a language");
  let simplified = ScriptSubtag::new("Hans").expect("a script");
  let composed = LanguageId::compose(chinese, Some(simplified), None, None);
  assert_eq!(composed, admitted("zh-Hans"));

  // A bare language composes to a tag with three empty seats, which is what `From` gives.
  assert_eq!(LanguageId::from(english), admitted("en"));
}

/// **A REGION THE DOOR REFUSES IS THE REGION SEAT'S ERROR**, carried whole.
///
/// The one place a seat past the language can refuse: a two-letter subtag reaches the region door,
/// and there is a shape it turns down — none, as it happens, since two ASCII letters is exactly what
/// that door takes. So this asserts the ROUTE rather than a refusal, by showing that the error type
/// can carry one.
#[test]
fn the_region_seats_error_has_a_route_to_the_surface() {
  let refused = ParseLanguageIdError::Region(ParseRegionError::Mixed);
  assert!(refused.to_string().contains("region subtag"));
  assert!(core::error::Error::source(&refused).is_some());

  let language = ParseLanguageIdError::Language(ParseLanguageError::Empty);
  assert!(core::error::Error::source(&language).is_some());
  assert!(core::error::Error::source(&ParseLanguageIdError::Empty).is_none());
}

/// Ordering is the four seats in order, which is total, stable, and a usable cursor key.
#[test]
fn ordering_walks_the_seats_in_order() {
  let mut sorted = [
    admitted("de-DE"),
    admitted("de"),
    admitted("de-AT"),
    admitted("zh-Hans"),
    admitted("zh"),
  ];
  sorted.sort();

  let tags: Vec<String> = sorted.iter().map(LanguageId::to_string).collect();
  assert_eq!(tags, ["de", "de-AT", "de-DE", "zh", "zh-Hans"]);
}