.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Gedcom::Record 3pm"
.TH Gedcom::Record 3pm "2016-10-29" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Gedcom::Record \- a module to manipulate Gedcom records
.PP
Version 1.20 \- 17th September 2017
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Gedcom::Record;
\&
\&  my $record  = tag_record("CHIL", 2);
\&  my @records = tag_record("CHIL");
\&  my @recs = $record\->record("birth");
\&  my @recs = $record\->record("birth", "date");
\&  my $rec  = $record\->record("birth date");
\&  my $rec  = $record\->record(["birth", 2], "date");
\&  my @recs = $record\->get_record("birth");
\&  my $val  = $record\->get_value;
\&  my @vals = $record\->get_value("date");
\&  my @vals = $record\->get_value("birth", "date");
\&  my $val  = $record\->get_value("birth date");
\&  my $val  = $record\->get_value(["birth", 2], "date");
\&  my $rec  = $record\->add("birth date", "1 Jan 2000");
\&  my $rec  = $record\->set("birth date", "2 Jan 2000");
\&  $self\->parse($record, $grammar);
\&  $record\->collect_xrefs($callback);
\&  my $xref = $record\->resolve_xref($record\->{value});
\&  my @famc = $record\->resolve $record\->get_value("FAMC");
\&  $record\->resolve_xrefs($callback);
\&  $record\->unresolve_xrefs($callback);
\&  return 0 unless $record\->validate_semantics;
\&  $record\->normalise_dates($format);
\&  $record\->renumber($args);
\&  print $record\->summary, "\en";
\&  $record\->delete_record($sub_record);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A selection of subroutines to handle records in a gedcom file.
.PP
Derived from Gedcom::Item.
.SH "HASH MEMBERS"
.IX Header "HASH MEMBERS"
Some of the more important hash members are:
.ie n .SS "$record\->{new_xref}"
.el .SS "\f(CW$record\fP\->{new_xref}"
.IX Subsection "$record->{new_xref}"
Used by \fIrenumber()\fR.
.ie n .SS "$record\->{recursed}"
.el .SS "\f(CW$record\fP\->{recursed}"
.IX Subsection "$record->{recursed}"
Used by \fIrenumber()\fR.
.SH "METHODS"
.IX Header "METHODS"
.SS "tag_record"
.IX Subsection "tag_record"
.Vb 2
\&  my $record  = tag_record("CHIL", 2);
\&  my @records = tag_record("CHIL");
.Ve
.PP
Get specific sub-records from the record.  This function is identical to
\&\fIGedcom::Item::get_item()\fR.
.PP
The arguments are the name of the tag, and optionally the count, starting from
one.
.PP
In scalar context, returns the sub-record, or undef if it doesn't exist.
In array context, returns all sub-records matching the specified tag.
.SS "record"
.IX Subsection "record"
.Vb 5
\&  my @recs = $record\->record("birth");
\&  my @recs = $record\->record("birth", "date");
\&  my $rec  = $record\->record("birth date");
\&  my $rec  = $record\->record(["birth", 2], "date");
\&  my @recs = $record\->get_record("birth");
.Ve
.PP
Retrieve a record.
.PP
The \fIget_record()\fR function is identical to the \fIrecord()\fR function.
.PP
In scalar context, \fIrecord()\fR returns the specified record, or undef if
there is none.  In list context, \fIrecord()\fR returns all the specified
records.
.PP
Records may be specified by a list of strings.  Each string is either a
Gedcom tag or a description.  Starting from the first string in the
list, specified records are retrieved.  Then from those records, records
specified by the next string in the list are retrieved.  This continues
until all strings from the list have been used.
.PP
In list context, all specified records are retrieved.  In scalar
context, only the first record is retrieved.  If a record other than the
first is wanted, then instead of passing a string, a reference to an
array containing the string and a count may be passed.
.PP
Instead of specifying a list of strings, it is possible to specify a
single space separated string.  This can make the interface nicer.
.SS "get_value"
.IX Subsection "get_value"
.Vb 5
\&  my $val  = $record\->get_value;
\&  my @vals = $record\->get_value("date");
\&  my @vals = $record\->get_value("birth", "date");
\&  my $val  = $record\->get_value("birth date");
\&  my $val  = $record\->get_value(["birth", 2], "date");
.Ve
.PP
Retrieve a record's value.
.PP
If arguments are specified, \fIrecord()\fR is first called with those
arguments, and the values of those records are returned.
.SS "add"
.IX Subsection "add"
.Vb 1
\&  my $rec  = $record\->add("birth date", "1 Jan 2000");
.Ve
.PP
Add a new record.
.PP
Add a new record ($rec) as a sub-item of \f(CW$record\fR.  Set its value to the
last argument given.  The first arguments may be specified as for
\&\fIrecord()\fR.  A new record will always be created for the last argument,
and for any arguments for which the count is explicitly set to zero.
.PP
If the new record does not take a value then do not supply one.  This
does mean that you cannot use the function with many arguments if the
last one is a scalar, but not a value.  In this case either specify the
last argument as [\*(L"arg\*(R", 0], or add undef as the last argument.
.SS "set"
.IX Subsection "set"
.Vb 1
\&  my $rec  = $record\->set("birth date", "2 Jan 2000");
.Ve
.PP
Set the value of a record.
.PP
This is the same as \fIadd()\fR, with the exception that a new record is not
created for the last argument.
.SS "parse"
.IX Subsection "parse"
.Vb 1
\&  $self\->parse($record, $grammar);
.Ve
.PP
Parse a Gedcom record.
.PP
Match a Gedcom::Record against a Gedcom::Grammar.  Warn of any
mismatches, and associate the Gedcom::Grammar with the Gedcom::Record as
\&\f(CW$record\fR\->{grammar}.  Do this recursively.
.SS "collect_xrefs"
.IX Subsection "collect_xrefs"
.Vb 1
\&  $record\->collect_xrefs($callback);
.Ve
.PP
Recursively collect all the xrefs.  Called by Gedcom::collect_xrefs.
\&\f(CW$callback\fR is not used yet.
.SS "resolve_xref"
.IX Subsection "resolve_xref"
.Vb 1
\&  my $xref = $record\->resolve_xref($value);
.Ve
.PP
See \fIGedcom::resolve_xrefs()\fR
.SS "resolve"
.IX Subsection "resolve"
.Vb 1
\&  my @famc = $record\->resolve $record\->tag_value("FAMC");
.Ve
.PP
For each argument, either return it or, if it an xref, return the
referenced record.
.SS "resolve_xrefs"
.IX Subsection "resolve_xrefs"
.Vb 1
\&  $record\->resolve_xrefs($callback);
.Ve
.PP
See \fIGedcom::resolve_xrefs()\fR
.SS "unresolve_xrefs"
.IX Subsection "unresolve_xrefs"
.Vb 1
\&  $record\->unresolve_xrefs($callback);
.Ve
.PP
See \fIGedcom::unresolve_xrefs()\fR
.SS "validate_semantics"
.IX Subsection "validate_semantics"
.Vb 1
\&  return 0 unless $record\->validate_semantics;
.Ve
.PP
Validate the semantics of the Gedcom::Record.  This performs a number of
consistency checks, but could do even more.
.PP
Returns true iff the Record is valid.
.SS "normalise_dates"
.IX Subsection "normalise_dates"
.Vb 1
\&  $record\->normalise_dates($format);
.Ve
.PP
Change the format of all dates in the record.
.PP
See the documentation for Gedcom::normalise_dates
.SS "renumber"
.IX Subsection "renumber"
.Vb 1
\&  $record\->renumber($args);
.Ve
.PP
Renumber the record.
.PP
See \fIGedcom::renumber()\fR.
.SS "child_value"
.IX Subsection "child_value"
\&\s-1NOTE \-\s0 This function is deprecated \- use tag_value instead.
.PP
.Vb 1
\&  my $child = $record\->child_value("NAME");
.Ve
.SS "child_values"
.IX Subsection "child_values"
\&\s-1NOTE \-\s0 This function is deprecated \- use tag_value instead.
.PP
.Vb 1
\&  my @children = $record\->child_values("CHIL");
.Ve
.SS "summary"
.IX Subsection "summary"
.Vb 1
\&  print $record\->summary, "\en";
.Ve
.PP
Return a line of text summarising the record.
.SS "delete_record"
.IX Subsection "delete_record"
.Vb 1
\&  $record\->delete_record($sub_record);
.Ve
.PP
Delete the specified sub-record from the record.
.SS "Access functions"
.IX Subsection "Access functions"
All the Gedcom tag names can be used as function names.  Depending on
the context in which they are called, the functions return either an
array of the specified sub-items, or the first specified sub-item.
.PP
The descriptions of the tags, with spaces replaced by underscores, can
also be used as function names.  The function names can be of either, or
mixed case.  Unless you use the tag name, in either case, or the
description in lower case, the function will not be pre-declared and you
will need to qualify it or \f(CW\*(C`use subs\*(C'\fR.