Korin
Table of Contents
Interfaces
- NodeRule
- A rule for one structure at a time. Rules that look at every line of a record are grouped in
{@see Rule\Nodes}, which walks each record once for all of them.
- Rule
- One conversion rule. It changes one record at a time, so that a conversion can stream: what
it must know about the whole input comes from the Prepass, which runs only when a rule needs it.
- Step
- A conversion between two adjacent versions of the chain 5.5 ↔ 5.5.1 ↔ 7.0, with 5.5.5
attached to 5.5.1 (SPEC section 7): its rules, applied in order to each record.
- GedcomException
- Implemented by every exception the library throws.
- Codec
- Converts between one character encoding and UTF-8.
- Records
- The records a validation goes through, one after another, and those it looks up by xref: of
a document, or of an indexed file, where each record is a document of its own. A record is
known by a key that grows with its place in the file.
- PayloadTypes
- The payload types of one GEDCOM version for ValueRule. A type is one alternative of a
structure's payload: a 7.0 type URI, a 5.x element such as "<SEX_VALUE>", or "Y".
- Rule
Classes
- Context
- What a rule may use besides the record it converts: the options, the prepass, new xrefs and
records, and the loss report. Losses are located in the source document: the document being
converted is a copy of it, so a node keeps its id; a node added during the conversion is
located at its nearest ancestor from the source, a line that could not be parsed at the
structure it is in (the path of a file-level one is empty).
- ConversionResult
- The conversion output and what could not be carried over. The converted document is read
from the output only when it is asked for: writing a conversion needs only output(). The
output is fixed when the conversion ends; editing document() does not change it.
- Converter
- Converts a document to another version along the chain of adjacent versions (SPEC section 7).
- Loss
- One entry of a loss report: data the target version cannot hold as it was. The path and the
line are those of the source document. Messages never quote more than a short fragment.
- LossReport
- Everything a conversion could not carry over as it was, in the order it was found. Empty
when upgrading. The JSON form is that of the corpus loss reports (losses.<version>.json).
- Prepass
- Facts about the whole input that rules need before they see the first record (SPEC section 7,
"Streaming conversion"): from the document here, from a lexer-only pass in convertFile().
- Extensions
- An extension named after a structure of the target version, where the target has that
structure and the source could not write it so, is that structure: it is how the conversion
the other way writes it (7.0 → 5.5.1: _NO, _SDATE, _CREA, _CROP, _SCHMA under HEAD, _PHRASE
under DATE, _FAMC @VOID@; 5.5.1 → 7.0 → 5.5.1: _NOTE and _SOUR under TRAN; 5.5.1 → 5.5: _EMAIL, _FONE, a second REPO of a source as _REPO,
SEX U as _SEX U), and it gets its tag back. Its substructures are already in the target's
form, unless a step before of the chain made it (Context::restored()). The source could not write it so when it has no such structure there, the value does
not fit the source's (an enumeration value it does not list) but fits the target's, the
source allows no more of them there, it is empty (5.5.5 and 7.0 have no empty structure), or (to
7.0) it points to @VOID@ or names its family so (_SLGC with FAMC @VOID@); and its value fits the
target's (a 5.5 _SOUR with a text under NOTE stays: 7.0 NOTE.SOUR is a pointer). Any other extension
(_DATE under BIRT) stays: a program wrote it so on purpose. The last rule of the walk but
Structures: it sees the tags the other rules wrote.
- Nodes
- Walks a record once, in document order, and gives every structure to each of its rules for
that tag in turn; CONC/CONT lines are part of their structure's value and are not visited. A structure
a rule removes is not given to the rules after it, nor are its substructures. An extension a rule
makes a structure again is given to the rules of its new tag, that rule but, from the first: those that
saw it as an extension passed it by, so a rule for every tag sees it twice.
- Payloads
- Whether a structure of a version can have a payload, as far as the conversion between
versions needs to know: a value or none, a pointer or not, and enumeration values; with
$grammars, in 5.x the grammars too (dates, ages, times, 5.5.5 place names), as the validator
checks them. Without, any text fits a grammar: the value rules convert dates and ages.
- SourceLines
- The first rule of every conversion, for what the reader could not read cleanly:
- Structures
- The structures the target version does not have where they stand:
- Spellings
- Values 4.0 writes in words (GEDCOM 4.0, chapter 5), in the form 5.5 has for them:
- Associations
- 5.5 ASSO names the type of the record it points to, which in 5.5.1 is always an individual:
TYPE INDI, its first substructure.
- Events
- The value of EVEN, which 5.5 does not have: 5.5 describes the event with TYPE
(<EVENT_DESCRIPTOR>, the element 5.5.1 writes in the value), so the value becomes its TYPE;
an EVEN with a TYPE already keeps it in a NOTE (KL3004 either way).
- Media
- Media in the 5.5 structure, where FORM belongs to the object:
- Addresses
- 5.5.5 ADDR has no value: the address is in ADR1–ADR3, CITY, STAE, POST and CTRY. The lines of
the value (at most three) are ADR1–ADR3: ADR lines that repeat them are kept, missing ones
are added, and the value is removed. So is a value the conversion back would make from CITY,
STAE, POST and CTRY. Any other value (more lines, an empty one, a line other than its ADR)
moves to a first substructure _ADDR (KL3001), from which the conversion back restores it.
- FileHeader
- 5.5.5 requires HEAD.GEDC.FORM LINEAGE-LINKED with a VERS of its own, 5.5.5: FORM is added
after GEDC.VERS when missing, and its VERS is set. HEAD.CHAR and GEDC.VERS are set by the
converter.
- InlineRecords
- 5.5.5 has no inline media or source: OBJE and SOUR substructures point to records. Each one
without a pointer becomes a new record @X<n>@ (before TRLR, in order of appearance), and the
substructure points to it:
- Spellings
- The 5.5.5 spelling of 5.5.1 values its stricter grammars reject (for Rule\Values): ages with
a space after < and > and without leading zeroes or zero parts ("<01y 0m" → "< 1y"), months
past 11 in years ("42m" → "3y 6m"; days stay, a month has no fixed length), dates
with days without a leading zero and years of at least 3 digits ("05 JAN 50" → "5 JAN 050"),
times with hours without one and two-digit fractions ("09:05:00.5" → "9:05:00.50"), place
names with ", " between parts. Null when there is none: an age of 0y, a longer fraction.
- Submitters
- A 5.5.5 file has exactly one SUBM record, directly after HEAD, and HEAD.SUBM points to it.
- Ages
- Ages by the 7.0 grammar: lowercase units in the order y m w d, one space between parts and
after "<" or ">" ("<0Y" → "< 0y", "11m 99y" → "99y 11m"); a number without a unit is years,
as most 5.5.1 programs read it. CHILD, INFANT and STILLBORN become "< 8y", "< 1y" and "0y"
with the word as PHRASE; anything else becomes PHRASE of an empty age.
- Dates
- Dates by the 7.0 grammar (specification section 2.6 and appendix A), uppercase:
- Enumerations
- Enumeration values in 7.0 case and spelling (birth → BIRTH, PRE-1970 → PRE_1970, DNS/CAN →
DNS_CAN). A value the 7.0 set does not have becomes OTHER with the value as PHRASE where 7.0
has both ("1 NAME … 2 TYPE Screen" → TYPE OTHER, PHRASE Screen), and stays as it is
elsewhere; the event type a citation is from, whose set has no OTHER, is EVEN, the generic
event, with the value as PHRASE ("2 EVEN Census of Galicia" → EVEN EVEN, PHRASE Census of
Galicia). A 5.5.1 role description "(text)" is OTHER with PHRASE text.
- Events
- 7.0 EVEN of an individual or a family requires TYPE, 5.5.1 does not: an EVEN with a value
("Moved to Osaka", which describes the event) and no TYPE gets the value as its first TYPE.
- FileHeader
- HEAD.CHAR, HEAD.GEDC.FORM and HEAD.FILE describe the file, not its data, and 7.0 has none of
them (a 7.0 file is always UTF-8 and lineage-linked, and its name is whatever it is saved
as): they are removed without a loss (SPEC section 7, "Source housekeeping structures").
- Identifiers
- AFN, RFN and RIN become EXID with the TYPE the 7.0 term files define for the conversion:
- InlineRecords
- 7.0 has no inline media or source: OBJE and SOUR substructures point to records. Each one
without a pointer becomes a new record @X<n>@ (before TRLR, in order of appearance), and
the substructure points to it:
- Languages
- Languages as BCP 47 tags: the 5.5.1 language names (case-insensitive) map to their tags as
in the gedcom7code converter, except Dogri, which is "doi" (it writes "dgr", Dogrib). A value
that already is a tag of a 2- or 3-letter language ("uk", "en-GB") stays; any other becomes
"und" with the value in an extension _PHRASE (7.0 LANG has no PHRASE), as gedcom7code does;
HEAD.SCHMA documents it (Schema).
- Media
- Media files by the 7.0 types:
- NoteRecords
- The 5.5.1 NOTE record is the 7.0 shared note SNOTE, and a NOTE that points to it (in 5.5.1 a
NOTE pointer always points to a NOTE record) is SNOTE too, where 7.0 has SNOTE: under a TRAN
(5.5.1 ROMN, FONE) it stays NOTE for the structures rule, which keeps it as _NOTE. NOTE with
text stays NOTE.
- Occurrences
- An event with neither a value nor substructures (1 BURI) says that the event occurred, which
7.0 writes as Y: it has no structure without both.
- Repositories
- 5.5.1 REPO of a source without a pointer (a repository known only by its call numbers) is
REPO @VOID@ in 7.0, which requires the pointer.
- Schema
- HEAD.SCHMA documents the extension tags with a standard meaning that the conversion writes:
"_PHRASE https://gedcom.io/terms/v7/PHRASE" (a relocated PHRASE) when a LANG of the input
has no BCP 47 tag (Languages). Whether one does comes from the prepass, so that HEAD is
complete when it is converted, as convertFile() needs. A tag the input already has is left
out, as its meaning there is not known; an existing SCHMA gets the TAG added (unless it has
one for _PHRASE already), an input without HEAD a HEAD. Extensions of
the input and those without a standard URI (_SUBN, _TYPE) are not documented: Korin does not
guess or invent what they mean.
- Sexes
- SEX U with _SEX X, which the conversion to 5.5.1 writes for SEX X, is SEX X (to 5.5.5 also
_SEX N, SEX N).
- Submissions
- 7.0 has no SUBN (the LDS submission record). Its substructures move to HEAD._SUBN, one per
SUBN record, so a conversion back can restore it; the record and HEAD.SUBN, the pointer to
it, are removed. Done when HEAD is converted, with the SUBN records from the prepass: a SUBN
record may be anywhere, HEAD is first. A SUBN record an earlier step of a route made
(7.0 → 5.5.1 → 5.5.5) moves when it is converted, its values written anew.
- TextValues
- Text values by the 7.0 line rules: CONC lines are joined (7.0 has no CONC and no line length
limit; CONT stays), and "@" is doubled only at the start of a line instead of everywhere
("with @@ inside" → "with @ inside"). "@#…@" sequences are kept as text ("@#DJULIAN@ x" →
"@@#DJULIAN@ x"); the date rule, which runs after this one, reads calendar escapes in DATE
from that text. Rules after this one read values by the 7.0 rules (Context::value()).
- Translations
- FONE and ROMN, the phonetic and romanized variations of a name or place, become TRAN with a
BCP 47 LANG in place of their TYPE: the types 5.5.1 names map to a language and script
(hangul → ko-Hang, kana → ja-Kana, romaji → ja-Latn, pinyin → zh-Latn-pinyin, wadegiles →
zh-Latn-wadegile; a FONE type only for FONE, a ROMN type only for ROMN); any other type keeps
its value as _TYPE, with LANG und (FONE) or und-Latn (ROMN, a romanization is in Latin
script). An empty TYPE is dropped.
- Uids
- The vendor tag _UID is the 7.0 UID. Its value is kept as it is: the UID term says an existing
identifier "should be used without modification", so a PAF-style UUID with a checksum stays.
- Xrefs
- Xrefs and pointers. 7.0 allows only uppercase letters, digits and "_" in an xref and
reserves @VOID@: a record with any other xref (@fam 1@, @note@, @VOID@) gets @X<n>@, the next
free n in document order, and every pointer to it follows. A pointer to a record that does
not exist (compared case-sensitively: @test@ is not @TEST@) becomes the null pointer @VOID@,
except under NOTE: there it is more likely text written without "@@" escaping (@Smith family@)
and stays text (NOTE @@Smith family@), so nothing is lost, and in an extension (_IN @B1@),
which 7.0 leaves to the extension's definition. Needs the prepass: a pointer may come before the record it points to.
- Addresses
- 5.5.1 ADDR has a value, the address as lines; 5.5.5 has none. The value is the first
substructure _ADDR, where the conversion to 5.5.5 keeps a value it cannot write, or else the
lines ADR1–ADR3, or else CITY, STAE POST and CTRY on one line ("Kyiv, 01001, Ukraine"). An
address with none of them stays without a value.
- Dates
- 5.5.5 writes years with at least 3 digits ("050"), 5.5.1 and 7.0 as they are ("50"): the
zeroes go, so a date converted to 5.5.5 and back is the date it was.
- FileHeader
- HEAD.GEDC.FORM.VERS, the version 5.5.5 requires under FORM, is not 5.5.1: it is removed, like
GEDC.VERS it is set by the conversion. A 5.5.5 file has one SUBM record; the others, which
the conversion to 5.5.5 keeps as _SUBM records, are SUBM records again.
- Spellings
- The 5.5.1 spelling of 5.5.5 values (for Rule\Values): ages without the space after < and >
("< 1y" → "<1y"), BCE and BC as B.C. ("1000 BCE" → "1000 B.C."). Null when there is none:
5.5.1 has no day and month without a year ("5 MAR"). years() takes back the zeroes 5.5.5
puts before short years, for every date.
- Associations
- ASSO names the type of the record it points to in 5.5 (TYPE); 5.5.1 associates individuals
only. TYPE INDI goes; an association with another record becomes an extension (KL2001).
- Media
- Media in the 5.5.1 structure, where FORM belongs to a FILE:
- Ages
- Ages by the 5.5.1 grammar: no space after "<" or ">" ("< 8y" → "<8y"); a PHRASE that is the
5.5.1 age it came from replaces the value ("< 8y" + PHRASE CHILD → CHILD). Every value is one
that converts up to the same age and PHRASE again: another PHRASE stays for the structures
rule, and an age 5.5.1 cannot write is kept as an extension, _AGE (KL3001): weeks ("2w"), and
a PHRASE alone that is no age ("AGE" + PHRASE Zero; "AGE Zero" is not a 5.5.1 age).
- Aliases
- A record whose extension tag HEAD.SCHMA documents as a standard record (TAG _USER
https://gedcom.io/terms/v7/record-SUBM) is that record in 7.0, and gets the standard tag in
5.5.1, which has no SCHMA: _USER → SUBM. HEAD is converted before the records after it, so its
SCHMA may be _SCHMA already.
- Dates
- Dates by the 5.5.1 grammar: calendar names become escapes (JULIAN → @#DJULIAN@, FRENCH_R →
@#DFRENCH R@, _ROMAN 24 _IUL 15 → @#DROMAN@ 24 IUL 15), BCE → B.C. A PHRASE joins the date as
the 5.5.1 date it came from when converting up: the PHRASE itself when it is that date
(DATE 30 JAN 1649 + PHRASE 30 JAN 1648/49 → 30 JAN 1648/49), otherwise "INT date (phrase)",
or "(phrase)" without a date (the PHRASE as it is when it has parentheses).
- Enumerations
- Enumeration values in 5.5.1 case and spelling (BIRTH → birth, PRE_1970 → PRE-1970, DNS_CAN →
DNS/CAN); OTHER with a PHRASE → the PHRASE (TYPE OTHER + PHRASE Screen → Screen), and a role
description in parentheses where 5.5.1 has one (ROLE OTHER + PHRASE midwife → (midwife)).
- Events
- The TYPE the conversion to 7.0 gives an EVEN without one, its value again
(EVEN Moved to Osaka + TYPE Moved to Osaka), is removed: 5.5.1 does not require it. The value
of RESI, which 5.5.1 writes without one, is a NOTE of it (KL3005).
- FileHeader
- 5.5.1 requires HEAD.GEDC.FORM, which 7.0 dropped (a 7.0 file is always lineage-linked):
GEDC.FORM LINEAGE-LINKED is added after GEDC.VERS. HEAD.CHAR and GEDC.VERS are set by the
converter.
- Identifiers
- EXID goes back to the 5.5.1 tag its TYPE names, where the record has that tag in 5.5.1 and
converting up again gives the same EXID:
- Languages
- HEAD.LANG and SUBM.LANG, the LANG structures 5.5.1 has, take 5.5.1 language names: uk →
Ukrainian, "und" with _PHRASE (a name converting up did not know) → that name. A tag 5.5.1
has no name for (en-GB, the region) is kept as an extension, _LANG (KL3001), so that nothing
is lost and converting up gives it back. A LANG beyond the three 5.5.1 allows in a SUBM
keeps its tag: the structures rule keeps it as _LANG in its 7.0 form (KL2002).
- Media
- Media files by the 5.5.1 types:
- NoteRecords
- The 7.0 shared note SNOTE is the 5.5.1 NOTE record, and the SNOTE that points to it is a
NOTE pointer, where 5.5.1 has a NOTE that can be one: an SNOTE under SOUR.DATA.EVEN.PLAC, or
of HEAD (whose NOTE is text only), stays for the structures rule, which keeps it as _SNOTE.
- Sexes
- SEX X ("does not fit the typical definition of only Male or only Female") and 5.5.5 SEX N
("not recorded") have no 5.5.1 value: they become SEX U with the value in _SEX X, or SEX U
alone under LossPolicy::DropWithReport (KL3002). Converting up gives SEX X back.
- Submissions
- HEAD._SUBN, where the conversion to 7.0 keeps a 5.5.1 SUBN record, becomes a SUBN record
again (before TRLR, xref @X<n>@) with its substructures, and HEAD.SUBN points to the first
one in its place. Needs the prepass: the new xref must not be one the input has.
- TextValues
- Text values by the 5.5.1 line rules: every "@" of a text is doubled ("with @ inside" →
"with @@ inside"), not only a leading one; "@#DJULIAN@" in a 7.0 text is text, so it is
"@@#DJULIAN@@". Long lines are split into CONC when the output is written. Rules after this
one read values by the 5.5.1 rules (Context::value()).
- Times
- Times by the 5.5.1 grammar, which has no time zone: a 7.0 time in UTC ("15:43:20Z") is kept as
an extension, _TIME (KL3001); converting up gives it back.
- Translations
- TRAN of a name or place in a language and script 5.5.1 has a variation type for becomes its
phonetic or romanized variation, LANG becoming TYPE: ko-Hang → FONE hangul, ja-Kana → FONE
kana, ja-Latn → ROMN romaji, zh-Latn-pinyin → ROMN pinyin, zh-Latn-wadegile → ROMN wadegiles;
LANG und and und-Latn, which converting up writes for another type, become FONE and ROMN with
that type (_TYPE). Any other TRAN is left to the structures rule (_TRAN).
- Uids
- The 7.0 UID is the vendor tag _UID, which 5.5.1 programs write; its value is kept.
- Values
- Values between 5.x versions: an enumeration value the target does not list is spelled as the
target spells it where it has one (5.5 FORM jpeg ↔ 5.5.1 jpg), and otherwise, like a missing
pointer the target requires (5.5.1 REPO without one → 5.5), makes the structure an extension
with its tag and value (5.5.1 SEX U → 5.5 _SEX U), or drops it under
LossPolicy::DropWithReport (KL3001); converting back gives the structure back (Extensions).
- V40ToV55
- 4.0 → 5.5 (SPEC section 7, best effort). 4.0 has a dictionary of tags but no grammar: values
in words take their 5.5 form (Spellings), and what 5.5 has no structure for (HEAL, a tag
where 5.5 does not have it) becomes an extension, reported (KL2001). There is no step back:
4.0 is read only.
- V551ToV55
- 5.5.1 → 5.5 (SPEC section 7). Nothing is dropped by default: what 5.5 has no structure for
(EMAIL, FAX, WWW, MAP, FONE, ROMN, the FILE of a media record) becomes an extension and a
loss report entry.
- V551ToV555
- 5.5.1 → 5.5.5 (SPEC section 7). 5.5.5 is 5.5.1 made strict: inline sources and media become
records, SUBN moves into HEAD._SUBN, values follow the stricter grammars; what 5.5.5 has no
structure for (LDS ordinances, RESN, ALIA, AFN, the value of ADDR) becomes an extension and a
loss report entry.
- V551ToV70
- 5.5.1 → 7.0, following the FamilySearch migration guide (SPEC section 7). Upgrading is
lossless: what 7.0 has no structure for stays an extension.
- V555ToV551
- 5.5.5 → 5.5.1 (SPEC section 7): ADDR gets its value back, HEAD._SUBN becomes a SUBN record,
SEX X and N become SEX U with _SEX, and values 5.5.1 spells otherwise are respelled; what
5.5.1 has no value for (a date without a year) becomes an extension and a loss report entry.
- V55ToV551
- 5.5 → 5.5.1 (SPEC section 7). Upgrading keeps everything: what 5.5.1 has no structure for
(BLOB, the AGE of a family event, a NOTE of a media link) becomes an extension, reported.
- V70ToV551
- 7.0 → 5.5.1, the reverse of the FamilySearch migration guide (SPEC section 7). Nothing is
dropped by default: what 5.5.1 has no structure for becomes an extension and a loss report
entry.
- Steps
- The conversion steps of the library, one per direction between adjacent versions.
- ConvertOptions
- Diagnostic
- A problem found while reading or validating. Codes are stable within a major version
and documented in docs/diagnostics.md. Messages never quote more than a short fragment
of the file: trees hold personal data and diagnostics end up in logs.
- ConversionException
- A conversion between versions that is not supported, or a loss under LossPolicy::Fail.
- DetachedNodeException
- The node was removed from its document.
- GedzipException
- A GEDZIP archive that cannot be read or written: not a ZIP, no gedcom.ged, a limit exceeded, no ext-zip.
- InvalidPathException
- A node path does not follow the path grammar.
- InvalidValueException
- A value that does not follow the grammar of a version, or one the version cannot write.
- IoException
- A file or stream could not be read or written.
- ParseException
- Malformed input in strict mode, or input that cannot be read at all.
- ReadOnlyException
- A change to a document that is read only: a record of {@see \Korin\Gedcom\Gedcom::open()}; edit a copy.
- RequiresDocumentException
- A view of a streamed record asked for another record: read the file with read() or open().
- UnencodableCharacterException
- A character has no representation in the target encoding.
- UnsupportedVersionException
- A version the library reads but does not write (GEDCOM 4.0): convert the document to 5.5 or later.
- Dialects
- Documented mistakes of programs, which a reader corrects to read their files as they are
(SPEC section 3; docs/dialects.md). Each is reported (KV1010) and none changes a line: it
only decides the encoding or version the file is read in. {@see \Korin\Gedcom\ReadOptions::withDialects()}
turns them off.
- SourceSystem
- The program that wrote a file, from HEAD.SOUR: the system identifier, its VERS and NAME
(5.x and 7.0 alike), and the {@see Program} when the identifier is known. The version is
HEAD.SOUR.VERS, or the number in the identifier when there is no VERS ("PAF 2.31").
- Gedcom
- Entry point for common tasks; the classes behind it can be injected directly.
- Archive
- A GEDZIP archive that was read ({@see \Korin\Gedcom\Gedcom::readGedzip()}): its gedcom.ged as
a document, and its media, read from the archive when asked for, never extracted to disk.
- EntryName
- Names of archive entries that are safe to use: relative paths with "/" between segments,
none of them "." or "..", no backslash, drive letter or control character. Anything else
could write or read outside a directory the archive is extracted to (zip-slip).
- GedzipReader
- Reads a GEDZIP archive (GEDCOM 7.0 section 3.6): gedcom.ged at its root, the media its FILE
references name. The archive is checked before anything is decompressed: the sizes of the
entries against the limits of {@see ReadOptions} (zip bombs), their names (zip-slip). The
size of gedcom.ged is checked again as it is read, as the directory can lie.
- GedzipWriter
- Writes a GEDZIP archive: the document as gedcom.ged, first, and the media under the names
its FILE references use. The archive is written to a temporary file next to the target and
renamed when complete, so a failure leaves no half-written archive.
- AnselCodec
- ANSEL (ANSI/NISO Z39.47) with the GEDCOM 5.5 additions (empty and black box, midline e and o,
es zet; "LDS extensions"). Combining marks precede the base letter in ANSEL and follow it in
Unicode; decoded text is NFC.
- AsciiCodec
- Codecs
- Shared, stateless codec instances per encoding.
- SingleByteCodec
- Code pages whose bytes 0x00–0x7F are ASCII and 0x80–0xFF come from a table.
- Utf16Codec
- Utf8
- UTF-8 helpers in pure PHP, so codecs work without ext-mbstring or ext-intl.
- Utf8Codec
- Detection
- EncodingDetector
- Order: explicit encoding → BOM → UTF-16 byte pattern → HEAD.CHAR checked against content.
- LineSplitter
- Splits raw bytes into lines without decoding them, so every line keeps its exact
original bytes and terminator (CR, LF, CRLF, or none on the last line).
- Age
- An age at an event: a duration in years, months, weeks and days, or a 5.x word (CHILD,
INFANT, STILLBORN), with "<" or ">" before it, and a phrase. The same value object for every version:
{@see self::parse()} reads the grammar of a version, {@see self::toGedcom()} writes it. The
phrase is the 7.0 PHRASE substructure; 5.x has none.
- Coordinates
- The MAP of a place: LATI and LONG as degrees, north and east positive ("N50.45", "E30.52").
- Date
- One calendar date of a {@see GedcomDate}: a year, optionally a month and a day, in a
calendar. Calendars, months and epochs are GEDCOM tags, written the same for every version:
the 5.x escape "@#DFRENCH R@" is FRENCH_R, "B.C." is the epoch BCE. A 7.0 extension calendar,
month or epoch keeps its tag ("_MAYA"). A dual year ("1648/49", 5.x only) keeps both years.
- Event
- A live view of an event of an individual or a family (BIRT, MARR, EVEN …): its date, place,
age and type. Dates and ages are read and written by the rules of the document's version: in
7.0 their phrase is the PHRASE substructure, in 5.x part of the value.
- Family
- A live view of a FAM record: partners, children and events. Linking an individual also adds
the pointer back (FAMS, FAMC), so the links stay mutual.
- GedcomDate
- A date value: a kind (a date, a range, a period, an approximation or none), its dates and a
phrase. The same value object for every version: {@see self::parse()} reads the grammar of a
version, {@see self::toGedcom()} writes it. In 7.0 the phrase is not part of the value but the
PHRASE substructure; in 5.x it is "INT date (phrase)" or "(phrase)".
- Grammars
- The validator's grammars for the values of the model: a value object accepts exactly what
the validator finds valid, without warnings.
- Individual
- A live view of an INDI record: names, sex, events, and the families it is a child or a
spouse in. Values that are not valid for the version read as null; their text stays on
{@see node()}.
- MediaFile
- A live view of a FILE of a media object: path or URL, format and title.
- MediaObject
- A live view of an OBJE record: its files and title.
- PersonalName
- The value of a personal NAME: the text before the surname, the surname between slashes and
the text after it ("Анна /Коваль/", "Ivan /Petrenko/ Jr."). The same in every version. The
name pieces (GIVN, SURN, NPFX and the others) are substructures, not part of the value.
- Place
- The value of a PLAC: its jurisdictions from the smallest to the largest, "Полтава, Україна".
- RecordView
- A live view of a record: it reads from and writes to the tree, so nothing the view does not
know about is lost. Records it points to are looked up in the file it belongs to; a view of a
streamed record has none and throws {@see RequiresDocumentException} when asked for them.
- Repository
- A live view of a REPO record: an archive or library that holds sources.
- SharedNote
- A live view of a note record: SNOTE in 7.0, NOTE in 5.x; its text is the record's value.
- Source
- A live view of a SOUR record: title, author, publication, abbreviation, text and repositories.
- Submitter
- A live view of a SUBM record: who contributed the data.
- ReadOptions
- Cardinality
- How many times a substructure may occur, e.g. {0:1}, {1:M}.
- JulianDays
- Gregorian and Julian dates as Julian Day Numbers, for comparing dates: shared by the model
({@see \Korin\Gedcom\Model\Date::days()}) and the plausibility checks.
- Profile
- The rules of one GEDCOM version as data: which structures exist, where they may appear and
how often, their payload types, enumerations and calendars. Compiled from spec/ into
resources/profiles by bin/generate-profiles.php.
- Structure
- One structure type of a profile, identified by its URI: the same tag can mean different
structures in different places (INDI.NAME and REPO.NAME).
- Substructure
- A structure as it may appear under a particular superstructure (or at the top level).
- Document
- Lossless, mutable GEDCOM tree. Nodes live in parallel arrays indexed by a stable id
(0 is the virtual root whose children are the records); {@see Node} objects are thin
views created on demand. Unmodified lines keep their original bytes, so preserve-mode
writing reproduces the input exactly. Removed nodes become tombstones and keep their id.
- Escaping
- "@" escaping of line values. 5.x doubles every "@" except inside "@#…@" escape
sequences (calendar escapes such as "@#DJULIAN@"); 7.0 doubles only a leading "@".
- IndexedDocument
- A file opened for reading without its tree in memory (SPEC section 6, `open()`): an index of
where each record starts, and records parsed from the file when they are asked for, the
last ones kept in a cache. Building the index parses no record but the first and HEAD.
- Node
- Live view of one line and its substructures. CONC/CONT lines are not children here:
they are joined into {@see value()}. Any access after the node was removed throws
{@see \Korin\Gedcom\Exception\DetachedNodeException}.
- Parser
- Builds a lossless {@see Document} from raw bytes.
- Path
- Node path, e.g. "HEAD/GEDC/VERS" or "@I1@/NAME[0]/SURN". The first segment is HEAD,
TRLR or a record xref; each next one is a tag with an optional 0-based index among
siblings with that tag. Without an index the tag must be unique among its siblings.
- Record
- One record of a {@see RecordStream}: a document of its own whose only record it is, so
nothing else of the file is in memory. Lines keep the numbers they have in the file;
writing the document in preserve mode gives the record's original bytes (the first record
of a file with a BOM starts with it).
- RecordReader
- Splits a file read in chunks into the bytes of its records, without parsing them: where
{@see Parser} would start a record, so each piece parses as that record. Lines before the
first GEDCOM line are pieces of their own, as the parser makes them records. The encoding is
detected on the first 64 KB, as {@see EncodingDetector} does on a whole file.
- RecordStream
- A file read one {@see Record} at a time, in memory that does not grow with the file
(SPEC section 6, read modes). Records are parsed as {@see Parser} parses the whole file:
the same nodes, values and line diagnostics, which each record's document holds. The
encoding is detected from the BOM, HEAD.CHAR and the first 64 KB; bytes later in the file
that are invalid in it are reported on their line (KV1003), not decoded again.
- DocumentRecords
- The records of a document; a key is the record's node id.
- IndexedRecords
- The records of an indexed file; a key is the record's number. Going through them reads the
file once; a record looked up is read from the file unless it is among the cached ones.
- DateGrammar
- The GEDCOM 7.0 date types DateValue, DatePeriod and DateExact (specification section 2.6 and
appendix A). Months and epochs come from the profile's calendars; month lengths are known here
for the four standard calendars. Calendars and months that HEAD.SCHMA defines as standard ones
are those ({@see Schema}); the months, epochs and days of other extension calendars are not known,
so not checked.
- DateGrammar5
- The GEDCOM 5.x date elements DATE_VALUE, DATE_PERIOD and DATE_EXACT (5.5.1 pages 45-48, 65):
calendar escapes such as "@#DJULIAN@", "B.C." after any year (5.5: "A (B.C.) appended to the
<YEAR>"; 5.5.1 writes it only after a lone year, but "MAR 44 B.C." means the same in both),
dual years ("1699/00") in the Gregorian calendar, date phrases in parentheses. Keywords and months are
case-insensitive. @#DROMAN@ and @#DUNKNOWN@ are "for future definition": any day, word and
year is accepted.
- DateRange
- The days a date value can mean, as Julian Day Numbers, for comparing dates: "1907" is
1 JAN to 31 DEC 1907, "BEF 1907" has no first day, "BET 1900 AND 1910" spans both years.
- FileRule
- 5.5.5 rules for the file as a whole that its grammar does not express: the file starts with
a byte order mark (KV1104, a warning: the BOM carries no data), and the SUBM record directly
follows HEAD (KV2004).
- Grammar5
- Grammars of the GEDCOM 5.x primitive elements that spec/<version>/primitives.yaml names; dates
are in DateGrammar5. Keywords and labels are case-insensitive, as in the gedcom7code tests.
- PayloadGrammar
- Grammars of the GEDCOM 7.0 data types (specification chapter 2), as regular expressions
with linear complexity. Dates are checked by DateGrammar.
- Payloads5
- GEDCOM 5.x payload types: the primitive elements of the profile ("<SEX_VALUE>") as
enumerations or grammars (Grammar5, DateGrammar5); other elements are text. Enumerations
are case-insensitive. An empty payload needs "<NULL>" among the alternatives. A payload
written without angle brackets is a literal ("Y", 5.5.5 "LINEAGE-LINKED").
- Payloads7
- GEDCOM 7.0 payload types: PayloadGrammar and DateGrammar, enumerations from the profile.
- PlausibilityRule
- Level 5, optional: warnings about data that is valid but cannot be true. A birth after the
death (KV5001), a child born before a parent (KV5002), an individual who is their own ancestor
(KV5003). Dates are compared as DateRange: only when the conflict is certain. The first BIRT
and DEAT with such a date count. Parents are HUSB and WIFE of the families an individual is a
child of, by FAM.CHIL or INDI.FAMC.
- ReferenceRule
- Level 4: pointers and xrefs: dangling pointers (KV4001), duplicate xrefs (KV4002), the type of
the record a pointer must point to (KV4003, from the profile). Family links must be mutual (KV4004): INDI.FAMC ↔ FAM.CHIL, INDI.FAMS ↔ FAM.HUSB/WIFE.
- Schema
- The documented extension tags of a 7.0 HEAD.SCHMA that stand for a standard term: a record
type, a calendar or a month. A tag definition makes its tag an abbreviation for the URI
(specification chapter 1, "Extension tags"), so `_USER` defined as
https://gedcom.io/terms/v7/record-SUBM is a SUBM record for the pointers to it, and a date in
`_CAL`, defined as https://gedcom.io/terms/v7/cal-FRENCH_R, is a French Republican date. The
contents of such a record are an extension's and are not checked.
- StructureRule
- Level 2: every standard tag is allowed where it stands, and substructures occur as often as
the profile says (KV2001–KV2003); 7.0 structures the specification deprecates are warnings
(KV2005, values in {@see Payloads7}). 5.x citations and media links are checked by their form
(Structure::form()), 7.0 substructures of which one is allowed by Profile::choices(). Extension tags ("_X") and everything under them are not
checked; HEAD first and TRLR last are syntax checks (KV1004–KV1006).
- ValueRule
- Level 3: payloads of standard structures against the profile's payload types (KV3001–KV3010).
- ValidationOptions
- Which diagnostics a validation reports and how severe they are.
- ValidationReport
- Diagnostics of one validation, in document order.
- Validator
- Checks a document, or an indexed file, against the profile of its version: every rule sees
the records one at a time, in order. The report starts with the syntax
diagnostics found while reading (KV1xxx); the document itself is never changed. The
plausibility checks (KV5xxx) run only when the options ask for them.
- WriteOptions
- ConcSplitter
- Splits an escaped 5.x line value into CONC parts. Splits fall only between grapheme clusters,
never inside "@@" or an "@#…@" escape, and never next to a space (5.5.1: "values that are
split for a CONC tag must always be split at a non-space"). Parts are as long as allowed.
- Writer
Enums
- LossPolicy
- What a conversion does with data the target version has no structure for.
- StoredAs
- How the data of a loss report entry was kept in the output.
- Program
- Programs known by the system identifier they write in HEAD.SOUR. Identifiers are those of
Tamura Jones, "GEDCOM System Identifiers" (https://www.tamurajones.net/GEDCOMSystemIdentifiers.xhtml);
they are compared without case, and a program may write several (HEREDIS PC2018, PAF 2.31).
- Encoding
- AgeBound
- "<" or ">" before an age: younger or older than the duration.
- DateKind
- What a {@see GedcomDate} says about its dates.
- Sex
- INDI.SEX.
- Severity
- Version
- WriteMode