.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OpenBSD::PackingList 3p"
.TH OpenBSD::PackingList 3p "2008-05-30" "perl v5.8.8" "Perl Programmers Reference Guide"
.SH "NAME"
OpenBSD::PackingList \- \f(CWpkg_add(1)\fR packing\-list manipulations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&    use OpenBSD::PackingList;
\&    # different methods to create packing-lists
\&    my $p1 = OpenBSD::PackingList->new();       # empty
\&    my $p2 = OpenBSD::PackingList->read($fh);
\&    my $p3 = OpenBSD::PackingList->fromfile($filename);
\&    my $p4 = OpenBSD::PackingList->fromfile(\e$scalar);
\&    my $p5 = OpenBSD::PackingList->from_installation($pkgname);
.Ve
.PP
.Vb 5
\&    # writing packing-lists
\&    $p2->write($fh);
\&    $p3->tofile($filename);
\&    $p4->to_installation();
\&    $p4->to_cache();
.Ve
.PP
.Vb 4
\&    # building up packing-lists
\&    OpenBSD::PackingElement::SUBCLASS->add($plist, @args);
\&    my $o = OpenBSD::PackingElement::SUBCLASS->new(@args);
\&    $o->add_object($plist);
.Ve
.PP
.Vb 5
\&    # tests and access
\&    $b = $p2->has($name);
\&    $b = $p2->get($name);
\&    # frequent accesses
\&    print $p3->pkgname, $p3->localbase, "\en";
.Ve
.PP
.Vb 2
\&    # processing packing-lists
\&    $p4->visit('method', @args);
.Ve
.PP
.Vb 2
\&    # auto visit
\&    $p4->method(@args);
.Ve
.PP
.Vb 3
\&    # signatures
\&    if ($p3->signature eq $p4->signature) {
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`OpenBSD::PackingList\*(C'\fR is the only supported interface for access to
packing-list information. It includes conversion methods from an external
textual representation (file) into an internal structured representation.
Basically, a packing-list is a collection of strongly-typed objects. Some
of these objects are just properties of the package (like the package name,
or dependencies), some objects have long lists of properties (files come
with \s-1MD5\s0 checksums, sizes, or linknames), some objects represent state
information (like file modes) and must be kept in the proper order.
The \f(CW\*(C`OpenBSD::PackingList\*(C'\fR class handles all that.
.PP
Packing-lists can be obtained using the following methods: from an
opened file handle using \f(CW\*(C`OpenBSD::PackingList\->read($fh)\*(C'\fR, from
an existing file using \f(CW\*(C`OpenBSD::PackingList\->fromfile($filename)\*(C'\fR,
from a scalar in memory using \f(CW\*(C`OpenBSD::PackingList\->fromfile(\e$scalar)\*(C'\fR,
or from an installed package using 
\&\f(CW\*(C`OpenBSD::PackingList\->from_installation($pkgname)\*(C'\fR.
.PP
Since building a full packing-list is a complex operation and can consume
a large amount of memory, those methods may take an extra argument in order to
obtain partial packing-lists with only some information:
.IP "SharedItemsOnly" 16
.IX Item "SharedItemsOnly"
read only stuff that may be shared between packages, e.g., new users, 
groups and directories.
.IP "LibraryOnly" 16
.IX Item "LibraryOnly"
read only shared library entries.
.IP "FilesOnly" 16
.IX Item "FilesOnly"
read only files without the associated annotations like size or \s-1MD5\s0.
.IP "DependOnly" 16
.IX Item "DependOnly"
read only dependency information.
.IP "ExtraInfoOnly" 16
.IX Item "ExtraInfoOnly"
read only the extra information field.
.IP "UpdateInfoOnly" 16
.IX Item "UpdateInfoOnly"
read only what is needed to decide to update a package.
.PP
A complete packing-list \f(CW$plist\fR may be written to disk using the 
following methods:
\&\f(CW\*(C`$plist\->write($fh)\*(C'\fR will write a packing-list to an
opened file handle \f(CW$fh\fR, \f(CW\*(C`$plist\->tofile($filename)\*(C'\fR will
write a packing-list to a file named \f(CW$filename\fR, and 
\&\f(CW\*(C`$plist\->to_installation()\*(C'\fR will write a packing-list during
registration of a package.
.PP
In addition \f(CW\*(C`$plist\->to_cache()\*(C'\fR will register enough 
information from a package to let the framework believe the package has
been installed. This is used for the simulation modes of \f(CWpkg_add(1)\fR
and friends.
.PP
Since a packing-list is structured information, reading a packing-list from
the disk and writing it back offers no guarantee the information will remain
in the same order.  It is a good way to validate packing-lists and normalize
them, though.
.PP
Building packing-lists entails cooperation with \f(CW\*(C`OpenBSD::PackingElement\*(C'\fR.
Packing-lists are usually built by adding objects from an 
\&\f(CW\*(C`OpenBSD::PackingElement\*(C'\fR subclass to the packing\-list, either with
the \f(CW\*(C`add\*(C'\fR constructor:  
\&\f(CW\*(C`OpenBSD::PackingElement::SUBCLASS\->add($plist, $args)\*(C'\fR, which builds
a packing element and adds it to the packing-list in one operation, or with
the \f(CW\*(C`add_object\*(C'\fR method, which takes an existing packing element and adds it
to the packing-list (note that \f(CW\*(C`add_object\*(C'\fR only makes sense for subclasses
of \f(CW\*(C`OpenBSD::PackingElement::Object\*(C'\fR).
See OpenBSD::PackingElement for more details.
.PP
\&\f(CW\*(C`$plist\->pkgname()\*(C'\fR retrieves a packing-list name (mandatory).
\&\f(CW\*(C`$plist\->signature()\*(C'\fR retrieves a packing-list full signature, composed
of the package name and dependency information.
.PP
\&\f(CW\*(C`$plist\->visit($method, @args)\*(C'\fR is a visitor pattern, calling
\&\f(CW\*(C`method(@args)\*(C'\fR on each element of the packing-list in a specific order.
.PP
As a feature, if \f(CW\*(C`OpenBSD::PackingElement\->can(method)\*(C'\fR, 
\&\f(CW\*(C`$plist\->method(@args)\*(C'\fR will be turned into a visitor call automatically.