gedcomkit 0.1.11

//! Readings of a record, for an interface to show.
//!
//! Every type here is a *projection*: computed on demand from structures that
//! remain the truth, never a parallel model that could disagree with them.
//! Two consequences worth stating, because they are the point of the design:
//!
//! - A projection that cannot express something loses nothing, because the
//!   structure is still in the document and still appears in [`RecordView`].
//! - Nothing is filtered out for being unrecognized. Everything in the file
//!   deserves to reach the screen, so [`RecordView::structures`] holds every
//!   structure, in file order, labelled as well as it can be.
//!
//! With the `serde` feature these types serialize, for callers that send them
//! to a webview or over a wire; with `ts`, they also carry TypeScript
//! definitions of that JSON (`ts_rs::TS`).

use crate::dates::GedcomDate;
use crate::names::PersonalName;
use crate::{Node, tags};

/// One structure, ready to render, with everything beneath it.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
#[non_exhaustive]
pub struct StructureView {
    /// Where this structure sits in its record: the child index at each level.
    /// It is how an edit says which structure it means.
    pub path: Vec<usize>,
    /// How deep it is, counting the record itself as zero.
    pub level: u16,
    /// The tag exactly as the file wrote it.
    pub tag: String,
    /// The tag in the interface's words, or the tag itself when there is no
    /// entry for it.
    pub label: String,
    /// How well these tables understand this structure: `record`, `event`,
    /// `attribute`, `structure`, or `unknown`.
    #[cfg_attr(
        feature = "ts",
        ts(type = r#""record" | "event" | "attribute" | "structure" | "unknown""#)
    )]
    pub kind: &'static str,
    /// The payload with its continuations folded in, for display.
    pub value: String,
    /// The payload read as a pointer, when it is one.
    pub pointer: Option<String>,
    /// Whether the tag is an extension — someone's addition to the standard.
    pub extension: bool,
    /// Substructures, `CONT`/`CONC` excluded because they are the payload.
    pub children: Vec<Self>,
}

impl StructureView {
    /// Reads a structure and everything under it.
    #[must_use]
    pub fn from_node(node: &Node, level: u16, path: Vec<usize>) -> Self {
        let children = node
            .children
            .iter()
            .enumerate()
            .filter(|(_, child)| !matches!(child.tag.as_str(), "CONT" | "CONC"))
            .map(|(index, child)| {
                let mut child_path = path.clone();
                child_path.push(index);
                Self::from_node(child, level + 1, child_path)
            })
            .collect();

        Self {
            path,
            level,
            tag: node.tag.clone(),
            label: tags::display_label(&node.tag).to_owned(),
            kind: kind_name(tags::kind(&node.tag, level)),
            value: node.logical_value(),
            pointer: node.pointer().map(str::to_owned),
            extension: tags::is_extension(&node.tag),
            children,
        }
    }
}

const fn kind_name(kind: tags::TagKind) -> &'static str {
    match kind {
        tags::TagKind::Record => "record",
        tags::TagKind::Event => "event",
        tags::TagKind::Attribute => "attribute",
        tags::TagKind::Structure => "structure",
        tags::TagKind::Unknown => "unknown",
    }
}

/// A whole record, as the record view shows it.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
#[non_exhaustive]
pub struct RecordView {
    /// The record's cross-reference identifier.
    pub xref: Option<String>,
    /// Its tag: `INDI`, `FAM`, or anything else the file used.
    pub tag: String,
    /// The tag in words.
    pub label: String,
    /// A one-line heading: a person's name, a source's title, or the tag.
    pub title: String,
    /// Every structure in the record, in file order. Nothing is omitted.
    pub structures: Vec<StructureView>,
    /// The record's exact GEDCOM lines, which is the guarantee that anything
    /// in the file can be seen.
    pub raw: String,
}

impl RecordView {
    /// Reads a record.
    #[must_use]
    pub fn from_node(record: &Node) -> Self {
        let structures = record
            .children
            .iter()
            .enumerate()
            .filter(|(_, child)| !matches!(child.tag.as_str(), "CONT" | "CONC"))
            .map(|(index, child)| StructureView::from_node(child, 1, vec![index]))
            .collect();

        Self {
            xref: record.xref.clone(),
            tag: record.tag.clone(),
            label: tags::display_label(&record.tag).to_owned(),
            title: record_title(record),
            structures,
            raw: raw_lines(record),
        }
    }
}

/// The record as GEDCOM, exactly as it will be written.
#[must_use]
pub fn raw_lines(record: &Node) -> String {
    let mut document = crate::Document {
        records: vec![record.clone()],
    };
    let text = document.to_text();
    document.records.clear();
    text
}

/// A one-line heading for a record of any type.
#[must_use]
pub fn record_title(record: &Node) -> String {
    let candidate = match record.tag.as_str() {
        "INDI" => record
            .first("NAME")
            .map(|node| PersonalName::from_node(node).display()),
        "FAM" => None,
        "SOUR" => record.value_of("TITL").or_else(|| record.value_of("ABBR")),
        "REPO" | "SUBM" => record.value_of("NAME"),
        "OBJE" => record
            .first("FILE")
            .and_then(|file| file.value_of("TITL"))
            .or_else(|| record.value_of("FILE")),
        // Everything else, understood or not, is headed by its own
        // payload — which is the only honest heading for a record type
        // nobody has seen before.
        _ => Some(record.logical_value()),
    };

    let title = candidate
        .map(|text| text.trim().replace('\n', " "))
        .filter(|text| !text.is_empty())
        .unwrap_or_else(|| tags::display_label(&record.tag).to_owned());

    truncate_heading(title)
}

/// Caps a heading at one line's worth of characters. A note record can be
/// pages long; a heading is 90 characters of it with an ellipsis.
#[must_use]
pub fn truncate_heading(title: String) -> String {
    if title.chars().count() > 90 {
        let short: String = title.chars().take(87).collect();
        format!("{short}…")
    } else {
        title
    }
}

/// An event or attribute, read for a timeline or a summary line.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
#[non_exhaustive]
pub struct EventView {
    /// The tag: `BIRT`, `RESI`, `EVEN`.
    pub tag: String,
    /// The tag in words, or the `TYPE` payload when the tag is the generic
    /// `EVEN` or `FACT` and the file said what it actually was.
    pub label: String,
    /// The `DATE` payload exactly as written.
    pub date: Option<String>,
    /// The date as the interface would say it, when it could be read.
    pub date_display: Option<String>,
    /// The year the date parsed to (or hinted at), for timelines and checks —
    /// carried here so a caller never re-parses the payload this view already
    /// parsed for [`EventView::sort_key`].
    pub year: Option<i32>,
    /// A number that orders this event against others, when one was found.
    pub sort_key: Option<i64>,
    /// The `PLAC` payload exactly as written.
    pub place: Option<String>,
    /// The `AGE` payload, which several producers write beside a date.
    pub age: Option<String>,
    /// The `CAUS` payload.
    pub cause: Option<String>,
    /// Whether this is a standing fact rather than an occurrence.
    pub attribute: bool,
    /// The payload, when the tag carries one — an occupation, a title. A bare
    /// `Y` is suppressed: `1 DEAT Y` is GEDCOM's way of asserting the event
    /// happened, not a payload worth showing.
    pub value: Option<String>,
    /// Cross-reference identifiers of the sources cited on this event.
    pub citations: Vec<String>,
    /// Where the structure sits in its record.
    pub path: Vec<usize>,
}

impl EventView {
    /// Reads an event or attribute structure.
    #[must_use]
    pub fn from_node(node: &Node, path: Vec<usize>) -> Self {
        let date = node.value_of("DATE");
        let parsed = date.as_deref().map(GedcomDate::parse);
        let described = node
            .value_of("TYPE")
            .filter(|value| !value.trim().is_empty());
        let label = match (node.tag.as_str(), described) {
            (_, Some(kind)) if matches!(node.tag.as_str(), "EVEN" | "FACT") => kind,
            _ => tags::display_label(&node.tag).to_owned(),
        };

        Self {
            tag: node.tag.clone(),
            label,
            date_display: parsed.as_ref().map(GedcomDate::display),
            year: parsed.as_ref().and_then(GedcomDate::year_hint),
            sort_key: parsed.as_ref().and_then(GedcomDate::sort_key),
            date,
            place: node.value_of("PLAC"),
            age: node.value_of("AGE"),
            cause: node.value_of("CAUS"),
            attribute: tags::is_attribute(&node.tag),
            value: node
                .value
                .clone()
                .filter(|value| !value.trim().is_empty() && value != "Y"),
            citations: node
                .all("SOUR")
                .filter_map(|source| source.pointer().map(str::to_owned))
                .collect(),
            path,
        }
    }
}

/// An individual, read for the person view.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
#[non_exhaustive]
pub struct IndividualView {
    /// The cross-reference identifier.
    pub xref: String,
    /// Every `NAME`, in file order. The first is what the file leads with.
    pub names: Vec<NameView>,
    /// The `SEX` payload in words, when there is one.
    pub sex: Option<String>,
    /// Every event and attribute, in the order the file wrote them.
    pub events: Vec<EventView>,
    /// Families this person is a child in.
    pub child_in: Vec<FamilyLinkView>,
    /// Families this person is a partner in.
    pub partner_in: Vec<FamilyLinkView>,
    /// Sources cited on the record itself rather than on one of its events.
    pub citations: Vec<String>,
    /// Media objects the record points at.
    pub media: Vec<String>,
    /// Identifiers other systems know this person by, shown and never
    /// rewritten: `REFN`, `RIN`, `EXID`, `UID`, and vendor extensions.
    pub identifiers: Vec<IdentifierView>,
}

/// One `NAME` structure.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
#[non_exhaustive]
pub struct NameView {
    /// The name as it should be shown.
    pub display: String,
    /// `Surname, Given`.
    pub sort: String,
    /// The payload exactly as written, slashes included.
    pub original: String,
    /// `NAME.TYPE`, when the file said what kind of name this is.
    pub kind: Option<String>,
    /// Sources cited on this name.
    pub citations: Vec<String>,
}

/// A link from a person to a family.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
#[non_exhaustive]
pub struct FamilyLinkView {
    /// The family's cross-reference identifier.
    pub family: String,
    /// `PEDI` in words, when the file gave one.
    pub pedigree: Option<String>,
}

/// An identifier another system knows this record by.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
#[non_exhaustive]
pub struct IdentifierView {
    /// The tag it was written under.
    pub tag: String,
    /// The tag in words, or the tag itself.
    pub label: String,
    /// The identifier.
    pub value: String,
    /// The `TYPE` beneath it, which is what says whose identifier this is.
    pub kind: Option<String>,
}

impl IndividualView {
    /// Reads an `INDI` record.
    #[must_use]
    pub fn from_node(record: &Node) -> Self {
        let mut names = Vec::new();
        let mut events = Vec::new();
        let mut child_in = Vec::new();
        let mut partner_in = Vec::new();
        let mut citations = Vec::new();
        let mut media = Vec::new();
        let mut identifiers = Vec::new();

        for (index, child) in record.children.iter().enumerate() {
            match child.tag.as_str() {
                "NAME" => {
                    let name = PersonalName::from_node(child);
                    names.push(NameView {
                        display: name.display(),
                        sort: name.sort_form(),
                        original: name.original.clone(),
                        kind: name.kind.clone(),
                        citations: pointers_of(child, "SOUR"),
                    });
                }
                "FAMC" => {
                    if let Some(family) = child.pointer() {
                        child_in.push(FamilyLinkView {
                            family: family.to_owned(),
                            pedigree: child
                                .value_of("PEDI")
                                .map(|value| tags::pedigree_label(&value).to_owned()),
                        });
                    }
                }
                "FAMS" => {
                    if let Some(family) = child.pointer() {
                        partner_in.push(FamilyLinkView {
                            family: family.to_owned(),
                            pedigree: None,
                        });
                    }
                }
                "SOUR" => {
                    if let Some(pointer) = child.pointer() {
                        citations.push(pointer.to_owned());
                    }
                }
                "OBJE" => {
                    if let Some(pointer) = child.pointer() {
                        media.push(pointer.to_owned());
                    }
                }
                "REFN" | "RIN" | "EXID" | "UID" | "_UID" => identifiers.push(IdentifierView {
                    tag: child.tag.clone(),
                    label: tags::display_label(&child.tag).to_owned(),
                    value: child.logical_value(),
                    kind: child.value_of("TYPE"),
                }),
                tag if tags::is_event(tag) || tags::is_attribute(tag) => {
                    events.push(EventView::from_node(child, vec![index]));
                }
                // A vendor identifier is worth showing beside the standard
                // ones rather than only in the extensions section.
                tag if tags::is_extension(tag) && tag.contains("ID") => {
                    identifiers.push(IdentifierView {
                        tag: child.tag.clone(),
                        label: tags::display_label(&child.tag).to_owned(),
                        value: child.logical_value(),
                        kind: None,
                    });
                }
                _ => {}
            }
        }

        Self {
            xref: record.xref.clone().unwrap_or_default(),
            names,
            sex: record
                .value_of("SEX")
                .map(|value| tags::sex_label(&value).to_owned()),
            events,
            child_in,
            partner_in,
            citations,
            media,
            identifiers,
        }
    }

    /// The name to lead with, which is the file's first.
    #[must_use]
    pub fn display_name(&self) -> String {
        self.names
            .first()
            .map_or_else(|| "Unnamed".to_owned(), |name| name.display.clone())
    }

    /// The year of the first event with this tag, when its date parsed —
    /// `event_year("BIRT")` for a birth year. The parse already happened in
    /// [`EventView::from_node`]; this is a lookup, not a reading.
    #[must_use]
    pub fn event_year(&self, tag: &str) -> Option<i32> {
        self.events
            .iter()
            .find(|event| event.tag == tag)
            .and_then(|event| event.year)
    }

    /// The years to show beside a name: birth and death, when they parsed.
    #[must_use]
    pub fn life_years(&self) -> Option<String> {
        let year = |tag: &str| self.event_year(tag);
        match (year("BIRT").or_else(|| year("CHR")), year("DEAT")) {
            (Some(birth), Some(death)) => Some(format!("{birth}–{death}")),
            (Some(birth), None) => Some(format!("b. {birth}")),
            (None, Some(death)) => Some(format!("d. {death}")),
            (None, None) => None,
        }
    }
}

/// A family, read for the family view and the pedigree.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
#[non_exhaustive]
pub struct FamilyView {
    /// The cross-reference identifier.
    pub xref: String,
    /// The `HUSB` pointer, when there is one.
    pub husband: Option<String>,
    /// The `WIFE` pointer, when there is one.
    pub wife: Option<String>,
    /// Every `CHIL` pointer, in file order.
    pub children: Vec<String>,
    /// Family events: marriage, divorce, and the rest.
    pub events: Vec<EventView>,
}

impl FamilyView {
    /// Reads a `FAM` record.
    #[must_use]
    pub fn from_node(record: &Node) -> Self {
        let mut children = Vec::new();
        let mut events = Vec::new();
        for (index, child) in record.children.iter().enumerate() {
            match child.tag.as_str() {
                "CHIL" => {
                    if let Some(pointer) = child.pointer() {
                        children.push(pointer.to_owned());
                    }
                }
                tag if tags::is_event(tag) => events.push(EventView::from_node(child, vec![index])),
                _ => {}
            }
        }
        Self {
            xref: record.xref.clone().unwrap_or_default(),
            husband: record
                .first("HUSB")
                .and_then(|node| node.pointer())
                .map(str::to_owned),
            wife: record
                .first("WIFE")
                .and_then(|node| node.pointer())
                .map(str::to_owned),
            children,
            events,
        }
    }

    /// Both partners, in the order the file wrote them.
    #[must_use]
    pub fn partners(&self) -> Vec<String> {
        [self.husband.clone(), self.wife.clone()]
            .into_iter()
            .flatten()
            .collect()
    }
}

fn pointers_of(node: &Node, tag: &str) -> Vec<String> {
    node.all(tag)
        .filter_map(|child| child.pointer().map(str::to_owned))
        .collect()
}

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

    const SAMPLE: &str = "0 HEAD\n\
0 @I1@ INDI\n\
1 NAME Mira Elowen /North Quill/\n\
2 SOUR @S1@\n\
1 SEX F\n\
1 BIRT\n\
2 DATE 14 February 1904\n\
2 PLAC Northbridge, Example County\n\
1 DEAT\n\
2 DATE 9 October 1987\n\
1 RESI\n\
2 PLAC Southmere, Example County\n\
1 FAMC @F7@\n\
2 PEDI adopted\n\
1 FAMS @F2@\n\
1 REFN X9Q2-TEST\n\
2 TYPE FamilySearch\n\
1 _FSFTID X9Q2-TEST\n\
1 NOTE Synthetic example.\n\
0 TRLR\n";

    fn individual() -> Node {
        Document::parse(SAMPLE)
            .expect("parse")
            .record("@I1@")
            .expect("individual")
            .clone()
    }

    #[test]
    fn every_structure_reaches_the_view_including_the_ones_we_do_not_understand() {
        let record = individual();
        let view = RecordView::from_node(&record);

        let tags: Vec<&str> = view
            .structures
            .iter()
            .map(|structure| structure.tag.as_str())
            .collect();
        assert_eq!(
            tags,
            [
                "NAME", "SEX", "BIRT", "DEAT", "RESI", "FAMC", "FAMS", "REFN", "_FSFTID", "NOTE"
            ]
        );

        let extension = view
            .structures
            .iter()
            .find(|structure| structure.tag == "_FSFTID")
            .expect("the extension is shown");
        assert_eq!(extension.kind, "unknown");
        assert!(extension.extension);
        assert_eq!(extension.value, "X9Q2-TEST");
        assert_eq!(extension.label, "_FSFTID");
    }

    #[test]
    fn the_raw_panel_is_the_record_exactly_as_it_will_be_written() {
        let record = individual();
        let view = RecordView::from_node(&record);

        assert!(
            view.raw
                .starts_with("0 @I1@ INDI\n1 NAME Mira Elowen /North Quill/\n")
        );
        assert!(view.raw.contains("1 _FSFTID X9Q2-TEST\n"));
    }

    #[test]
    fn an_individual_reads_into_names_events_families_and_identifiers() {
        let view = IndividualView::from_node(&individual());

        assert_eq!(view.display_name(), "Mira Elowen North Quill");
        assert_eq!(view.sex.as_deref(), Some("Female"));
        assert_eq!(view.life_years().as_deref(), Some("1904–1987"));
        assert_eq!(view.names[0].citations, ["@S1@"]);
        assert_eq!(view.child_in[0].pedigree.as_deref(), Some("Adopted"));
        assert_eq!(view.partner_in[0].family, "@F2@");

        let events: Vec<&str> = view.events.iter().map(|event| event.tag.as_str()).collect();
        assert_eq!(events, ["BIRT", "DEAT", "RESI"]);
        assert!(view.events[2].attribute, "RESI is an attribute");
        assert_eq!(
            view.events[0].date_display.as_deref(),
            Some("14 February 1904")
        );

        let identifiers: Vec<&str> = view
            .identifiers
            .iter()
            .map(|identifier| identifier.tag.as_str())
            .collect();
        assert_eq!(identifiers, ["REFN", "_FSFTID"]);
        assert_eq!(view.identifiers[0].kind.as_deref(), Some("FamilySearch"));
    }

    #[test]
    fn a_record_type_we_do_not_know_still_has_a_title_and_a_view() {
        let record = Document::parse("0 HEAD\n0 @X1@ _OPAQUE\n1 QUERY Tova Testwright\n0 TRLR\n")
            .expect("parse")
            .record("@X1@")
            .expect("record")
            .clone();
        let view = RecordView::from_node(&record);

        assert_eq!(view.tag, "_OPAQUE");
        assert_eq!(view.label, "_OPAQUE");
        assert_eq!(view.structures[0].tag, "QUERY");
        assert_eq!(view.structures[0].value, "Tova Testwright");
    }

    #[test]
    fn a_family_reads_its_partners_children_and_events() {
        let record = Document::parse(
            "0 HEAD\n0 @F1@ FAM\n1 HUSB @I1@\n1 WIFE @I2@\n1 CHIL @I3@\n1 CHIL @I4@\n1 MARR\n2 DATE 1880\n0 TRLR\n",
        )
        .expect("parse")
        .record("@F1@")
        .expect("family")
        .clone();
        let view = FamilyView::from_node(&record);

        assert_eq!(view.partners(), ["@I1@", "@I2@"]);
        assert_eq!(view.children, ["@I3@", "@I4@"]);
        assert_eq!(view.events[0].tag, "MARR");
        assert_eq!(view.events[0].date.as_deref(), Some("1880"));
    }

    #[test]
    fn a_generic_event_is_labelled_by_what_the_file_said_it_was() {
        let record = Document::parse(
            "0 HEAD\n0 @I1@ INDI\n1 EVEN\n2 TYPE Arrival in Minnesota\n2 DATE 1899\n0 TRLR\n",
        )
        .expect("parse")
        .record("@I1@")
        .expect("individual")
        .clone();
        let view = IndividualView::from_node(&record);

        assert_eq!(view.events[0].label, "Arrival in Minnesota");
    }
}