gedcomkit 0.1.6

//! What GEDCOM's standard tags mean, in words.
//!
//! This is a vocabulary, not a schema. Nothing here decides what may be
//! stored — a tag missing from every table below is read, kept, written back,
//! and displayed exactly like one that is present. What it decides is how
//! well a structure can be *shown*: whether it gets a purpose-built row, a
//! labelled generic row, or the raw tag it was written with.
//!
//! Covers GEDCOM 5.5.1 and 7.0. Where the two disagree, both spellings are
//! listed, because a file of either version has to render. Extension tags are
//! deliberately absent: an application that writes its own extensions labels
//! them itself, falling back to these tables for everything standard.

/// How a structure should be presented.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum TagKind {
    /// A level-zero record: `INDI`, `FAM`, `SOUR`, and the rest.
    Record,
    /// Something that happened at a time and place: `BIRT`, `CENS`, `MARR`.
    Event,
    /// A standing fact rather than an occurrence: `OCCU`, `RESI`, `NATI`.
    Attribute,
    /// An ordinary substructure: `DATE`, `PLAC`, `PAGE`.
    Structure,
    /// A tag these tables have no entry for, including every `_` extension.
    Unknown,
}

/// What the tag means, in the words the interface should use.
///
/// Returns `None` for a tag with no entry, which the caller must render with
/// the tag itself rather than inventing a label for it.
#[must_use]
#[allow(
    clippy::too_many_lines,
    reason = "one arm per tag reads better than a split table"
)]
pub fn label(tag: &str) -> Option<&'static str> {
    Some(match tag {
        // Records
        "HEAD" => "Header",
        "INDI" => "Individual",
        "FAM" => "Family",
        "SOUR" => "Source",
        "REPO" => "Repository",
        "OBJE" => "Media object",
        "NOTE" => "Note",
        "SNOTE" => "Shared note",
        "SUBM" => "Submitter",
        "SUBN" => "Submission",
        "TRLR" => "End of file",

        // Individual events
        "BIRT" => "Birth",
        "CHR" => "Christening",
        "DEAT" => "Death",
        "BURI" => "Burial",
        "CREM" => "Cremation",
        "ADOP" => "Adoption",
        "BAPM" => "Baptism",
        "BARM" => "Bar mitzvah",
        "BASM" => "Bat mitzvah",
        "BLES" => "Blessing",
        "CHRA" => "Adult christening",
        "CONF" => "Confirmation",
        "FCOM" => "First communion",
        "ORDN" => "Ordination",
        "NATU" => "Naturalization",
        "EMIG" => "Emigration",
        "IMMI" => "Immigration",
        "CENS" => "Census",
        "PROB" => "Probate",
        "WILL" => "Will",
        "GRAD" => "Graduation",
        "RETI" => "Retirement",
        "EVEN" => "Event",

        // Individual attributes
        "CAST" => "Caste",
        "DSCR" => "Physical description",
        "EDUC" => "Education",
        "IDNO" => "Identifying number",
        "NATI" => "Nationality",
        "NCHI" => "Number of children",
        "NMR" => "Number of marriages",
        "OCCU" => "Occupation",
        "PROP" => "Property",
        "RELI" => "Religion",
        "RESI" => "Residence",
        "SSN" => "Social security number",
        "TITL" => "Title",
        "FACT" => "Fact",

        // Family events
        "MARR" => "Marriage",
        "DIV" => "Divorce",
        "DIVF" => "Divorce filed",
        "ANUL" => "Annulment",
        "ENGA" => "Engagement",
        "MARB" => "Marriage banns",
        "MARC" => "Marriage contract",
        "MARL" => "Marriage licence",
        "MARS" => "Marriage settlement",

        // LDS ordinances, defined by both versions and present in real
        // FamilySearch-derived exports.
        "BAPL" => "Baptism (LDS)",
        "CONL" => "Confirmation (LDS)",
        "ENDL" => "Endowment (LDS)",
        "SLGC" => "Sealing to parents (LDS)",
        "SLGS" => "Sealing to spouse (LDS)",

        // Structures
        "ABBR" => "Abbreviation",
        "ADDR" => "Address",
        "ADR1" => "Address line 1",
        "ADR2" => "Address line 2",
        "ADR3" => "Address line 3",
        "AGE" => "Age",
        "AGNC" => "Agency",
        "ALIA" => "Also recorded as",
        "ANCI" => "Ancestor interest",
        "ASSO" => "Association",
        "AUTH" => "Author",
        "CALN" => "Call number",
        "CAUS" => "Cause",
        "CHAR" => "Character set",
        "CHAN" => "Last changed",
        "CHIL" => "Child",
        "CITY" => "City",
        "CONC" => "Continued",
        "CONT" => "Continued on a new line",
        "COPR" => "Copyright",
        "CORP" => "Corporation",
        "CREA" => "Created",
        "CROP" => "Crop",
        "CTRY" => "Country",
        "DATA" => "Data",
        "DATE" => "Date",
        "DESI" => "Descendant interest",
        "DEST" => "Destination",
        "EMAIL" => "Email",
        "EXID" => "External identifier",
        "FAMC" => "Child in family",
        "FAMS" => "Spouse in family",
        "FAX" => "Fax",
        "FILE" => "File",
        "FONE" => "Phonetic form",
        "FORM" => "Format",
        "GEDC" => "GEDCOM version",
        "GIVN" => "Given name",
        "HEIG" | "HEIGHT" => "Height",
        "HUSB" => "Husband",
        "INIL" => "Initiatory",
        "LANG" => "Language",
        "LATI" => "Latitude",
        "LEFT" => "Crop from the left",
        "LONG" => "Longitude",
        "MAP" => "Coordinates",
        "MEDI" => "Medium",
        "MIME" => "Media type",
        "NAME" => "Name",
        "NO" => "Did not happen",
        "NICK" => "Nickname",
        "NPFX" => "Name prefix",
        "NSFX" => "Name suffix",
        "PAGE" => "Where in the source",
        "PEDI" => "Pedigree",
        "PHON" => "Telephone",
        "PHRASE" => "As written",
        "PLAC" => "Place",
        "POST" => "Postal code",
        "PUBL" => "Publication",
        "QUAY" => "Certainty",
        "REFN" => "Reference number",
        "RELA" => "Relationship",
        "RESN" => "Restriction",
        "RIN" => "Record identifier",
        "ROLE" => "Role",
        "ROMN" => "Romanized form",
        "SCHMA" => "Extension declarations",
        "SDATE" => "Sort date",
        "SEX" => "Sex",
        "SPFX" => "Surname prefix",
        "STAE" => "State",
        "STAT" => "Status",
        "SURN" => "Surname",
        "TAG" => "Extension tag",
        "TEMP" => "Temple",
        "TEXT" => "Text from the source",
        "TIME" => "Time",
        "TOP" => "Crop from the top",
        "TRAN" => "Translation",
        "TYPE" => "Type",
        "VERS" => "Version",
        "WIDTH" => "Width",
        "WIFE" => "Wife",
        "WWW" => "Web address",
        // `_UID` is not standard in 5.5.1 but every producer writes it, and a
        // reader should not have to decode a tag to know what the line holds.
        "UID" | "_UID" => "Unique identifier",

        _ => return None,
    })
}

/// The label to show, falling back to the tag itself.
#[must_use]
pub fn display_label(tag: &str) -> &str {
    label(tag).unwrap_or(tag)
}

/// What a vendor's extension tag means, for the ones real files carry.
///
/// Kept apart from [`label`] on purpose: these are extensions and stay badged
/// as extensions — [`is_extension`] and [`kind`] answer for them exactly as
/// for a tag nobody understands. The list is grounded in a fourteen-producer
/// fixture corpus, not imagined; `_FREL`/`_MREL` appear twenty-four thousand
/// times in the Family Tree Maker exports alone. A label only saves a reader
/// from decoding a tag to know what a line holds. A tag not listed returns
/// `None` and keeps its raw spelling, which is honest for a construct nobody
/// here understands.
#[must_use]
pub const fn vendor_label(tag: &str) -> Option<&'static str> {
    Some(match tag.as_bytes() {
        b"_UID" => "Unique identifier",
        b"_FSFTID" => "FamilySearch identifier",
        b"_APID" => "Ancestry record identifier",
        b"_FREL" => "Relationship to father",
        b"_MREL" => "Relationship to mother",
        b"_MARNM" => "Married name",
        b"_AKA" => "Also known as",
        b"_PRIM" | b"_PHOTO" => "Preferred picture",
        b"_MILT" => "Military service",
        b"_MDCL" => "Medical",
        b"_SEPR" => "Separation",
        b"_HTITL" => "Husband's title",
        b"_WTITL" => "Wife's title",
        b"_UPD" => "Last updated",
        b"_LINK" | b"_WEBTAG" => "Web link",
        b"_URL" | b"_WWW" => "Web address",
        b"_FOOT" => "Footnote",
        b"_TODO" => "To do",
        _ => return None,
    })
}

/// The letter a record type's identifiers conventionally start with.
///
/// `@I12@`, `@F3@`, `@S7@`: every producer uses these, a file is easier to
/// read by hand for it, and [`crate::Document::next_xref`] takes the result
/// directly. `X` for a record type with no convention.
#[must_use]
pub const fn xref_prefix(tag: &str) -> &'static str {
    match tag.as_bytes() {
        b"INDI" => "I",
        b"FAM" => "F",
        b"SOUR" => "S",
        b"NOTE" | b"SNOTE" => "N",
        b"OBJE" => "M",
        b"REPO" => "R",
        b"SUBM" => "U",
        _ => "X",
    }
}

/// How a tag should be presented, given the level it appears at.
///
/// Level matters because GEDCOM reuses tags: `SOUR` at level zero is a source
/// record, and below that it is a citation pointing at one.
#[must_use]
pub fn kind(tag: &str, level: u16) -> TagKind {
    if level == 0 {
        return if is_record(tag) {
            TagKind::Record
        } else {
            TagKind::Unknown
        };
    }
    if is_event(tag) {
        return TagKind::Event;
    }
    if is_attribute(tag) {
        return TagKind::Attribute;
    }
    if label(tag).is_some() {
        TagKind::Structure
    } else {
        TagKind::Unknown
    }
}

/// Whether the tag names a record type the standard defines.
#[must_use]
pub const fn is_record(tag: &str) -> bool {
    matches!(
        tag.as_bytes(),
        b"HEAD"
            | b"INDI"
            | b"FAM"
            | b"SOUR"
            | b"REPO"
            | b"OBJE"
            | b"NOTE"
            | b"SNOTE"
            | b"SUBM"
            | b"SUBN"
            | b"TRLR"
    )
}

/// Whether the tag names something that happened, which is what earns a place
/// on the timeline.
#[must_use]
pub const fn is_event(tag: &str) -> bool {
    matches!(
        tag.as_bytes(),
        b"BIRT"
            | b"CHR"
            | b"DEAT"
            | b"BURI"
            | b"CREM"
            | b"ADOP"
            | b"BAPM"
            | b"BARM"
            | b"BASM"
            | b"BLES"
            | b"CHRA"
            | b"CONF"
            | b"FCOM"
            | b"ORDN"
            | b"NATU"
            | b"EMIG"
            | b"IMMI"
            | b"CENS"
            | b"PROB"
            | b"WILL"
            | b"GRAD"
            | b"RETI"
            | b"EVEN"
            | b"MARR"
            | b"DIV"
            | b"DIVF"
            | b"ANUL"
            | b"ENGA"
            | b"MARB"
            | b"MARC"
            | b"MARL"
            | b"MARS"
    )
}

/// Whether the tag names a standing fact rather than an occurrence. An
/// attribute can still carry a date, and several routinely do.
#[must_use]
pub const fn is_attribute(tag: &str) -> bool {
    matches!(
        tag.as_bytes(),
        b"CAST"
            | b"DSCR"
            | b"EDUC"
            | b"IDNO"
            | b"NATI"
            | b"NCHI"
            | b"NMR"
            | b"OCCU"
            | b"PROP"
            | b"RELI"
            | b"RESI"
            | b"SSN"
            | b"TITL"
            | b"FACT"
    )
}

/// Whether the tag is an extension: someone's addition to the standard. These
/// are preserved untouched and shown under the tag as written.
#[must_use]
pub fn is_extension(tag: &str) -> bool {
    tag.starts_with('_')
}

/// The `SEX` payload in words.
#[must_use]
pub fn sex_label(value: &str) -> &str {
    match value.trim() {
        "M" => "Male",
        "F" => "Female",
        "X" => "Neither male nor female",
        "U" => "Unknown",
        other => other,
    }
}

/// The `PEDI` payload in words. A file may carry a value from either version
/// or a vendor's own, so an unrecognized one is returned unchanged.
#[must_use]
pub fn pedigree_label(value: &str) -> &str {
    match value.trim() {
        "birth" | "Birth" | "BIRTH" => "Birth",
        "adopted" | "Adopted" | "ADOPTED" => "Adopted",
        "foster" | "Foster" | "FOSTER" => "Foster",
        "sealing" | "Sealing" | "SEALING" => "Sealing",
        "step" | "Step" | "STEP" => "Step",
        "other" | "Other" | "OTHER" => "Other",
        other => other,
    }
}

/// The `QUAY` payload in words. GEDCOM defines 0 through 3.
#[must_use]
pub fn certainty_label(value: &str) -> &str {
    match value.trim() {
        "0" => "Unreliable",
        "1" => "Questionable",
        "2" => "Secondary evidence",
        "3" => "Direct primary evidence",
        other => other,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_tag_with_no_entry_renders_as_itself() {
        assert_eq!(label("_FSFTID"), None);
        assert_eq!(display_label("_FSFTID"), "_FSFTID");
        assert_eq!(kind("_FSFTID", 1), TagKind::Unknown);
        assert!(is_extension("_FSFTID"));
    }

    #[test]
    fn the_same_tag_reads_differently_by_level() {
        assert_eq!(kind("SOUR", 0), TagKind::Record);
        assert_eq!(kind("SOUR", 1), TagKind::Structure);
    }

    #[test]
    fn events_and_attributes_are_told_apart() {
        assert_eq!(kind("BIRT", 1), TagKind::Event);
        assert_eq!(kind("RESI", 1), TagKind::Attribute);
        assert_eq!(kind("DATE", 2), TagKind::Structure);
    }

    #[test]
    fn every_tag_the_requirement_corpus_uses_has_a_label() {
        // A representative compatibility document. `_FSFTID` is deliberately
        // absent: it is an extension and renders as its own tag.
        for tag in [
            "HEAD", "SOUR", "NAME", "GEDC", "VERS", "FORM", "CHAR", "NOTE", "INDI", "SEX", "BIRT",
            "DATE", "PLAC", "CHR", "DEAT", "BURI", "RESI", "IMMI", "NATU", "OCCU", "EVEN", "TYPE",
            "FAMC", "FAMS", "REFN", "OBJE", "FAM", "HUSB", "WIFE", "CHIL", "TITL", "PUBL", "FILE",
            "TRLR",
        ] {
            assert!(label(tag).is_some(), "{tag} has no label");
        }
    }

    #[test]
    fn enumerations_read_as_words_and_keep_what_they_do_not_know() {
        assert_eq!(sex_label("F"), "Female");
        assert_eq!(sex_label("Q"), "Q");
        assert_eq!(pedigree_label("adopted"), "Adopted");
        assert_eq!(certainty_label("3"), "Direct primary evidence");
        assert_eq!(certainty_label("9"), "9");
    }
}