.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Gedcom::Item 3pm"
.TH Gedcom::Item 3pm "2022-10-16" "perl v5.34.0" "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::Item \- a base class for Gedcom::Grammar and Gedcom::Record
.PP
Version 1.22 \- 15th November 2019
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A selection of subroutines to handle items in a \s-1GEDCOM\s0 file.
.SH "HASH MEMBERS"
.IX Header "HASH MEMBERS"
Some of the more important hash members are:
.ie n .SS "$item\->{level}"
.el .SS "\f(CW$item\fP\->{level}"
.IX Subsection "$item->{level}"
The level of the item.
.ie n .SS "$item\->{xref}"
.el .SS "\f(CW$item\fP\->{xref}"
.IX Subsection "$item->{xref}"
The cross reference, either hard or soft.
.ie n .SS "$item\->{tag}"
.el .SS "\f(CW$item\fP\->{tag}"
.IX Subsection "$item->{tag}"
The name of the tag.
.ie n .SS "$item\->{value}"
.el .SS "\f(CW$item\fP\->{value}"
.IX Subsection "$item->{value}"
The value of the item.
.ie n .SS "$item\->{pointer}"
.el .SS "\f(CW$item\fP\->{pointer}"
.IX Subsection "$item->{pointer}"
True iff the value is a pointer to another item.
.ie n .SS "$item\->{min}"
.el .SS "\f(CW$item\fP\->{min}"
.IX Subsection "$item->{min}"
The minimum number of items allowed.
.ie n .SS "$item\->{max}"
.el .SS "\f(CW$item\fP\->{max}"
.IX Subsection "$item->{max}"
The maximum number of items allowed.
.ie n .SS "$item\->{gedcom}"
.el .SS "\f(CW$item\fP\->{gedcom}"
.IX Subsection "$item->{gedcom}"
The top level Gedcom object.
.ie n .SS "$item\->{file}"
.el .SS "\f(CW$item\fP\->{file}"
.IX Subsection "$item->{file}"
The file from which this object was read, if any.
.ie n .SS "$item\->{line}"
.el .SS "\f(CW$item\fP\->{line}"
.IX Subsection "$item->{line}"
The line number from which this object was read, if any.
.ie n .SS "$item\->{items}"
.el .SS "\f(CW$item\fP\->{items}"
.IX Subsection "$item->{items}"
Array of all sub-items of this item.
.PP
It should not be necessary to access these hash members directly.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 2
\&  $item\->{grammar} = Gedcom::Grammar\->new(file     => $item\->{grammar_file},
\&                                          callback => $item\->{callback});
.Ve
.PP
Create a new object.
.PP
If file is supplied, it is the name of a file to read.
.PP
If callback is supplied, it is a subroutine reference which is called at
various times while the file is being read.
.PP
The subroutine takes five parameters:
  \f(CW$title:\fR     A title
  \f(CW$txt1:\fR      One text message
  \f(CW$txt2:\fR      A secondary text message
  \f(CW$current:\fR   A count of how far through the file we are
  \f(CW$total:\fR     The extent of the file
.PP
The subroutine should return true iff the file should continue to be
read.
.SS "copy"
.IX Subsection "copy"
.Vb 1
\&  my $c = $item\->copy;
.Ve
.PP
Make a copy of the object.  The sub-items are copied too.
.SS "read"
.IX Subsection "read"
.Vb 1
\&  $item\->read if $item\->{file};
.Ve
.PP
Read a file into the object.  Called by the constructor.
.SS "add_items"
.IX Subsection "add_items"
.Vb 1
\&  $item\->add_items($rec);
.Ve
.PP
Read in the sub-items of a item.
.SS "next_item"
.IX Subsection "next_item"
.Vb 1
\&  while (my $next = $item\->next_item($item))
.Ve
.PP
Read the next item from a file.  Return the item or false if it
cannot be read.
.SS "next_line"
.IX Subsection "next_line"
.Vb 1
\&  my $line = $item\->next_line;
.Ve
.PP
Read the next line from the file, and return it or false.
.SS "next_text_line"
.IX Subsection "next_text_line"
.Vb 1
\&  my $line = $item\->next_text_line;
.Ve
.PP
Read the next line of text from the file, and return it or false.
.SS "write"
.IX Subsection "write"
.Vb 1
\&  $item\->write($fh, $level, $flush);
.Ve
.PP
Write the item to a FileHandle.
.PP
The subroutine takes three parameters:
  \f(CW$fh:\fR        The FileHandle to which to write
  \f(CW$level:\fR     The level of the item
  \f(CW$flush:\fR     Whether or not to indent the \s-1GEDCOM\s0 output according to the level
.SS "write_xml"
.IX Subsection "write_xml"
.Vb 1
\&  $item\->write_xml($fh, $level);
.Ve
.PP
Write the item to a FileHandle as \s-1XML.\s0
.PP
The subroutine takes two parameters:
  \f(CW$fh:\fR        The FileHandle to which to write
  \f(CW$level:\fR     The level of the item
.PP
Note that this function is experimental.  Please read the warnings for
\&\fBGedcom::write_xml()\fR.
.SS "print"
.IX Subsection "print"
.Vb 1
\&  $item\->print;
.Ve
.PP
Print the item.  Used for debugging.  (What?  There are bugs?)
.SS "get_item"
.IX Subsection "get_item"
.Vb 2
\&  my $item  = $item\->get_item("CHIL", 2);
\&  my @items = $item\->get_items("CHIL");
.Ve
.PP
Get specific sub-items from the item.
.PP
The arguments are the name of the tag, and optionally the count, starting from
one.
.PP
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.
.SS "get_child"
.IX Subsection "get_child"
\&\s-1NOTE\s0 \- This function is deprecated \- use get_item instead
.PP
.Vb 1
\&  my $child = get_child("CHIL2");
.Ve
.PP
Get a specific child item from the item.
.PP
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:
.PP
.Vb 1
\&  my ($tag, $count) = $t =~ /^_?(\ew+?)(\ed*)$/
.Ve
.PP
Returns the child item, or undef if it doesn't exist
.SS "get_children"
.IX Subsection "get_children"
\&\s-1NOTE\s0 \- This function is deprecated \- use get_item instead
.PP
.Vb 1
\&  my @children = get_children("CHIL");
.Ve
.SS "parent"
.IX Subsection "parent"
.Vb 1
\&  my $parent = $item\->parent;
.Ve
.PP
Returns the parent of the item or undef if there is none.
.PP
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.
.SS "delete"
.IX Subsection "delete"
.Vb 1
\&  my $success = $item\->delete;
.Ve
.PP
Deletes the item.
.PP
Note that this is an expensive function.  It use \fBparent()\fR described
above.  It is better to use \f(CW$parent\fR\->delete_item($child), assuming that
you know \f(CW$parent\fR.
.PP
Note too that this function calls \fBdelete_item()\fR, so its caveats apply.
.SS "delete_item"
.IX Subsection "delete_item"
.Vb 1
\&  $item\->delete_item($sub_item);
.Ve
.PP
Delete the specified sub-item from the item.
.PP
Note that this function doesn't do any housekeeping.  It is up to you to
ensure that you don't leave any dangling pointers.
.SS "Access functions"
.IX Subsection "Access functions"
.Vb 11
\&  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;
.Ve
.PP
Return the eponymous hash element.  If a value if passed into the
function, the element is first assigned that value.
.SS "full_value"
.IX Subsection "full_value"
.Vb 1
\&  my $v = $item\->full_value;
.Ve
.PP
Return the value of the item including all \s-1CONT\s0 and \s-1CONC\s0 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 \s-1CONT\s0 and \s-1CONC\s0 items yourself, you will need to use
the \fBvalue()\fR function and probably the \fBitems()\fR function.
.SS "_items"
.IX Subsection "_items"
.Vb 1
\&  my $sub_items = $item\->_items;
.Ve
.PP
Return a reference to a list of all the sub-items, reading them from the
\&\s-1GEDCOM\s0 file if they have not already been read.
.PP
It should not be necessary to use this function.  See \fBitems()\fR.
.SS "items"
.IX Subsection "items"
.Vb 1
\&  my @sub_items = $item\->items;
.Ve
.PP
Return a list of all the sub-items, reading them from the \s-1GEDCOM\s0 file if
they have not already been read.
.PP
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 \s-1CONT\s0 and \s-1CONC\s0
items.
.SS "delete_items"
.IX Subsection "delete_items"
.Vb 1
\&  $item\->delete_items;
.Ve
.PP
Delete all the sub-items, allowing the memory to be reused.  If the
sub-items are required again, they will be reread.
.PP
It should not be necessary to use this function unless you are using
read_only mode and need to reclaim your memory.