.\" 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 "Arch::Storage 3pm"
.TH Arch::Storage 3pm "2022-06-08" "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"
Arch::Storage \- abstract class to access arch archives
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use base \*(AqArch::Storage\*(Aq;
\&
\&    # see synopsis of concrete classes
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Arch::Storage provides some common methods to query content of arch archive.
.PP
The methods usually return arrayref if not otherwise specified, and
are not affected by the list context (except for working_names).
.SH "METHODS"
.IX Header "METHODS"
The following (implemented and pure virtual) methods are common to subclasses:
.PP
\&\fBnew\fR,
\&\fBinit\fR,
\&\fBworking_name\fR,
\&\fBworking_names\fR,
\&\fBfixup_name_alias\fR,
\&\fBis_archive_managed\fR,
\&\fBexpanded_revisions\fR.
.PP
\&\fBarchives\fR,
\&\fBcategories\fR,
\&\fBbranches\fR,
\&\fBversions\fR,
\&\fBrevisions\fR,
\&\fBget_revision_descs\fR,
\&\fBexpanded_archive_info\fR,
\&\fBget_revision_changeset\fR,
\&\fBget_changeset\fR,
\&\fBget_revision_log\fR,
\&\fBget_log\fR.
.IP "\fBnew\fR [\fI\f(CI%args\fI\fR]" 4
.IX Item "new [%args]"
Create a new instance of the concrete subclass (i.e. Arch::Session or
Arch::Library).
.IP "\fBinstance\fR" 4
.IX Item "instance"
Alternative constructor. Return the last created instance of the concrete
subclass (i.e. Arch::Session or Arch::Library) or create a new one.
.Sp
The purpose of this alternative constructor is to allow the singleton
behaviour as well as certain Aspect Oriented Programming practices.
.Sp
Theoretical note: this design is acceptably good, and mixing \fBnew\fR and
\&\fBinstance\fR constructors in the code usually does what is intended. However,
if someone actually creates more than one object of any subclass, he has two
choices to enforce correctness. Either only use \fBinstance\fR method in the
code (singleton pattern), or alternatively create a temporary \fBnew\fR object
before calling methods of other classes that internally use \fBinstance\fR to
work with this subclass.
.IP "\fBinit\fR \fI\f(CI%args\fI\fR" 4
.IX Item "init %args"
Initialize or reset the object state.
.IP "\fBworking_name\fR [\fIname\fR]" 4
.IX Item "working_name [name]"
Set or get the default working operand for other methods.
.Sp
The argument may be anything that Arch::Name constructor accepts,
i.e. fully qualified string, arrayref, hashref or Arch::Name instance.
If needed, \fIname\fR is converted to Arch::Name instance, and this is
what is returned. Note that this object behaves as fully qualified name
in string context.
.IP "\fBworking_names\fR [\fIarchive\fR ..]" 4
.IX Item "working_names [archive ..]"
Similar to \fBworking_name\fR, but accepts and returns a list of name
components, from \fIarchive\fR to \fIrevision\fR.
.Sp
This method is provided for convenience and backward compatibility only.
You may as well use \fBworking_name\fR instead, just enclose the argument list
into arrayref, and call \fBto_array\fR on the returned object.
.IP "\fBfixup_name_alias\fR" 4
.IX Item "fixup_name_alias"
Replace (if needed) the \*(L"\s-1FIRST\*(R"\s0 and \*(L"\s-1LATEST\*(R"\s0 components of the working name's
\&\fIversion\fR and \fIrevision\fR with the actual values by querying the storage.
.IP "\fBis_archive_managed\fR [\fIarchive\fR]" 4
.IX Item "is_archive_managed [archive]"
Return true or false depending on whether the archive is known to the
storage.
.Sp
If given, the argument is used instead of the default \fBworking_name\fR.
.IP "\fBexpanded_revisions\fR" 4
.IX Item "expanded_revisions"
Return all revisions in all archives, each revision is Arch::Name object.
.IP "\fBarchives\fR" 4
.IX Item "archives"
Return all registered (or otherwise known) archives.
.IP "\fBcategories\fR [\fIarchive\fR]" 4
.IX Item "categories [archive]"
.PD 0
.IP "\fBbranches\fR   [\fIcategory\fR]" 4
.IX Item "branches [category]"
.IP "\fBversions\fR   [\fIbranch\fR]" 4
.IX Item "versions [branch]"
.IP "\fBrevisions\fR  [\fIversion\fR]" 4
.IX Item "revisions [version]"
.PD
Return all categories, branches, versions or revisions respectively
in the immediate parent, similarly to the corresponding \fItla\fR commands.
.Sp
If given, the argument is used instead of the default \fBworking_name\fR.
.IP "\fBget_revision_descs\fR [\fIversion\fR]" 4
.IX Item "get_revision_descs [version]"
Return describing hash for every revision in the version.
.Sp
If given, the argument is used instead of the default \fBworking_name\fR.
.Sp
The revision hashes have the following fields:
.RS 4
.IP "\fBname\fR" 4
.IX Item "name"
The revision name (i.e. \f(CW\*(C`base\-0\*(C'\fR, \f(CW\*(C`patch\-X\*(C'\fR, \f(CW\*(C`version\-0\*(C'\fR or \f(CW\*(C`versionfix\-X\*(C'\fR)
.IP "\fBsummary\fR" 4
.IX Item "summary"
The revision's commit log's summary line
.IP "\fBcreator\fR" 4
.IX Item "creator"
The name part of the committers \f(CW\*(C`tla my\-id\*(C'\fR (i.e. \f(CW\*(C`John Hacker\*(C'\fR)
.IP "\fBemail\fR" 4
.IX Item "email"
The email address part of the committers \f(CW\*(C`tla my\-id\*(C'\fR
(i.e. \f(CW\*(C`jhacker@nowhere.org\*(C'\fR)
.IP "\fBdate\fR" 4
.IX Item "date"
The revisions commit date in \f(CW\*(C`%Y\-%m\-%d %H:%M:%S %Z\*(C'\fR format (see
\&\fBstrftime\fR\|(3))
.IP "\fBkind\fR" 4
.IX Item "kind"
The kind of revision (i.e. one of \f(CW\*(C`tag\*(C'\fR, \f(CW\*(C`import\*(C'\fR, \f(CW\*(C`cset\*(C'\fR or \f(CW\*(C`unknown\*(C'\fR)
.RE
.RS 4
.RE
.IP "\fBexpanded_archive_info\fR [\fIarchive\fR]" 4
.IX Item "expanded_archive_info [archive]"
Returns a tree of categories, branches and versions in the
archive. The archive defaults to \fBworking_names\fR.
.Sp
Returns a reference to a list of categories. Every category is a list
consisting of the category name and a list of branches. Every branch
is a list consisting of the branch name and a list of versions. Every
version is list consisting of the version number and the first and
last revision name.
.Sp
.Vb 11
\&    [
\&      [ "category1", [
\&        [ "branch1", [
\&          [ "version1", "first_revision1", "last_revision1" ],
\&          [ "version2", "first_revision2", "last_revision2" ],
\&          ...
\&        ],
\&        ...
\&      ],
\&      ...
\&    ]
.Ve
.IP "\fBget_revision_changeset\fR \fIrevision\fR [\fIdir\fR]" 4
.IX Item "get_revision_changeset revision [dir]"
.PD 0
.IP "\fBget_changeset\fR [\fIdir\fR]" 4
.IX Item "get_changeset [dir]"
.PD
Fetches the changeset for \fIrevision\fR or \fBworking_name\fR and returns
an Arch::Changeset for it. If \fIdir\fR is specified, it will be used to
store the contents of the changeset. Otherwise a new temporary
directory will be created.
.IP "\fBget_revision_log\fR \fIrevision\fR" 4
.IX Item "get_revision_log revision"
.PD 0
.IP "\fBget_log\fR" 4
.IX Item "get_log"
.PD
Fetch the log for the \fIrevision\fR or \fBworking_name\fR. Returns an
Arch::Log object.
.SH "BUGS"
.IX Header "BUGS"
No known bugs.
.SH "AUTHORS"
.IX Header "AUTHORS"
Mikhael Goikhman (migo@homemail.com\*(--Perl\-GPL/arch\-perl\*(--devel).
.PP
Enno Cramer (uebergeek@web.de\-\-2003/arch\-perl\*(--devel).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information, see tla, Arch::Session, Arch::Library.