Gedcom::Item(3pm)

📦
version 1.22 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Gedcom::Item(3pm) 💖

okay bestie, welcome to Gedcom::Item, the Perl module that's literally the base class for Gedcom::Grammar and Gedcom::Record. It lives in the User Contributed Perl Documentation and it's giving very much “I hold all the GEDCOM items together” energy. ✨

🌸 NAME 🌸

Gedcom::Item — a base class for Gedcom::Grammar and Gedcom::Record

Version 1.22 - 15th November 2019

✨ SYNOPSIS ✨

No cap, here's the whole vibe in code:

  use Gedcom::Record;

  $item->{grammar} = Gedcom::Grammar->new(file     => $item->{grammar_file},
                                          callback => $item->{callback});
  my $c = $item->copy;
  $item->read if $item->{file};
  $item->add_items($rec);
  while (my $next = $item->next_item($item))
  my $line = $item->next_line;
  my $line = $item->next_text_line;
  $item->write($fh, $level, $flush);
  $item->write_xml($fh, $level);
  $item->print;
  my $item  = $item->get_item("CHIL", 2);
  my @items = $item->get_item("CHIL");
  my $parent = $item->parent;
  my $success = $item->delete;
  $item->delete_item($sub_item);
  my $v = $item->level;
  $item->level(1);
  my $v = $item->xref;
  my $v = $item->tag;
  my $v = $item->value;
  my $v = $item->pointer;
  my $v = $item->min;
  my $v = $item->max;
  my $v = $item->gedcom;
  my $v = $item->file;
  my $v = $item->line;
  my $v = $item->full_value;
  my $sub_items = $item->_items;
  my @sub_items = $item->items;
  $item->delete_items;

💖 DESCRIPTION 💖

A selection of subroutines to handle items in a GEDCOM file. That's the whole point, bestie.

🎀 HASH MEMBERS 🎀

Some of the more important hash members are:

$item->{level}

The level of the item.

$item->{xref}

The cross reference, either hard or soft.

$item->{tag}

The name of the tag.

$item->{value}

The value of the item.

$item->{pointer}

True iff the value is a pointer to another item.

$item->{min}

The minimum number of items allowed.

$item->{max}

The maximum number of items allowed.

$item->{gedcom}

The top level Gedcom object.

$item->{file}

The file from which this object was read, if any.

$item->{line}

The line number from which this object was read, if any.

$item->{items}

Array of all sub-items of this item.

It should not be necessary to access these hash members directly. fr fr, hands off the internals unless you know what you're doing.

👑 METHODS 👑

new

$item->{grammar} = Gedcom::Grammar->new(file     => $item->{grammar_file},
                                        callback => $item->{callback});

Create a new object.

If file is supplied, it is the name of a file to read.

If callback is supplied, it is a subroutine reference which is called at various times while the file is being read.

The subroutine takes five parameters:

  • $title: A title
  • $txt1: One text message
  • $txt2: A secondary text message
  • $current: A count of how far through the file we are
  • $total: The extent of the file

The subroutine should return true iff the file should continue to be read.

copy

my $c = $item->copy;

Make a copy of the object. The sub-items are copied too.

read

$item->read if $item->{file};

Read a file into the object. Called by the constructor.

add_items

$item->add_items($rec);

Read in the sub-items of a item.

next_item

while (my $next = $item->next_item($item))

Read the next item from a file. Return the item or false if it cannot be read.

next_line

my $line = $item->next_line;

Read the next line from the file, and return it or false.

next_text_line

my $line = $item->next_text_line;

Read the next line of text from the file, and return it or false.

write

$item->write($fh, $level, $flush);

Write the item to a FileHandle.

The subroutine takes three parameters:

  • $fh: The FileHandle to which to write
  • $level: The level of the item
  • $flush: Whether or not to indent the GEDCOM output according to the level

write_xml

$item->write_xml($fh, $level);

Write the item to a FileHandle as XML.

The subroutine takes two parameters:

  • $fh: The FileHandle to which to write
  • $level: The level of the item
Note that this function is experimental. Please read the warnings for Gedcom::write_xml(). experimental means proceed with caution, bestie!

print

$item->print;

Print the item. Used for debugging. (What? There are bugs?) not me side-eyeing the bugs 💀

get_item

my $item  = $item->get_item("CHIL", 2);
my @items = $item->get_items("CHIL");

Get specific sub-items from the item.

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

In scalar context, returns the sub-item, or undef if it doesn't exist. In array context, returns all sub-items matching the specified tag.

get_child

NOTE - This function is deprecated - use get_item instead
my $child = get_child("CHIL2");

Get a specific child item from the item.

The argument contains the name of the tag, and optionally the count, starting from one. The regular expression to generate the tag and the count is:

my ($tag, $count) = $t =~ /^_?(\w+?)(\d*)$/

Returns the child item, or undef if it doesn't exist

get_children

NOTE - This function is deprecated - use get_item instead
my @children = get_children("CHIL");

parent

my $parent = $item->parent;

Returns the parent of the item or undef if there is none.

Note that this is an expensive function. A child does not know who its parent is, and so this function searches through all items looking for one with the appropriate child. it's giving “where is my mother” but make it O(n) 😭

delete

my $success = $item->delete;

Deletes the item.

Note that this is an expensive function. It use parent() described above. It is better to use $parent->delete_item($child), assuming that you know $parent.
Note too that this function calls delete_item(), so its caveats apply.

delete_item

$item->delete_item($sub_item);

Delete the specified sub-item from the item.

Note that this function doesn't do any housekeeping. It is up to you to ensure that you don't leave any dangling pointers. do NOT leave dangling pointers, that's the drama we don't want.

Access functions

my $v = $item->level;
$item->level(1);
my $v = $item->xref;
my $v = $item->tag;
my $v = $item->value;
my $v = $item->pointer;
my $v = $item->min;
my $v = $item->max;
my $v = $item->gedcom;
my $v = $item->file;
my $v = $item->line;

Return the eponymous hash element. If a value if passed into the function, the element is first assigned that value.

full_value

my $v = $item->full_value;

Return the value of the item including all CONT and CONC lines. This is probably what you want most of the time, and is the function called by default from other functions that return values. If, for some reason, you want to process CONT and CONC items yourself, you will need to use the value() function and probably the items() function.

_items

my $sub_items = $item->_items;

Return a reference to a list of all the sub-items, reading them from the GEDCOM file if they have not already been read.

It should not be necessary to use this function. See items(). lowkey private, highkey useful internally.

items

my @sub_items = $item->items;

Return a list of all the sub-items, reading them from the GEDCOM file if they have not already been read.

In general it should not be necessary to use this function. The sub-items will usually be accessed by name. This function is only necessary if the ordering of the different items is important. This is very rare, but is needed for example, when processing CONT and CONC items.

delete_items

$item->delete_items;

Delete all the sub-items, allowing the memory to be reused. If the sub-items are required again, they will be reread.

It should not be necessary to use this function unless you are using read_only mode and need to reclaim your memory.

💖 okay bestie, that's the whole page! This one came from perl v5.36.0, dated 2022-10-16, and it's Gedcom::Item(3pm). Go slay your GEDCOM files, no cap! 💅✨🦋

📦 where this page comes from