ged_io 0.12.3

A parser for GEDCOM files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

//! Shared parsing utilities and traits for GEDCOM records.
//!
//! This module provides the core parsing infrastructure for GEDCOM data.
//! Functions are optimized with inline hints for performance-critical paths.

use crate::{
    tokenizer::{Token, Tokenizer, TokenizerTrait},
    types::custom::UserDefinedTag,
    GedcomError,
};

/// Defines shared parsing functionality for GEDCOM records.
pub trait Parser {
    /// Parses GEDCOM tokens into the data structure.
    ///
    /// # Errors
    ///
    /// This function will return an error if parsing fails.
    fn parse(&mut self, tokenizer: &mut Tokenizer, level: u8) -> Result<(), GedcomError>;
}

/// Defines shared parsing functionality for GEDCOM records with any tokenizer.
pub trait StreamParser {
    /// Parses GEDCOM tokens into the data structure using any tokenizer.
    ///
    /// # Errors
    ///
    /// This function will return an error if parsing fails.
    fn parse_stream<T: TokenizerTrait>(
        &mut self,
        tokenizer: &mut T,
        level: u8,
    ) -> Result<(), GedcomError>;
}

/// Parses GEDCOM tokens at a specific hierarchical level, handling both standard and custom tags.
///
/// This function processes tokens from the tokenizer until it encounters a token at or below
/// the specified level, effectively parsing all child elements of a GEDCOM structure.
/// Standard tags are handled by the provided callback, while custom/non-standard tags
/// are collected and returned.
///
/// # Errors
///
/// Returns a `GedcomError` if an unhandled token is encountered or if `UserDefinedTag::new` fails.
#[inline]
pub fn parse_subset<F>(
    tokenizer: &mut Tokenizer,
    level: u8,
    mut tag_handler: F,
) -> Result<Vec<Box<UserDefinedTag>>, GedcomError>
where
    F: FnMut(&str, &mut Tokenizer) -> Result<(), GedcomError>,
{
    let mut non_standard_dataset = Vec::new();
    loop {
        if let Token::Level(curl_level) = tokenizer.current_token {
            if curl_level <= level {
                break;
            }
        }

        match &tokenizer.current_token {
            Token::Tag(tag) => {
                let tag_clone = tag.clone();
                tag_handler(tag_clone.as_ref(), tokenizer)?;
            }
            Token::CustomTag(tag) => {
                let tag_clone = tag.clone();
                non_standard_dataset.push(Box::new(UserDefinedTag::new(
                    tokenizer,
                    level + 1,
                    &tag_clone,
                )?));
            }
            Token::Level(_) => tokenizer.next_token()?,
            Token::LineValue(_) => {
                // Be permissive: some files contain stray empty values where a tag is expected.
                // Skip and continue parsing at the same level.
                tokenizer.next_token()?;
            }
            Token::EOF => break,
            _ => {
                return Err(GedcomError::ParseError {
                    line: tokenizer.line,
                    message: format!("Unhandled Token: {:?}", tokenizer.current_token),
                })
            }
        }
    }
    Ok(non_standard_dataset)
}

/// Generic version of `parse_subset` that works with any tokenizer implementing `TokenizerTrait`.
///
/// This function processes tokens from the tokenizer until it encounters a token at or below
/// the specified level, effectively parsing all child elements of a GEDCOM structure.
/// Standard tags are handled by the provided callback, while custom/non-standard tags
/// are collected and returned.
///
/// # Errors
///
/// Returns a `GedcomError` if an unhandled token is encountered or if `UserDefinedTag::new_from_tokenizer` fails.
#[inline]
pub fn parse_subset_stream<T, F>(
    tokenizer: &mut T,
    level: u8,
    mut tag_handler: F,
) -> Result<Vec<Box<UserDefinedTag>>, GedcomError>
where
    T: TokenizerTrait,
    F: FnMut(&str, &mut T) -> Result<(), GedcomError>,
{
    let mut non_standard_dataset = Vec::new();
    loop {
        if let Token::Level(curl_level) = tokenizer.current_token() {
            if *curl_level <= level {
                break;
            }
        }

        match tokenizer.current_token() {
            Token::Tag(tag) => {
                let tag_clone = tag.clone();
                tag_handler(tag_clone.as_ref(), tokenizer)?;
            }
            Token::CustomTag(tag) => {
                let tag_clone = tag.clone();
                non_standard_dataset.push(Box::new(UserDefinedTag::new_from_tokenizer(
                    tokenizer,
                    level + 1,
                    &tag_clone,
                )?));
            }
            Token::Level(_) => tokenizer.next_token()?,
            Token::LineValue(_) => {
                // Be permissive: some files contain stray empty values where a tag is expected.
                // Skip and continue parsing at the same level.
                tokenizer.next_token()?;
            }
            Token::EOF => break,
            _ => {
                return Err(GedcomError::ParseError {
                    line: tokenizer.line(),
                    message: format!("Unhandled Token: {:?}", tokenizer.current_token()),
                })
            }
        }
    }
    Ok(non_standard_dataset)
}