Korin API

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
On this page

Search results