Class for parsing GEDCOM 5.5 files and creating a {@link Gedcom} structure from them.
General usage is as follows:
GedcomParser objectGedcomParser.load() method (in one of its various forms) to parse a file/streamgedcom property to access the parsed data It is highly recommended that after calling the GedcomParser.load() method, the user check the {@link GedcomParser#errors} and {@link GedcomParser#warnings} collections to see if anything problematic wasencountered in the data while parsing. Most commonly, the warnings collection will have information about tags from GEDCOM 5.5.1 that were specified in a file that was designated as a GEDCOM 5.5 file. When this occurs, the data is loaded, but will not be able to be written by {@link org.gedcom4j.writer.GedcomWriter} until theversion number in the gedcomVersion field of {@link Gedcom#header} is updated to{@link SupportedVersion#V5_5_1}, or the 5.5.1-specific data is cleared from the data.
The parser takes a "forgiving" approach where it tries to load as much data as possible, including 5.5.1 data in a file that says it's in 5.5 format, and vice-versa. However, when it finds inconsistencies, it will add messages to the warnings and errors collections. Most of these messages indicate that the data was loaded, even though it was incorrect, and the data will need to be corrected before it can be written.
The parser makes the assumption that if the version of GEDCOM used is explicitly specified in the file header, that the rest of the data in the file should conform to that spec. For example, if the file header says the file is in 5.5 format (i.e., has a VERS 5.5 tag), then it will generate warnings if the new 5.5.1 tags (e.g., EMAIL) are encountered elsewhere, but will load the data anyway. If no version is specified, the 5.5.1 format is assumed as a default.
This approach was selected based on the presumption that most of the uses of GEDCOM4J will be to read GEDCOM files rather than to write them, so this provides that use case with the lowest friction.
@author frizbog1 | |