Crate gedcomkit 

A byte-preserving GEDCOM document model.

This crate reads, represents, and writes GEDCOM — 5.5 through 7.x — on the theory that the file is the truth and a library’s job is to lose none of it. Everything a file contains is represented whether or not the caller understands it: unknown tags, vendor extensions, record order, and the exact bytes of every line.

The central guarantee is in Document::to_text: a node no caller touched is written back byte for byte. That is what makes preservation a property of the representation rather than a feature implemented per construct, and it is why Node keeps its source line whenever the canonical rendering of that line would differ from what arrived.

The pieces, from the outside in:

• decode turns the bytes of a file into text: byte-order marks, UTF-16, ANSEL, and the lies a CHAR line tells.
• Document::parse reads that text into records, under Limits that keep a hostile file from exhausting memory before it can be rejected.
• dates, names, tags, and view are readings: projections computed on demand for display, sorting, and search, never a parallel model that could disagree with the document and never a rewrite of it.
• validate reports what the file says that cannot all be true, without refusing or changing any of it.
• convert rewrites a document between 5.5.1 and 7.0 as an explicit, reported operation; schema handles version 7’s extension declarations.
• gedzip reads and writes the GEDZIP container, with the same bounds.

What this crate deliberately does not contain: application extension tags and their meanings, interface state, or any I/O beyond bytes handed to it. Callers with their own extension vocabulary label and declare it themselves (schema, convert::to_version_7_with).

Quickstart

use gedcomkit::view::IndividualView;

let bytes = b"0 HEAD\n1 GEDC\n2 VERS 7.0\n0 @I1@ INDI\n1 NAME Ada /Example/\n1 BIRT\n2 DATE 5 JAN 1882\n0 TRLR\n";

// Bytes to document: encoding sniffed and reported, then parsed.
let (mut document, report) = gedcomkit::Document::from_bytes(bytes)?;
assert!(report.summary().starts_with("Read as UTF-8"));

// Read through a projection; the document stays the truth.
let record = document.record("@I1@").expect("known record");
let person = IndividualView::from_node(record);
assert_eq!(person.display_name(), "Ada Example");
assert_eq!(person.event_year("BIRT"), Some(1882));

// Edit through the setters, which surrender exactly one kept line…
document
    .record_mut("@I1@")
    .and_then(|record| record.first_mut("NAME"))
    .expect("the name line")
    .set_logical_value("Ada /Lovelace/");

// …and write back: every untouched line, byte for byte.
let written = document.to_bytes();
assert!(std::str::from_utf8(&written)?.contains("1 NAME Ada /Lovelace/"));

Re-exports

pub use decode::EncodingReport;

pub use decode::GedcomEncoding;

pub use decode::decode_gedcom;

Modules

convert

Converting a document between GEDCOM 5.5.1 and 7.0.

dates

Reading a GEDCOM date payload without ever rewriting it.

decode

Turning the bytes of a GEDCOM file into text.

family

The family graph: who is whose parent, child, and partner.

gedzip

GEDZIP: a GEDCOM document and its media in a ZIP archive.

names

Reading a NAME structure.

schema

GEDCOM 7’s extension declarations: HEAD.SCHMA.TAG.

synthetic

A synthetic tree of any size, generated rather than collected.

tags

What GEDCOM’s standard tags mean, in words.

validate

What the file says that cannot all be true, and what it does not say at all.

view

Readings of a record, for an interface to show.

Structs

Document

A GEDCOM document: the records of one file, in file order.

GedcomError

A bounded fault in GEDCOM input, with the relevant one-based line.

Limits

Bounds on what will be read. Imported data is hostile, and every one of these exists to keep a malformed or malicious file from exhausting memory before it can be rejected.

Node

One GEDCOM line and the lines nested beneath it.

UnresolvedPointer

A pointer with no record behind it, addressed precisely enough to repair.

Enums

GedcomErrorKind

What kind of fault a GedcomError reports, for callers that react programmatically rather than showing the message.