Crate ged_io 

ged_io is a Rust crate for parsing GEDCOM formatted text.

The library works with GEDCOM (Genealogical Data Communication), a text-based format widely supported by genealogy software for storing and exchanging family history data. ged_io transforms this text format into workable Rust data structures.

Version Support

This library supports both GEDCOM 5.5.1 and GEDCOM 7.0 specifications:

• GEDCOM 5.5.1 (1999/2019): The previous major version, widely supported
• GEDCOM 7.0 (2021+): The current version with UTF-8 encoding, extension schemas, and new structure types

Basic example:

use ged_io::Gedcom;
use std::error::Error;
use std::fs;

// Parse a GEDCOM file
fn main() -> Result<(), Box<dyn Error>> {
    let source = fs::read_to_string("./tests/fixtures/sample.ged")?;
    let mut gedcom = Gedcom::new(source.chars())?;
    let gedcom_data = gedcom.parse_data()?;

    // Display file statistics
    gedcom_data.stats();
    Ok(())
}

This crate contains an optional "json" feature that implements serialization and deserialization to JSON with serde.

To enable JSON support, add the feature to your Cargo.toml:

[dependencies]
ged_io = { version = "0.4", features = ["json"] }

JSON serialization example:

use ged_io::Gedcom;
use std::error::Error;

#[cfg(feature = "json")]
fn serialize_to_json() -> Result<(), Box<dyn Error>> {
    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())?;
    let gedcom_data = gedcom.parse_data()?;

    let json_output = serde_json::to_string_pretty(&gedcom_data)?;
    println!("GEDCOM as JSON:\n{}", json_output);

    Ok(())
}

Version Detection Example

use ged_io::version::{detect_version, GedcomVersion};

let content = "0 HEAD\n1 GEDC\n2 VERS 7.0\n0 TRLR";
let version = detect_version(content);
assert_eq!(version, GedcomVersion::V7_0);

let content = "0 HEAD\n1 GEDC\n2 VERS 5.5.1\n0 TRLR";
let version = detect_version(content);
assert_eq!(version, GedcomVersion::V5_5_1);

Error Handling Example

This example demonstrates how to handle GedcomError when parsing a malformed GEDCOM string.

use ged_io::Gedcom;
use ged_io::GedcomError;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    let malformed_gedcom = "0 HEAD\n1 GEDC\n2 VERS 5.5\n1 INVALID_TAG\n0 TRLR";
    let mut gedcom = Gedcom::new(malformed_gedcom.chars())?;

    match gedcom.parse_data() {
        Ok(_) => println!("Parsing successful!"),
        Err(e) => {
            eprintln!("Error parsing GEDCOM: {}", e);
            match e {
                GedcomError::ParseError { line, message } => {
                    eprintln!("Parse error at line {}: {}", line, message);
                }
                GedcomError::InvalidFormat(msg) => {
                    eprintln!("Invalid format: {}", msg);
                }
                GedcomError::EncodingError(msg) => {
                    eprintln!("Encoding error: {}", msg);
                }
                GedcomError::InvalidTag { line, tag } => {
                    eprintln!("Invalid tag '{}' at line {}", tag, line);
                }
                GedcomError::UnexpectedLevel { line, expected, found } => {
                    eprintln!("Unexpected level at line {}: expected {}, found {}", line, expected, found);
                }
                GedcomError::MissingRequiredValue { line, tag } => {
                    eprintln!("Missing required value for '{}' at line {}", tag, line);
                }
                GedcomError::InvalidValueFormat { line, value, expected_format } => {
                    eprintln!("Invalid format for '{}' at line {}: expected {}", value, line, expected_format);
                }
                GedcomError::FileSizeLimitExceeded { size, max_size } => {
                    eprintln!("File too large: {} bytes (max: {} bytes)", size, max_size);
                }
                GedcomError::IoError(msg) => {
                    eprintln!("I/O error: {}", msg);
                }
            }
        }
    }
    Ok(())
}

Re-exports

pub use builder::GedcomBuilder;

pub use builder::ParserConfig;

pub use debug::ImprovedDebug;

pub use encoding::decode_gedcom_bytes;

pub use encoding::detect_encoding;

pub use encoding::GedcomEncoding;

pub use error::GedcomError;

pub use stream::GedcomRecord;

pub use stream::GedcomStreamParser;

pub use types::SourceCitationStats;

pub use version::detect_version;

pub use version::GedcomVersion;

pub use version::VersionFeatures;

pub use writer::GedcomWriter;

pub use writer::WriterConfig;

Modules

builder

Builder pattern for configuring GEDCOM parsing. Builder pattern implementation for configuring GEDCOM parsing.

debug

Improved Debug trait implementations for GEDCOM data structures. Improved Debug trait implementations for GEDCOM data structures.

display

Display trait implementations for GEDCOM data structures. Display trait implementations for GEDCOM data structures.

encoding

Character encoding detection and conversion for GEDCOM files.

error

Error types for the ged_io crate.

indexed

Indexed GEDCOM data structure for O(1) lookups. Indexed GEDCOM data structure for O(1) lookups.

parser

Shared parsing utilities and traits for GEDCOM records.

stream

Streaming parser for large GEDCOM files.

tokenizer

Processes character streams into tokens.

types

Data structures representing the parsed contents of a GEDCOM file.

util

Utility functions for GEDCOM processing.

version

GEDCOM version detection and handling.

writer

Writer module for serializing GEDCOM data back to GEDCOM format.

Macros

fmt_optional_value

Macro for displaying Options in debug mode without the text wrapping.

Structs

Gedcom

The main interface for parsing GEDCOM files into structured Rust data types.