view release on metacpan or  search on metacpan

lib/Gedcom.pm  view on Meta::CPAN

  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 particularly 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.

=head2 set_encoding

  $ged->set_encoding("utf-8");

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.

=head2 write

  $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 specified.

=head2 write_xml

  $ged->write_xml($new_xml_file);

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; it's just me trying to turn the GEDCOM format into sensible XML.

=head2 collect_xrefs

  $ged->collect_xrefs($callback);

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

Called by new().

=head2 resolve_xref

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

Return the record $value points to, or undef.

=head2 resolve_xrefs

  $ged->resolve_xrefs($callback);

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.

=head2 unresolve_xrefs

  $ged->unresolve_xrefs($callback);

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.

=head2 validate

  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.