gedcomkit 0.1.12__tar.gz → 0.1.13__tar.gz

{gedcomkit-0.1.12 → gedcomkit-0.1.13}/CHANGELOG.md

@@ -5,6 +5,26 @@ format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 the project uses semantic versioning within the usual pre-1.0 compatibility
 rules.
 
+## [0.1.13] - 2026-10-02
+
+### Fixed
+
+- `convert::to_version_7` / `to_version_7_with` now convert roles. A role in
+  a cited event (`SOUR`.`EVEN`.`ROLE`) that 5.5.1 writes as free text —
+  its `(descriptor)` form, or a bare word — becomes version 7's enumerated
+  role it names (`Son` → `CHIL`, `Godmother` → `GODP`, `Witness` → `WITN`;
+  `OTHER` when it names none), with the words kept verbatim as a `PHRASE`;
+  an enumerated value in another case is upper-cased. An association's
+  `RELA`, which version 7 spells `ROLE`, gets the same treatment. Before, both
+  were carried into the 7.0 document unchanged, where neither is valid. A
+  role that already has a `PHRASE`, is empty, or has a continuation line with
+  substructures is kept and reported.
+- `convert::to_version_5_5_1` turns them back: under a cited event a role
+  5.5.1 enumerates (`CHIL`, `HUSB`, `WIFE`, `MOTH`, `FATH`, `SPOU`) without a
+  phrase stays, and any other becomes `(words)` — the `PHRASE` when there is
+  one, the role in words otherwise; under an association the role becomes
+  `RELA` with the same words.
+
 ## [0.1.12] - 2026-09-30
 
 ### Fixed

{gedcomkit-0.1.12 → gedcomkit-0.1.13}/Cargo.lock

@@ -35,7 +35,7 @@ dependencies = [
 
 [[package]]
 name = "gedcomkit"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "flate2",
  "serde",

{gedcomkit-0.1.12 → gedcomkit-0.1.13}/Cargo.toml

@@ -3,7 +3,7 @@
 # was checked on crates.io, npm, and PyPI before the initial release.
 [package]
 name = "gedcomkit"
-version = "0.1.12"
+version = "0.1.13"
 description = "A byte-preserving GEDCOM document model: decoding, parsing, readings, version conversion, plausibility checks, and the GEDZIP container, for GEDCOM 5.5 through 7.x."
 edition = "2024"
 # The true minimum, not the workspace's toolchain: a parser library is a leaf

{gedcomkit-0.1.12 → gedcomkit-0.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gedcomkit
-Version: 0.1.12
+Version: 0.1.13
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython

{gedcomkit-0.1.12 → gedcomkit-0.1.13}/bindings/gedcomkit-py/Cargo.lock

@@ -35,7 +35,7 @@ dependencies = [
 
 [[package]]
 name = "gedcomkit"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "flate2",
  "serde",
@@ -43,7 +43,7 @@ dependencies = [
 
 [[package]]
 name = "gedcomkit-py"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "gedcomkit",
  "pyo3",

{gedcomkit-0.1.12 → gedcomkit-0.1.13}/bindings/gedcomkit-py/Cargo.toml

@@ -2,7 +2,7 @@
 # abi3 keeps it to one wheel per platform across Python versions.
 [package]
 name = "gedcomkit-py"
-version = "0.1.12"
+version = "0.1.13"
 description = "Python bindings for gedcomkit: an archival-grade GEDCOM library — byte-preserving round-trip, encoding detection, GEDCOM 5.5 through 7.x, GEDZIP."
 edition = "2024"
 rust-version = "1.88"

{gedcomkit-0.1.12 → gedcomkit-0.1.13}/src/convert.rs

@@ -324,6 +324,18 @@ fn structures_to_7_node(node: &mut Node, shared: &[String], pass: &mut Pass) ->
         changed |= date_to_7(node, pass);
     }
 
+    // A role in a cited event (`SOUR`.`EVEN`.`ROLE`), and an association's
+    // relation, which 5.5.1 spells `RELA` and version 7 `ROLE`: both become
+    // version 7's enumerated role, the words as written kept in a `PHRASE`.
+    if node.tag == "EVEN" || node.tag == "ASSO" {
+        let association = node.tag == "ASSO";
+        for child in &mut node.children {
+            if child.tag == "ROLE" || (association && child.tag == "RELA") {
+                changed |= role_to_7(child, pass);
+            }
+        }
+    }
+
     // A multimedia record's files: `FORM` moves from the object to each
     // `FILE` (5.5), and each file's path, format and medium take version 7's
     // shape (5.5.1 already nests `FORM` under `FILE`, with `TYPE` beneath).
@@ -845,6 +857,201 @@ fn medium_to_7(medium: &str) -> (String, bool) {
     }
 }
 
+/// Version 7's enumerated roles (`enumset-ROLE`).
+const ROLES_7: &[&str] = &[
+    "CHIL",
+    "CLERGY",
+    "FATH",
+    "FRIEND",
+    "GODP",
+    "HUSB",
+    "MOTH",
+    "MULTIPLE",
+    "NGHBR",
+    "OFFICIATOR",
+    "PARENT",
+    "SPOU",
+    "WIFE",
+    "WITN",
+    "OTHER",
+];
+
+/// The enumerated role a word for one reads as, and `OTHER` when none does.
+/// Only a word that names the role outright counts: a son is a child, a
+/// godmother a godparent; anything else is `OTHER`, and the words survive in
+/// the `PHRASE` either way.
+fn role_word_to_7(words: &str) -> &'static str {
+    match words.trim().to_lowercase().as_str() {
+        "child" | "son" | "daughter" => "CHIL",
+        "husband" => "HUSB",
+        "wife" => "WIFE",
+        "mother" => "MOTH",
+        "father" => "FATH",
+        "spouse" => "SPOU",
+        "parent" => "PARENT",
+        "friend" => "FRIEND",
+        "godparent" | "godfather" | "godmother" => "GODP",
+        "witness" => "WITN",
+        "neighbor" | "neighbour" => "NGHBR",
+        "clergy" | "priest" | "minister" | "pastor" => "CLERGY",
+        "officiator" | "officiant" => "OFFICIATOR",
+        "multiple" => "MULTIPLE",
+        _ => "OTHER",
+    }
+}
+
+/// A 5.5.1 role (`ROLE` under a cited event, or an association's `RELA`) in
+/// version 7's shape. A value already in the enumeration stays; free text —
+/// 5.5.1's `(descriptor)` form, or any other word — becomes the enumerated
+/// role it names (`OTHER` when it names none) with the text kept verbatim as
+/// a `PHRASE`.
+fn role_to_7(role: &mut Node, pass: &mut Pass) -> bool {
+    let from_rela = role.tag == "RELA";
+    let original = role.logical_value();
+    let trimmed = original.trim();
+    let upper = trimmed.to_ascii_uppercase();
+    let label = if from_rela { "ASSO.RELA" } else { "ROLE" };
+
+    if !from_rela && ROLES_7.contains(&upper.as_str()) {
+        if upper == original {
+            return false;
+        }
+        if continuation_has_children(role) {
+            refuse_for_continuation_children(label, "role", pass);
+            return false;
+        }
+        role.set_logical_value(&upper);
+        pass.note(
+            label,
+            ConversionKind::Converted,
+            format!("the role {original:?} is version 7's enumerated value {upper}"),
+        );
+        return true;
+    }
+
+    let words = trimmed
+        .strip_prefix('(')
+        .and_then(|inner| inner.strip_suffix(')'))
+        .unwrap_or(trimmed)
+        .trim()
+        .to_owned();
+    if continuation_has_children(role) {
+        refuse_for_continuation_children(label, "role", pass);
+        return false;
+    }
+    if words.is_empty() {
+        pass.note(
+            label,
+            ConversionKind::Kept,
+            "an empty role has no version 7 reading; it is left as it is",
+        );
+        return false;
+    }
+    if role.first("PHRASE").is_some() {
+        pass.note(
+            label,
+            ConversionKind::Kept,
+            format!(
+                "the role {original:?} is not version 7's enumeration, but it already has a PHRASE to keep the words in; it is left as it is"
+            ),
+        );
+        return false;
+    }
+    let value = role_word_to_7(&words);
+    if from_rela {
+        role.set_tag("ROLE");
+    }
+    role.set_logical_value(value);
+    role.push(Node::with_value("PHRASE", &words));
+    pass.note(
+        label,
+        ConversionKind::Converted,
+        if from_rela {
+            format!(
+                "an association's relation {words:?} is version 7's ROLE {value}, with the words kept as a PHRASE"
+            )
+        } else {
+            format!("the role {original:?} became {value}, with the words kept as a PHRASE")
+        },
+    );
+    true
+}
+
+/// The roles 5.5.1 enumerates under a cited event.
+const ROLES_5: &[&str] = &["CHIL", "HUSB", "WIFE", "MOTH", "FATH", "SPOU"];
+
+/// A version 7 role in 5.5.1's spelling. Under an association it becomes
+/// `RELA`, whose payload is free text; under a cited event, a role 5.5.1
+/// enumerates stays and any other becomes `(descriptor)`. A `PHRASE` is the
+/// words to keep, and leaves with them.
+fn role_to_5(role: &mut Node, association: bool, pass: &mut Pass) -> bool {
+    let enumerated = role.logical_value().trim().to_ascii_uppercase();
+    let phrase = role
+        .first("PHRASE")
+        .filter(|phrase| phrase.substructures().next().is_none())
+        .map(Node::logical_value)
+        .filter(|phrase| !phrase.contains('\n') && !phrase.trim().is_empty());
+    if role.first("PHRASE").is_some() && phrase.is_none() {
+        pass.note(
+            "ROLE",
+            ConversionKind::Kept,
+            "5.5.1 holds a role on one line with nothing beneath it, and this role's PHRASE spans lines or has substructures; it is kept as written, which 5.5.1 does not define",
+        );
+        return false;
+    }
+    if continuation_has_children(role) {
+        refuse_for_continuation_children("ROLE", "role", pass);
+        return false;
+    }
+    let words = phrase.unwrap_or_else(|| role_label(&enumerated));
+    if association {
+        remove_child(role, "PHRASE");
+        role.set_tag("RELA");
+        role.set_logical_value(words.trim());
+        pass.note(
+            "ROLE",
+            ConversionKind::Converted,
+            "an association's role is RELA in 5.5.1, a relation in words",
+        );
+        return true;
+    }
+    if role.first("PHRASE").is_none() && ROLES_5.contains(&enumerated.as_str()) {
+        return false;
+    }
+    remove_child(role, "PHRASE");
+    role.set_logical_value(&format!("({})", words.trim()));
+    pass.note(
+        "ROLE",
+        ConversionKind::Converted,
+        "a role 5.5.1 does not enumerate, or one with a phrase, is 5.5.1's parenthesized role descriptor",
+    );
+    true
+}
+
+/// An enumerated role in words, for a 5.5.1 descriptor that has no phrase to
+/// take them from.
+fn role_label(enumerated: &str) -> String {
+    match enumerated {
+        "CHIL" => "Child",
+        "CLERGY" => "Clergy",
+        "FATH" => "Father",
+        "FRIEND" => "Friend",
+        "GODP" => "Godparent",
+        "HUSB" => "Husband",
+        "MOTH" => "Mother",
+        "MULTIPLE" => "Multiple",
+        "NGHBR" => "Neighbor",
+        "OFFICIATOR" => "Officiator",
+        "PARENT" => "Parent",
+        "SPOU" => "Spouse",
+        "WIFE" => "Wife",
+        "WITN" => "Witness",
+        "OTHER" => "Other",
+        other => return other.to_owned(),
+    }
+    .to_owned()
+}
+
 /// Converts a document to GEDCOM 5.5.1.
 #[must_use]
 pub fn to_version_5_5_1(document: &Document) -> Conversion {
@@ -1031,6 +1238,18 @@ fn structures_to_5_node(node: &mut Node, level: usize, pass: &mut Pass) -> bool
         }
     }
 
+    // Version 7's enumerated role goes back to 5.5.1's spelling: free text
+    // in parentheses under a cited event, and `RELA` under an association.
+    if node.tag == "EVEN" || node.tag == "ASSO" {
+        let association = node.tag == "ASSO";
+        for child in &mut node.children {
+            if child.tag == "ROLE" && role_to_5(child, association, pass) {
+                changed = true;
+                crate::build::fit_own_lines(child, level + 1, crate::build::MAX_LINE_LENGTH);
+            }
+        }
+    }
+
     // Everything else version 7 added and 5.5.1 does not define is kept and
     // named. Deleting a translation or a creation date to satisfy a version
     // number would be the worst trade this application could make.
@@ -1312,6 +1531,65 @@ mod tests {
         assert!(note.detail.contains("ole"), "{}", note.detail);
     }
 
+    #[test]
+    fn a_cited_role_in_words_becomes_an_enumerated_role_with_its_phrase() {
+        let document = parse(
+            "0 HEAD\n1 GEDC\n2 VERS 5.5.1\n0 @I1@ INDI\n1 CENS\n2 SOUR @S1@\n3 EVEN CENS\n4 ROLE (Son)\n0 @I2@ INDI\n1 CENS\n2 SOUR @S1@\n3 EVEN CENS\n4 ROLE (Lodger)\n0 @I3@ INDI\n1 BIRT\n2 SOUR @S1@\n3 EVEN BIRT\n4 ROLE MOTH\n0 @S1@ SOUR\n0 TRLR\n",
+        );
+        let outcome = to_version_7(&document);
+        let text = outcome.document.to_text();
+        assert!(text.contains("4 ROLE CHIL\n5 PHRASE Son\n"), "{text}");
+        assert!(text.contains("4 ROLE OTHER\n5 PHRASE Lodger\n"), "{text}");
+        assert!(
+            text.contains("4 ROLE MOTH\n0 @S1@"),
+            "an enumerated role is untouched: {text}"
+        );
+        assert_eq!(
+            outcome
+                .notes
+                .iter()
+                .filter(|note| note.tag == "ROLE")
+                .count(),
+            2,
+            "{:?}",
+            outcome.notes
+        );
+
+        // And back: the words return as 5.5.1's descriptor, the enumerated
+        // role 5.5.1 also knows stays as it is.
+        let back = to_version_5_5_1(&outcome.document).document.to_text();
+        assert!(back.contains("4 ROLE (Son)\n"), "{back}");
+        assert!(back.contains("4 ROLE (Lodger)\n"), "{back}");
+        assert!(back.contains("4 ROLE MOTH\n"), "{back}");
+        assert!(!back.contains("PHRASE"), "{back}");
+    }
+
+    #[test]
+    fn an_association_relation_is_a_role_in_version_seven_and_back() {
+        let document = parse(
+            "0 HEAD\n1 GEDC\n2 VERS 5.5.1\n0 @I1@ INDI\n1 ASSO @I2@\n2 RELA Godfather\n0 @I2@ INDI\n0 TRLR\n",
+        );
+        let seven = to_version_7(&document).document;
+        let text = seven.to_text();
+        assert!(
+            text.contains("1 ASSO @I2@\n2 ROLE GODP\n3 PHRASE Godfather\n"),
+            "{text}"
+        );
+
+        let back = to_version_5_5_1(&seven).document.to_text();
+        assert!(back.contains("1 ASSO @I2@\n2 RELA Godfather\n"), "{back}");
+    }
+
+    #[test]
+    fn a_version_seven_role_without_a_phrase_reads_in_words_in_5_5_1() {
+        let document = parse(
+            "0 HEAD\n1 GEDC\n2 VERS 7.0\n0 @I1@ INDI\n1 BAPM\n2 SOUR @S1@\n3 EVEN BAPM\n4 ROLE GODP\n1 ASSO @I2@\n2 ROLE FRIEND\n0 @I2@ INDI\n0 @S1@ SOUR\n0 TRLR\n",
+        );
+        let back = to_version_5_5_1(&document).document.to_text();
+        assert!(back.contains("4 ROLE (Godparent)\n"), "{back}");
+        assert!(back.contains("2 RELA Friend\n"), "{back}");
+    }
+
     #[test]
     fn an_unrecognized_source_medium_becomes_other_with_a_phrase() {
         let document = parse(