Gedcom::Record(3pm)

🎀 NAME 🎀

okay so bestie, say hi to Gedcom::Record — a module to manipulate Gedcom records 💖 and yes, it's the one living in the Gedcom::Record(3pm) section of your man pages.

We're on Version 1.22 - 15th November 2019, no cap. ✨

---

🦋 SYNOPSIS 🦋

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, "\n";
$record->delete_record($sub_record);

---

💅 DESCRIPTION 💅

A selection of subroutines to handle records in a GEDCOM file. That's the whole vibe. 🫶

Derived from Gedcom::Item. It's giving generational talent, honestly.

---

🌈 HASH MEMBERS 🌈

Some of the more important hash members are — peek behind the curtain bestie, we're going in 🔍:

$record->{new_xref}

Used by renumber().

$record->{recursed}

Used by renumber().

---

👑 METHODS 👑

tag_record

my $record  = tag_record("CHIL", 2);
my @records = tag_record("CHIL");

Get specific sub-records from the record. This function is identical to Gedcom::Item::get_item(). literally twins ✨

The arguments are the name of the tag, and optionally the count, starting from one.

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.

record

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");

Retrieve a record. 🎀

The get_record() function is identical to the record() function — same energy, different name.

In scalar context, record() returns the specified record, or undef if there is none. In list context, record() returns all the specified records.

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. It just keeps going, bestie, like a group chat at 2am 📱

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.

Instead of specifying a list of strings, it is possible to specify a single space separated string. This can make the interface nicer. aesthetic upgrade, we love to see it 🌸

get_value

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");

Retrieve a record's value. 💜

If arguments are specified, record() is first called with those arguments, and the values of those records are returned.

add

my $rec  = $record->add("birth date", "1 Jan 2000");

Add a new record. ✨ brand new, fresh out the box ✨

Add a new record ($rec) as a sub-item of $record. Set its value to the last argument given. The first arguments may be specified as for record(). A new record will always be created for the last argument, and for any arguments for which the count is explicitly set to zero.

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 ["arg", 0], or add undef as the last argument.

heads up bestie, that last bit is a whole gotcha — read it twice if you have to 😭

set

my $rec  = $record->set("birth date", "2 Jan 2000");

Set the value of a record.

This is the same as add(), with the exception that a new record is not created for the last argument. no new friends, just an update 💅

parse

$self->parse($record, $grammar);

Parse a Gedcom record.

Match a Gedcom::Record against a Gedcom::Grammar. Warn of any mismatches, and associate the Gedcom::Grammar with the Gedcom::Record as $record->{grammar}. Do this recursively. 🌀

collect_xrefs

$record->collect_xrefs($callback);

Recursively collect all the xrefs. Called by Gedcom::collect_xrefs. $callback is not used yet. (it's just sitting there, waiting for its moment 🙈)

resolve_xref

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

See Gedcom::resolve_xrefs(). 👀

resolve

my @famc = $record->resolve $record->tag_value("FAMC");

For each argument, either return it or, if it an xref, return the referenced record.

resolve_xrefs

$record->resolve_xrefs($callback);

See Gedcom::resolve_xrefs(). 👀

unresolve_xrefs

$record->unresolve_xrefs($callback);

See Gedcom::unresolve_xrefs(). 👀

validate_semantics

return 0 unless $record->validate_semantics;

Validate the semantics of the Gedcom::Record. This performs a number of consistency checks, but could do even more. overachiever core, but make it humble 🎀

Returns true iff the Record is valid.

normalise_dates

$record->normalise_dates($format);

Change the format of all dates in the record. 🗓️✨

See the documentation for Gedcom::normalise_dates.

renumber

$record->renumber($args);

Renumber the record.

See Gedcom::renumber(). 🔢

child_value

NOTE - This function is deprecated - use tag_value instead.

my $child = $record->child_value("NAME");

child_values

NOTE - This function is deprecated - use tag_value instead.

my @children = $record->child_values("CHIL");

summary

print $record->summary, "\n";

Return a line of text summarising the record. the tl;dr of records, truly iconic 📝

delete_record

$record->delete_record($sub_record);

Delete the specified sub-record from the record. 🗑️ bye bestie, sadly it's time

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.

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 use subs.

lowkey important: read that casing rule three times and then once more, because Perl will absolutely humble you otherwise 💀

---

and that's the whole page, bestie — we ate and left no crumbs 🍓

This little manual dropped as part of perl v5.36.0, dated 2022-10-16, and it's filed under Gedcom::Record(3pm). Take care of it, it's precious 💖🧚‍♀️🦋