Provided by: libgedcom-perl_1.20-1_all bug


       Gedcom - a module to manipulate Gedcom genealogy files

       Version 1.20 - 17th September 2017


         use Gedcom;

         my $ged = Gedcom->new;
         my $ged = Gedcom->new($gedcom_file);
         my $ged = Gedcom->new(grammar_version => "5.5.1",
                               gedcom_file     => $gedcom_file,
                               read_only       => 1,
                               callback        => $cb);
         my $ged = Gedcom->new(grammar_file => "gedcom-5.5.grammar",
                               gedcom_file  => $gedcom_file);

         return unless $ged->validate;
         my $xref = $self->resolve_xref($value);
         my %xrefs = $ged->renumber;
         $ged->write($new_gedcom_file, $flush);
         my @individuals = $ged->individuals;
         my @families = $ged->families;
         my $me = $ged->get_individual("Paul Johnson");
         my $xref = $ged->next_xref("I");
         my $record = $ged->add_header;
         my $source = $ged->get_source("S1");


       Copyright 1998-2013, Paul Johnson (

       This software is free.  It is licensed under the same terms as Perl itself.

       The latest version of this software should be available from my homepage:

       This module provides for manipulation of Gedcom files.  Gedcom is a format for storing
       genealogical information designed by The Church of Jesus Christ of Latter-Day Saints
       (  Information about Gedcom is available as a zip file at  Unfortunately, this is only usable if
       you can access a PC running Windows of some description.  Part of the reason I wrote this
       module is because I don't do that.  Well, I didn't.  I can now although I prefer not to...


         Perl 5.005 or later
         ActivePerl5 Build Number 520 or later has been reported to work

       Optional Modules:
       to work with dates     to use soundex to use lines2perl             to use the LifeLines function roman from lines2perl

       The Gedcom format is specified in a grammar file (gedcom-5.5.grammar). parses
       the grammar which is then used to validate and allow manipulation of the Gedcom file.  I
       have only used with version 5.5 of the Gedcom grammar, which I had to modify
       slightly to correct a few errors.  The advantage of this approach is that should
       be useful if the Gedcom grammar is ever updated.  It also made the software easier to
       write, and probably more dependable too.  I suppose this is the virtue of laziness shining

       The vice of laziness is also shining brightly - I need to document how to use this module
       in much greater detail.  This is happening - this release has more documentation than the
       previous ones - but if you would like information feel free to send me mail or better
       still, ask on the mailing list.

       This module provides some functions which work over the entire Gedcom file, such as
       reformatting dates, renumbering entries and ordering the entries.  It also allows access
       to individuals, and then to relations of individuals, for example sons, siblings, spouse,
       parents and so forth.

       The distribution includes a lines2perl program to convert LifeLines programs to Perl.  The
       program works, but it has a few rough edges, and some missing functionality.  I'll be
       working on it when it hits the top of my TODO list.

       There is now an option for read only access to the gedcom file.  Actually, this doesn't
       stop you changing or writing the file, but it does parse the gedcom file lazily, meaning
       that only those portions of the gedcom file which are needed will be read.  This can
       provide a substantial saving of time and memory providing that not too much of the gedcom
       file is read.  If you are going to read the whole gedcom file, this mode is less efficient
       unless you do some manual housekeeping.

       Note that this is still considered beta software - caveat emptor.

       Should you find this software useful, or if you make changes to it, or if you would like
       me to make changes to it, please send me mail.  I would like to have some sort of an idea
       of the use this software is getting.  Apart from being of interest to me, this will guide
       my decisions when I feel the need to make changes to the interface.

       There is a low volume mailing list available for discussing the use of Perl in conjunction
       with genealogical work.  This is an appropriate forum for discussing and if you
       use or are interested in this module I would encourage you to join the list.  To subscribe
       send an empty message to

       To store my genealogy I wrote a syntax file (gedcom.vim) and used vim (
       to enter the data, and to validate and manipulate it.  I find this to be a nice


       This space is reserved for something of a tutorial.  If you learn best by looking at
       examples, take a look at the test directory, t.  The most simple test is birthdates.t.

       The first thing to do is to read in the Gedcom file.  At its most simple, this will
       involve a statement such as

         my $ged = Gedcom->new($gedcom_file);

       It is now possible to access the records within the gedcom file.  Each individual and
       family is a record.  Records can contain other records.  For example, an individual is a
       record.  The birth information is a sub-record of the individual, and the date of birth is
       a sub-record of the birth record.

       Some records, such as the birth record, are simply containers for other records.  Some
       records have a value, such as the date record, whose value is a date.  This is all defined
       in the Gedcom standard.

       To access an individual use a statement such as

         my $i = $ged->get_individual("Paul Johnson");

       To access information about the individual, use a function of the same name as the Gedcom
       tag, or its description.  Tags and descriptions are listed at the head of  For

         for my $b ($i->birth)

       will loop through all the birth records in the individual.  Usually there will only be one
       such record, but there may be zero, one or more.  Calling the function in scalar context
       will return only the first record.

         my $b = $i->birth;

       But the second record may be returned with

         my $b = $i->birth(2);

       If the record required has a value, for example

         my $n = $i->name;

       then the value is returned, in this case the name of the individual.  If there is no
       value, as is the case for the birth record, then the record itself is returned.  If there
       is a value, but the record itself is required, then the get_record() function can be used.

       Information must be accessed through the Gedcom structure so, for example, the birthdate
       is accessed via the date record from the birth record within an individual.

         my $d = $b->date;

       Be aware that if you access a record in scalar context, but there is no such record, then
       undef is returned.  In this case, $d would be undef if $b had no date record.  This is
       another reason why looping through records is a nice solution, all else being equal.

       Access to values can also be gained through the get_value() function.  This is a
       preferable solution where it is necessary to work down the Gedcom structure.  For example

         my $bd = $i->get_value("birth date");
         my $bd = $i->get_value(qw(birth date));

       will both return an individual's birth date or undef if there is none.  And

         my @bd = $i->get_value("birth date");

       will return all the birth dates.  The second birth date, if there is one, is

         my $bd2 = $i->get_value(["birth", 2], "date");

       Using the get_record() function in place of the get_value() function, in all cases will
       return the record rather than the value.

       All records are of a type derived from Gedcom::Item.  Individuals are of type
       Gedcom::Individual.  Families are of type Gedcom::Family.  Events are of type
       Gedcom::Event.  Other records are of type Gedcom::Record which is the base type of
       Gedcom::Individual, Gedcom::Family and Gedcom::Event.

       As individuals are of type Gedcom::Individual, the functions in are
       available.  These allow access to relations and other information specific to individuals,
       for example

         my @sons = $i->sons;

       It is possible to get all the individuals in the gedcom file as

         my @individuals = $ged->individuals;

       So putting everything together, here is a little program which will print out the names
       and birthdates of everyone in a GEDCOM file specified on the command line.

         #!/bin/perl -w

         use strict;
         use Gedcom;

         my $ged = Gedcom->new(shift);

         for my $i ($ged->individuals)
             for my $bd ($i->get_value("birth date"))
                 print $i->name, " was born on $bd\n";


       I have not gone the whole hog with data encapsulation and such within this module.  Maybe
       I should have done.  Maybe I will.  For now though, the data is accessible though hash
       members.  This is partly because having functions to do this is a little slow, especially
       on my old DECstation, and partly because of laziness again.  I'm not too sure whether this
       is good or bad laziness yet.  Time will tell no doubt.

       As of version 1.05, you should be able to access all the data through functions, and as of
       version 1.10 write access is available.  I have a faster machine now.

       Some of the more important hash members are:

       This contains the gedcom grammar.

       See for more details.

       This contains the top level gedcom record.  A record contains a number of items.  Each of
       those items are themselves records.  This is the way in which the hierarchies are

       If you want to get at the data in the gedcom object, this is where you start.

       See for more details.


         my $ged = Gedcom->new;

         my $ged = Gedcom->new($gedcom_file);

         my $ged = Gedcom->new(grammar_version => "5.5.1",
                               gedcom_file     => $gedcom_file,
                               read_only       => 1,
                               callback        => $cb);

         my $ged = Gedcom->new(grammar_file => "gedcom-5.5.grammar",
                               gedcom_file  => $gedcom_file);

       Create a new gedcom object.

       gedcom_file is the name of the gedcom file to parse.  If you do not supply a gedcom_file
       parameter then you will get an empty Gedcom object, empty that is apart from a few
       mandatory records.

       You may optionally pass grammar_version as the version number of the gedcom grammar you
       want to use.  There are two versions available, 5.5 and 5.5.1.  If you do not specify a
       grammar version, you may specify a grammar file as grammar_file.  Usually, you will do
       neither of these, and in this case the grammar version will default to the latest full
       available version, currently 5.5.  5.5.1 is only a draft, but it is available if you
       specify it.

       The read_only parameter indicates that the Gedcom data structure will be used primarily
       for read_only operations.  In this mode the gedcom file is read lazily, such that whenever
       possible the Gedcom records are not read until they are needed.  This can save on both
       memory and CPU usage, provided that not too much of the gedcom file is needed.  If the
       whole of the gedcom file needs to be read, for example to validate it, or to write it out
       in a different format, then this option should not be used.

       When using the read_only option an index file is kept which can also speed up operations.
       It's usage should be transparent, but will require write access to the directory
       containing the gedcom file.  If you access individuals only by their xref (eg I20) then
       the index file will allow only the relevant parts of the gedcom file to be read.

       With or without the read_only option, the gedcom file is accessed in the same fashion and
       the data structures can be changed.  In this respect, the name read_only is not very
       accurate, but since changing the Gedcom data will generally mean that the data will be
       written which means that the data will first be read, the read_only option is generally
       useful when the data will not be written and when not all the data will be read.  You may
       find it useful to experiment with this option and check the amount of CPU time and memory
       that your application uses.  You may also need to read this paragraph a few times to
       understand it.  Sorry.

       callback is an optional reference to a subroutine which will be called at various times
       while the gedcom file (and the grammar file, if applicable) is being read.  Its purpose is
       to provide feedback during potentially long operations.  The subroutine is called with
       five arguments:

         my ($title, $txt1, $txt2, $current, $total) = @_;

         $title is a brief description of the current operation
         $txt1 and $txt2 provide more information on the current operation
         $current is the number of operations performed
         $total is the number of operations that need to be performed

       If the subroutine returns false, the operation is aborted.


       Valid arguments are "ansel" and "utf-8".  Defaults to "ansel" but is set to "utf-8" if the
       gedcom data was read from a file which was deemed to contain UTF-8, either due to the
       presence of a BOM or as specified by a CHAR item.

       Set the encoding for the gedcom file.  Calling this directly doesn't alter the CHAR item,
       but does affect the way in which files are written.

         $ged->write($new_gedcom_file, $flush);

       Write out the gedcom file.

       Takes the name of the new gedcom file, and whether or not to indent the output according
       to the level of the record.  $flush defaults to false, but the new file name must be


       Write the gedcom file as XML.

       Takes the name of the new gedcom file.

       Note that this function is experimental.  The XML output doesn't conform to any standard
       that I know of, because I don't know of any standard.  If and when such a standard
       surfaces, and probably even if it doesn't, I'll change the output from this function.  If
       you make use of this function, beware.  I'd also be very interested in hearing from you to
       determine the requirements for the XML.


       Collect all the xrefs into a data structure ($ged->{xrefs}) for easy location.  $callback
       is not used yet.

       Called by new().

         my $xref = $self->resolve_xref($value);

       Return the record $value points to, or undef.


       Changes all xrefs to reference the record they are pointing to.  Like changing a soft link
       to a hard link on a Unix filesystem.  $callback is not used yet.


       Changes all xrefs to name the record they contained.  Like changing a hard link to a soft
       link on a Unix filesystem.  $callback is not used yet.

         return unless $ged->validate($callback);

       Validate the gedcom object.  This performs a number of consistency checks, but could do
       even more.  $callback is not properly used yet.

       Any errors found are given out as warnings.  If this is unwanted, use $SIG{__WARN__} to
       catch the warnings.

       Returns true iff the gedcom object is valid.

         $ged->normalise_dates("%A, %E %B %Y");

       Change all recognised dates into a consistent format.  This routine uses Date::Manip to do
       the work, so you can look at its documentation regarding formats that are recognised and %
       sequences for the output.

       Optionally takes a format to use for the output.  The default is currently "%A, %E %B %Y",
       but I may change this, as it seems that some programs don't like that format.

         my %xrefs = $ged->renumber(INDI => 34, FAM => 12, xrefs => [$xref1, $xref2]);

       Renumber all the records.

       Optional parameters are:

         tag name => last used number (defaults to 0)
         xrefs    => list of xrefs to renumber first

       As a record is renumbered, it is assigned the next available number.  The husband, wife,
       children, parents and siblings are then renumbered in that order.  This helps to ensure
       that families are numerically close together.

       The hash returned is the updated hash that was passed in.


       Default ordering subroutine.

       The sort is by record type in the following order: HEAD, SUBM, INDI, FAM, NOTE, TRLR, and
       then by xref within the type.


       Order all the records.  Optionally provide a sort subroutine.

       This orders the entries within the gedcom object, which will affect the order in which
       they are written out.  The default sort function is Gedcom::sort_sub.  You will need to
       ensure that the HEAD record is first and that the TRLR record is last.

         my @individuals = $ged->individuals;

       Return a list of all the individuals.

         my @families = $ged->families;

       Return a list of all the families.

         my $me = $ged->get_individual("Paul Johnson");

       Return a list of all individuals matching the specified name.

       There are thirteen matches performed, in decreasing order of exactitude.  This means that
       the more likely matches are at the head of the list.

       In scalar context return the first match found.

       The matches are:

          1 - Xref
          2 - Exact
          3 - On word boundaries
          4 - Anywhere
          5 - Exact, case insensitive
          6 - On word boundaries, case insensitive
          7 - Anywhere, case insensitive
          8 - Names in any order, on word boundaries
          9 - Names in any order, anywhere
         10 - Names in any order, on word boundaries, case insensitive
         11 - Names in any order, anywhere, case insensitive
         12 - Soundex code
         13 - Soundex of name

         my $xref = $ged->next_xref("I");

       Return the next available xref with the specified prefix.


       Create and return a new record of the specified type.

       Normally you will not want to pass any arguments to the function.  Those functions which
       have an xref (ie not header or trailer) accept an optional first argument { xref => $x }
       which will use $x as the xref rather than letting the module automatically choose the

       add_note also accepts an optional second argument which is the text to be used on the
       first line of the note.


       Return all records of the specified type.  In scalar context just return the first record.
       If a parameter is passed in, just return records of that xref.