geneweb 0.6.0

A parser for GeneWeb .gw genealogy files, with conversion to GEDCOM via oxidged
Documentation
//! Rendering `.gw` dates as GEDCOM date values.
//!
//! Follows `ged_date_dmy` in GeneWeb's `bin/gwb2ged/gwb2gedLib.ml`, so that this crate
//! and GeneWeb's own exporter produce the same strings.
//!
//! `oxidged` keeps a date as the text it is written as, in GEDCOM syntax, so the whole job
//! here is formatting: precision keyword, calendar escape, zero-padded day, month *name*,
//! year. `oxidged`'s writer converts that text to the grammar of the version it writes.
//! The formatting stays here rather than in `oxidged`'s date values because it reproduces
//! `gwb2ged`: a zero-padded day, and a thirteenth Gregorian month kept as its number.

use std::fmt::Write as _;

use oxidged::model::Date;

use crate::date::{Calendar, Dmy, Dmy2, GwDate, Precision};

/// Gregorian and Julian month abbreviations.
const GREGORIAN_MONTHS: [&str; 12] = [
    "JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC",
];

/// French Republican month abbreviations. The thirteenth covers the complementary days.
const FRENCH_MONTHS: [&str; 13] = [
    "VEND", "BRUM", "FRIM", "NIVO", "PLUV", "VENT", "GERM", "FLOR", "PRAI", "MESS", "THER", "FRUC",
    "COMP",
];

/// Hebrew month abbreviations. The thirteenth is the leap-year intercalation.
const HEBREW_MONTHS: [&str; 13] = [
    "TSH", "CSH", "KSL", "TVT", "SHV", "ADR", "ADS", "NSN", "IYR", "SVN", "TMZ", "AAV", "ELL",
];

/// The GEDCOM escape that introduces a non-Gregorian date.
fn calendar_escape(calendar: Calendar) -> &'static str {
    match calendar {
        // Gregorian is the default and is written without an escape.
        Calendar::Gregorian => "",
        Calendar::Julian => "@#DJULIAN@ ",
        Calendar::French => "@#DFRENCH R@ ",
        Calendar::Hebrew => "@#DHEBREW@ ",
    }
}

/// The month abbreviation for a calendar, or `None` when the number has no name.
fn month_name(calendar: Calendar, month: u8) -> Option<&'static str> {
    let index = usize::from(month.checked_sub(1)?);
    match calendar {
        Calendar::Gregorian | Calendar::Julian => GREGORIAN_MONTHS.get(index).copied(),
        Calendar::French => FRENCH_MONTHS.get(index).copied(),
        Calendar::Hebrew => HEBREW_MONTHS.get(index).copied(),
    }
}

/// Renders a year, marking years before the common era.
fn year(value: i32) -> String {
    if value >= 0 {
        value.to_string()
    } else {
        format!("{} BCE", -value)
    }
}

/// Appends `day month year` in GEDCOM order, omitting components that are zero.
fn push_ymd(out: &mut String, calendar: Calendar, day: u8, month: u8, y: i32) {
    out.push_str(calendar_escape(calendar));
    if day != 0 {
        let _ = write!(out, "{day:02} ");
    }
    if month != 0 {
        match month_name(calendar, month) {
            Some(name) => out.push_str(name),
            // A thirteenth Gregorian month has no abbreviation. GeneWeb's exporter fails
            // here; emitting the number keeps the value rather than losing it.
            None => out.push_str(&month.to_string()),
        }
        out.push(' ');
    }
    out.push_str(&year(y));
}

/// The keyword that introduces a date of this precision.
fn precision_keyword(precision: &Precision) -> &'static str {
    match precision {
        Precision::Sure => "",
        Precision::About => "ABT ",
        // GEDCOM has no "possibly"; GeneWeb maps it to "estimated".
        Precision::Maybe => "EST ",
        Precision::Before => "BEF ",
        Precision::After => "AFT ",
        // Both an alternative and an interval become a GEDCOM range.
        Precision::OrYear(_) | Precision::YearInt(_) => "BET ",
    }
}

/// Formats a structured date as a GEDCOM date value.
#[must_use]
pub fn format_dmy(dmy: &Dmy, calendar: Calendar) -> String {
    let mut out = String::from(precision_keyword(&dmy.precision));
    push_ymd(&mut out, calendar, dmy.day, dmy.month, dmy.year);
    if let Precision::OrYear(alt) | Precision::YearInt(alt) = &dmy.precision {
        let Dmy2 {
            day,
            month,
            year: y,
        } = *alt;
        out.push_str(" AND ");
        push_ymd(&mut out, calendar, day, month, y);
    }
    out
}

/// The GEDCOM 5.5.1 date value of a `.gw` date.
pub(crate) fn value(date: &GwDate) -> String {
    match date {
        GwDate::Structured { dmy, calendar } => format_dmy(dmy, *calendar),
        // The GEDCOM 5.5.1 date phrase GeneWeb emits: the value `(text)`, with no
        // `PHRASE`. `oxidged`'s writer turns it into an empty `DATE` with a `PHRASE` when
        // it writes GEDCOM 7.
        GwDate::Text(text) => format!("({text})"),
    }
}

/// Converts a `.gw` date into a `oxidged` date.
#[must_use]
pub fn to_gedcom(date: &GwDate) -> Date {
    Date::new(value(date))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::date::parse;

    fn ged(s: &str) -> String {
        let date = parse(s)
            .unwrap_or_else(|e| panic!("{e}"))
            .unwrap_or_else(|| panic!("{s:?} is an unknown date"));
        to_gedcom(&date)
            .value
            .as_owned()
            .expect("a date the conversion owns")
            .to_owned()
    }

    #[test]
    fn plain_dates() {
        assert_eq!(ged("1850"), "1850");
        assert_eq!(ged("5/1850"), "MAY 1850");
        assert_eq!(ged("12/5/1850"), "12 MAY 1850");
        // Days are zero-padded, as GEDCOM expects.
        assert_eq!(ged("3/5/1850"), "03 MAY 1850");
    }

    #[test]
    fn precision_keywords() {
        assert_eq!(ged("~1850"), "ABT 1850");
        assert_eq!(ged("?1850"), "EST 1850");
        assert_eq!(ged("<1850"), "BEF 1850");
        assert_eq!(ged(">1850"), "AFT 1850");
    }

    #[test]
    fn ranges_become_bet_and() {
        assert_eq!(ged("1850..1860"), "BET 1850 AND 1860");
        assert_eq!(ged("1850|1851"), "BET 1850 AND 1851");
        assert_eq!(ged("1/1/1850..3/6/1860"), "BET 01 JAN 1850 AND 03 JUN 1860");
    }

    #[test]
    fn calendars_use_gedcom_escapes() {
        assert_eq!(ged("12/5/1750J"), "@#DJULIAN@ 12 MAY 1750");
        assert_eq!(ged("3/13/8F"), "@#DFRENCH R@ 03 COMP 8");
        assert_eq!(ged("12/5/5750H"), "@#DHEBREW@ 12 SHV 5750");
        // Gregorian carries no escape.
        assert_eq!(ged("12/5/1750G"), "12 MAY 1750");
    }

    #[test]
    fn the_calendar_escape_repeats_on_the_second_half_of_a_range() {
        assert_eq!(
            ged("1750..1760J"),
            "BET @#DJULIAN@ 1750 AND @#DJULIAN@ 1760"
        );
    }

    #[test]
    fn years_before_the_common_era() {
        assert_eq!(ged("-52"), "52 BCE");
        assert_eq!(ged("15/3/-44"), "15 MAR 44 BCE");
    }

    #[test]
    fn text_dates_become_a_phrase() {
        let date = parse("0(vers la Saint-Jean)").unwrap().unwrap();
        let out = to_gedcom(&date);
        assert_eq!(out.value.as_owned(), Some("(vers la Saint-Jean)"));
        // The 5.5.1 date phrase only: no GEDCOM 7.0 PHRASE beside it.
        assert_eq!(out.detail().phrase, None);
    }

    #[test]
    fn a_text_date_is_written_as_gedcom_5_5_1() {
        use oxidged::{GedcomVersion, GedcomWriter};
        let db = crate::database::GwDatabase::read(
            b"fam Doe John 0(vers_la_Saint-Jean) + Roe Jane\n",
            "t.gw",
        )
        .expect("parses");
        let written = GedcomWriter::new()
            .write_to_string(&db.to_gedcom())
            .expect("writes");
        assert!(
            written.contains("2 DATE (vers la Saint-Jean)\n"),
            "{written}"
        );
        assert!(!written.contains("PHRASE"), "{written}");

        // Written as GEDCOM 7.0, the same date is a `PHRASE`: the version is the
        // writer's business, not the conversion's.
        let written = GedcomWriter::new()
            .gedcom_version(GedcomVersion::V7_0)
            .write_to_string(&db.to_gedcom())
            .expect("writes");
        assert!(
            written.contains("2 DATE\n3 PHRASE vers la Saint-Jean\n"),
            "{written}"
        );
    }

    #[test]
    fn every_french_republican_month_has_a_name() {
        for month in 1..=13u8 {
            assert!(month_name(Calendar::French, month).is_some());
            assert!(month_name(Calendar::Hebrew, month).is_some());
        }
        // The Gregorian calendar has only twelve.
        assert!(month_name(Calendar::Gregorian, 12).is_some());
        assert!(month_name(Calendar::Gregorian, 13).is_none());
        assert!(month_name(Calendar::Gregorian, 0).is_none());
    }
}