ged_io 0.12.3

pub mod association;
pub mod attribute;
pub mod family_link;
pub mod gender;
pub mod name;

use crate::{
    parser::{parse_subset, Parser},
    tokenizer::Tokenizer,
    types::{
        custom::UserDefinedTag,
        date::change_date::ChangeDate,
        event::{detail::Detail, util::HasEvents},
        gedcom7::NonEvent,
        individual::{
            association::Association,
            attribute::detail::AttributeDetail,
            family_link::FamilyLink,
            gender::{Gender, GenderType},
            name::Name,
        },
        lds::LdsOrdinance,
        multimedia::Multimedia,
        note::Note,
        source::citation::Citation,
        Xref,
    },
    GedcomError,
};

#[cfg(feature = "json")]
use serde::{Deserialize, Serialize};

/// Individual (tag: INDI) represents a compilation of facts or hypothesized facts about an
/// individual. These facts may come from multiple sources. Source citations and notes allow
/// documentation of the source where each of the facts were discovered. See
/// <https://gedcom.io/specifications/FamilySearchGEDCOMv7.html#INDIVIDUAL_RECORD>.
///
/// # GEDCOM 7.0 Additions
///
/// In GEDCOM 7.0, individuals can have:
/// - `NO` - Non-event assertions (e.g., "NO MARR" means never married)
///
/// See <https://gedcom.io/specifications/FamilySearchGEDCOMv7.html#NO>
#[derive(Clone, Debug, Default, PartialEq)]
#[cfg_attr(feature = "json", derive(Serialize, Deserialize))]
pub struct Individual {
    pub xref: Option<Xref>,
    pub name: Option<Name>,
    pub sex: Option<Gender>,
    pub families: Vec<FamilyLink>,
    pub attributes: Vec<AttributeDetail>,
    pub source: Vec<Citation>,
    pub events: Vec<Detail>,
    pub multimedia: Vec<Multimedia>,
    pub last_updated: Option<String>,
    pub note: Option<Note>,
    pub change_date: Option<ChangeDate>,
    pub custom_data: Vec<Box<UserDefinedTag>>,
    /// Non-event assertions for GEDCOM 7.0.
    ///
    /// These assert that specific events did NOT occur (e.g., "NO MARR" means
    /// the individual never married). This is distinct from omitting an event
    /// (which means unknown).
    pub non_events: Vec<NonEvent>,
    /// LDS (Latter-day Saints) ordinances.
    ///
    /// These include BAPL (Baptism), CONL (Confirmation), INIL (Initiatory - GEDCOM 7.0 only),
    /// ENDL (Endowment), and SLGC (Sealing to parents).
    pub lds_ordinances: Vec<LdsOrdinance>,
    /// Associations with other individuals.
    ///
    /// Used to link individuals who have some relationship not covered by other
    /// standard tags (e.g., friends, neighbors, witnesses).
    pub associations: Vec<Association>,
    /// Unique identifier (tag: UID).
    ///
    /// A globally unique identifier for this record. In GEDCOM 7.0, this is
    /// a URI that uniquely identifies the record across all datasets.
    ///
    /// See <https://gedcom.io/specifications/FamilySearchGEDCOMv7.html#UID>
    pub uid: Option<String>,
    /// Restriction notice (tag: RESN).
    ///
    /// A flag that indicates access to information has been restricted.
    /// Valid values are:
    /// - `confidential` - Not for public distribution
    /// - `locked` - Cannot be modified
    /// - `privacy` - Information is private
    ///
    /// See <https://gedcom.io/specifications/FamilySearchGEDCOMv7.html#RESN>
    pub restriction: Option<String>,
    /// User reference number (tag: REFN).
    ///
    /// A user-defined number or text that the submitter uses to identify
    /// this record. Not guaranteed to be unique.
    pub user_reference_number: Option<String>,
    /// User reference type (tag: TYPE under REFN).
    ///
    /// A user-defined type for the reference number.
    pub user_reference_type: Option<String>,
    /// Automated record ID (tag: RIN).
    ///
    /// A unique record identification number assigned to the record by
    /// the source system. Used for reconciling differences between systems.
    pub automated_record_id: Option<String>,
    /// Ancestral File Number (tag: AFN).
    ///
    /// A unique permanent record file number of an individual record
    /// stored in Ancestral File (LDS-specific).
    pub ancestral_file_number: Option<String>,
    /// Alias pointers (tag: ALIA).
    ///
    /// Pointers to other individual records that may be the same person.
    /// Used when combining records from different sources that may refer
    /// to the same individual.
    pub aliases: Vec<Xref>,
    /// Interest in ancestors (tag: ANCI).
    ///
    /// Indicates an interest in researching the ancestry of this individual.
    /// Points to a submitter record who has this interest.
    pub ancestor_interest: Option<Xref>,
    /// Interest in descendants (tag: DESI).
    ///
    /// Indicates an interest in researching the descendants of this individual.
    /// Points to a submitter record who has this interest.
    pub descendant_interest: Option<Xref>,
    /// External identifiers (tag: EXID, GEDCOM 7.0).
    ///
    /// Identifiers maintained by external authorities that apply to this individual.
    pub external_ids: Vec<String>,
}

impl Individual {
    #[must_use]
    fn with_xref(xref: Option<Xref>) -> Self {
        Self {
            xref,
            ..Default::default()
        }
    }

    /// Creates a new `Individual` from a `Tokenizer`.
    ///
    /// # Errors
    ///
    /// This function will return an error if parsing fails.
    pub fn new(
        tokenizer: &mut Tokenizer,
        level: u8,
        xref: Option<Xref>,
    ) -> Result<Individual, GedcomError> {
        let mut indi = Individual::with_xref(xref);
        indi.parse(tokenizer, level)?;
        Ok(indi)
    }

    pub fn add_family(&mut self, link: FamilyLink) {
        let mut do_add = true;
        let xref = &link.xref;
        for family in &self.families {
            if family.xref.as_str() == xref.as_str() {
                do_add = false;
            }
        }
        if do_add {
            self.families.push(link);
        }
    }

    pub fn add_source_citation(&mut self, sour: Citation) {
        self.source.push(sour);
    }

    pub fn add_multimedia(&mut self, multimedia: Multimedia) {
        self.multimedia.push(multimedia);
    }

    pub fn add_attribute(&mut self, attribute: AttributeDetail) {
        self.attributes.push(attribute);
    }

    #[must_use]
    pub fn families(&self) -> &[FamilyLink] {
        &self.families
    }

    // ========================================================================
    // Convenience Methods for Common Data Access (Issue #29)
    // ========================================================================

    /// Gets the full name as a formatted string, removing GEDCOM slashes.
    ///
    /// # Example
    ///
    /// ```rust
    /// use ged_io::Gedcom;
    ///
    /// let source = "0 HEAD\n1 GEDC\n2 VERS 5.5\n0 @I1@ INDI\n1 NAME John /Doe/\n0 TRLR";
    /// let mut gedcom = Gedcom::new(source.chars()).unwrap();
    /// let data = gedcom.parse_data().unwrap();
    ///
    /// let name = data.individuals[0].full_name();
    /// assert_eq!(name, Some("John Doe".to_string()));
    /// ```
    #[must_use]
    pub fn full_name(&self) -> Option<String> {
        self.name.as_ref().and_then(|n| {
            n.value
                .as_ref()
                .map(|v| v.replace('/', "").trim().to_string())
        })
    }

    /// Gets the given (first) name if available.
    #[must_use]
    pub fn given_name(&self) -> Option<&str> {
        self.name.as_ref().and_then(|n| n.given.as_deref())
    }

    /// Gets the surname (family name) if available.
    #[must_use]
    pub fn surname(&self) -> Option<&str> {
        self.name.as_ref().and_then(|n| n.surname.as_deref())
    }

    /// Checks if the individual is male.
    #[must_use]
    pub fn is_male(&self) -> bool {
        self.sex
            .as_ref()
            .is_some_and(|s| matches!(s.value, GenderType::Male))
    }

    /// Checks if the individual is female.
    #[must_use]
    pub fn is_female(&self) -> bool {
        self.sex
            .as_ref()
            .is_some_and(|s| matches!(s.value, GenderType::Female))
    }

    /// Gets the birth event details if available.
    #[must_use]
    pub fn birth(&self) -> Option<&Detail> {
        self.events
            .iter()
            .find(|e| matches!(e.event, crate::types::event::Event::Birth))
    }

    /// Gets the death event details if available.
    #[must_use]
    pub fn death(&self) -> Option<&Detail> {
        self.events
            .iter()
            .find(|e| matches!(e.event, crate::types::event::Event::Death))
    }

    /// Gets the birth date as a string if available.
    #[must_use]
    pub fn birth_date(&self) -> Option<&str> {
        self.birth()
            .and_then(|b| b.date.as_ref())
            .and_then(|d| d.value.as_deref())
    }

    /// Gets the death date as a string if available.
    #[must_use]
    pub fn death_date(&self) -> Option<&str> {
        self.death()
            .and_then(|d| d.date.as_ref())
            .and_then(|d| d.value.as_deref())
    }

    /// Gets the birth place if available.
    #[must_use]
    pub fn birth_place(&self) -> Option<&str> {
        self.birth()
            .and_then(|b| b.place.as_ref())
            .and_then(|p| p.value.as_deref())
    }

    /// Gets the death place if available.
    #[must_use]
    pub fn death_place(&self) -> Option<&str> {
        self.death()
            .and_then(|d| d.place.as_ref())
            .and_then(|p| p.value.as_deref())
    }

    /// Gets all events of a specific type.
    #[must_use]
    pub fn events_of_type(&self, event_type: &crate::types::event::Event) -> Vec<&Detail> {
        self.events
            .iter()
            .filter(|e| &e.event == event_type)
            .collect()
    }

    /// Checks if the individual has any events recorded.
    #[must_use]
    pub fn has_events(&self) -> bool {
        !self.events.is_empty()
    }

    /// Checks if the individual has any sources cited.
    #[must_use]
    pub fn has_sources(&self) -> bool {
        !self.source.is_empty()
    }
}

impl HasEvents for Individual {
    fn add_event(&mut self, event: Detail) {
        self.events.push(event);
    }
    fn events(&self) -> Vec<Detail> {
        self.events.clone()
    }
}

impl Parser for Individual {
    /// parse handles the INDI top-level tag
    fn parse(
        &mut self,
        tokenizer: &mut crate::tokenizer::Tokenizer,
        level: u8,
    ) -> Result<(), GedcomError> {
        // skip over INDI tag name
        tokenizer.next_token()?;

        let handle_subset = |tag: &str, tokenizer: &mut Tokenizer| -> Result<(), GedcomError> {
            match tag {
                // TODO handle xref
                "NAME" => self.name = Some(Name::new(tokenizer, level + 1)?),
                "SEX" => self.sex = Some(Gender::new(tokenizer, level + 1)?),
                "ADOP" | "BIRT" | "BAPM" | "BARM" | "BASM" | "BLES" | "BURI" | "CENS" | "CHR"
                | "CHRA" | "CONF" | "CREM" | "DEAT" | "EMIG" | "FCOM" | "GRAD" | "IMMI"
                | "NATU" | "ORDN" | "RETI" | "PROB" | "WILL" | "EVEN" | "MARR" => {
                    self.add_event(Detail::new(tokenizer, level + 1, tag)?);
                }
                "CAST" | "DSCR" | "EDUC" | "IDNO" | "NATI" | "NCHI" | "NMR" | "OCCU" | "PROP"
                | "RELI" | "RESI" | "SSN" | "TITL" | "FACT" => {
                    self.add_attribute(AttributeDetail::new(tokenizer, level + 1, tag)?);
                }
                "FAMC" | "FAMS" => {
                    self.add_family(FamilyLink::new(tokenizer, level + 1, tag)?);
                }
                "CHAN" => self.change_date = Some(ChangeDate::new(tokenizer, level + 1)?),
                "SOUR" => {
                    self.add_source_citation(Citation::new(tokenizer, level + 1)?);
                }
                "OBJE" => self.add_multimedia(Multimedia::new(tokenizer, level + 1, None)?),
                "NOTE" => self.note = Some(Note::new(tokenizer, level + 1)?),
                "NO" => self.non_events.push(NonEvent::new(tokenizer, level + 1)?),
                // LDS Ordinances (INIL is GEDCOM 7.0 only)
                "BAPL" | "CONL" | "INIL" | "ENDL" | "SLGC" => {
                    self.lds_ordinances
                        .push(LdsOrdinance::new(tokenizer, level + 1, tag)?);
                }
                // Associations with other individuals
                "ASSO" => {
                    self.associations
                        .push(Association::new(tokenizer, level + 1)?);
                }
                // Unique identifier (GEDCOM 7.0)
                "UID" => self.uid = Some(tokenizer.take_line_value()?),
                // Restriction notice
                "RESN" => self.restriction = Some(tokenizer.take_line_value()?),
                // User reference number
                "REFN" => {
                    self.user_reference_number = Some(tokenizer.take_line_value()?);
                    // Note: TYPE substructure would need to be parsed here
                }
                // Automated record ID
                "RIN" => self.automated_record_id = Some(tokenizer.take_line_value()?),
                // Ancestral File Number (LDS)
                "AFN" => self.ancestral_file_number = Some(tokenizer.take_line_value()?),
                // Alias pointer
                "ALIA" => self.aliases.push(tokenizer.take_line_value()?),
                // Interest in ancestors
                "ANCI" => self.ancestor_interest = Some(tokenizer.take_line_value()?),
                // Interest in descendants
                "DESI" => self.descendant_interest = Some(tokenizer.take_line_value()?),
                // External identifier (GEDCOM 7.0)
                "EXID" => self.external_ids.push(tokenizer.take_line_value()?),
                _ => {
                    return Err(GedcomError::ParseError {
                        line: tokenizer.line,
                        message: format!("Unhandled Individual Tag: {tag}"),
                    })
                }
            }

            Ok(())
        };

        self.custom_data = parse_subset(tokenizer, level, handle_subset)?;

        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use crate::Gedcom;

    #[test]
    fn test_parse_individual_record() {
        let sample = "\
           0 HEAD\n\
           1 GEDC\n\
           2 VERS 5.5\n\
           0 @PERSON1@ INDI\n\
           1 NAME John Doe\n\
           1 SEX M\n\
           0 TRLR";

        let mut doc = Gedcom::new(sample.chars()).unwrap();
        let data = doc.parse_data().unwrap();

        let indi = &data.individuals[0];
        assert_eq!(indi.xref.as_ref().unwrap(), "@PERSON1@");
        assert_eq!(
            indi.name.as_ref().unwrap().value.as_ref().unwrap(),
            "John Doe"
        );
        assert_eq!(indi.sex.as_ref().unwrap().value.to_string(), "Male");
    }

    #[test]
    fn test_parse_gender_record() {
        let sample = "\
            0 HEAD\n\
            1 GEDC\n\
            2 VERS 5.5\n\
            0 @PERSON1@ INDI\n\
            1 SEX M
            2 FACT A fact about an individual's gen
            3 CONC der
            2 SOUR @CITATION1@
            3 PAGE Page
            4 CONC : 132
            3 _MYOWNTAG This is a non-standard tag. Not recommended but allowed
            0 TRLR";

        let mut doc = Gedcom::new(sample.chars()).unwrap();
        let data = doc.parse_data().unwrap();

        let sex = data.individuals[0].sex.as_ref().unwrap();
        assert_eq!(sex.value.to_string(), "Male");
        assert_eq!(
            sex.fact.as_ref().unwrap(),
            "A fact about an individual's gender"
        );
        assert_eq!(sex.sources[0].xref, "@CITATION1@");
        assert_eq!(sex.sources[0].page.as_ref().unwrap(), "Page: 132");
    }

    #[test]
    fn test_parse_family_link_record() {
        let sample = "\
           0 HEAD\n\
           1 GEDC\n\
           2 VERS 5.5\n\
           0 @PERSON1@ INDI\n\
           1 NAME given name\n\
           1 SEX M\n\
           1 ADOP\n\
           2 DATE CAL 31 DEC 1897\n\
           2 FAMC @ADOPTIVE_PARENTS@\n\
           3 PEDI adopted
           3 ADOP BOTH\n\
           3 STAT proven
           0 TRLR";

        let mut doc = Gedcom::new(sample.chars()).unwrap();
        let data = doc.parse_data().unwrap();

        let famc = data.individuals[0].events[0].family_link.as_ref().unwrap();
        assert_eq!(famc.xref, "@ADOPTIVE_PARENTS@");
        assert_eq!(famc.family_link_type.to_string(), "Child");
        assert_eq!(
            famc.pedigree_linkage_type.as_ref().unwrap().to_string(),
            "Adopted"
        );
        assert_eq!(
            famc.child_linkage_status.as_ref().unwrap().to_string(),
            "Proven"
        );
        assert_eq!(famc.adopted_by.as_ref().unwrap().to_string(), "Both");
    }

    #[test]
    fn test_parse_name_record() {
        let sample = "\
           0 HEAD\n\
           1 GEDC\n\
           2 VERS 5.5\n\
           0 @PERSON1@ INDI\n\
           1 NAME John Doe\n\
           0 TRLR";

        let mut doc = Gedcom::new(sample.chars()).unwrap();
        let data = doc.parse_data().unwrap();

        let indi = &data.individuals[0];
        assert_eq!(indi.xref.as_ref().unwrap(), "@PERSON1@");
        assert_eq!(
            indi.name.as_ref().unwrap().value.as_ref().unwrap(),
            "John Doe"
        );
    }

    #[test]
    fn test_parse_attribute_detail_record() {
        let sample = "\
           0 HEAD\n\
           1 GEDC\n\
           2 VERS 5.5\n\
           0 @PERSON1@ INDI\n\
           1 DSCR Physical description\n\
           2 DATE 31 DEC 1997\n\
           2 PLAC The place\n\
           2 SOUR @SOURCE1@\n\
           3 PAGE 42\n\
           3 DATA\n\
           4 DATE 31 DEC 1900\n\
           4 TEXT a sample text\n\
           5 CONT Sample text continued here. The word TE\n\
           5 CONC ST should not be broken!\n\
           3 QUAY 3\n\
           3 NOTE A note\n\
           4 CONT Note continued here. The word TE\n\
           4 CONC ST should not be broken!\n\
           2 NOTE PHY_DESCRIPTION event note (the physical characteristics of a person, place, or thing)\n\
           3 CONT Note continued here. The word TE\n\
           3 CONC ST should not be broken!\n\
           0 TRLR";

        let mut doc = Gedcom::new(sample.chars()).unwrap();
        let data = doc.parse_data().unwrap();

        assert_eq!(data.individuals.len(), 1);

        let attr = &data.individuals[0].attributes[0];
        assert_eq!(attr.attribute.to_string(), "PhysicalDescription");
        assert_eq!(attr.value.as_ref().unwrap(), "Physical description");
        assert_eq!(
            attr.date.as_ref().unwrap().value.as_ref().unwrap(),
            "31 DEC 1997"
        );
        assert_eq!(
            attr.place.as_ref().unwrap().value.as_ref().unwrap(),
            "The place"
        );

        let a_sour = &data.individuals[0].attributes[0].sources[0];
        assert_eq!(a_sour.page.as_ref().unwrap(), "42");
        assert_eq!(
            a_sour
                .data
                .as_ref()
                .unwrap()
                .date
                .as_ref()
                .unwrap()
                .value
                .as_ref()
                .unwrap(),
            "31 DEC 1900"
        );
        assert_eq!(
            a_sour
                .data
                .as_ref()
                .unwrap()
                .text
                .as_ref()
                .unwrap()
                .value
                .as_ref()
                .unwrap(),
            "a sample text\nSample text continued here. The word TEST should not be broken!"
        );
        assert_eq!(
            a_sour.certainty_assessment.as_ref().unwrap().to_string(),
            "Direct"
        );
        assert_eq!(
            a_sour.note.as_ref().unwrap().value.as_ref().unwrap(),
            "A note\nNote continued here. The word TEST should not be broken!"
        );
    }
}