Syntax
Table of Contents
Classes
- 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.