.\" 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::RevisionBunches 3pm"
.TH Arch::RevisionBunches 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::RevisionBunches \- manage bunches of related revisions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Arch::RevisionBunches;
\&    use Arch::Tree;
\&
\&    my $rb = Arch::RevisionBunches\->new;
\&    my $tree = Arch::Tree\->new(".", own_logs => 1);
\&    $rb\->add_revision_descs($tree\->get_history_revision_descs);
\&    $rb\->rebunch(25);  # the default is 50
\&    foreach my $bunch ($rb\->get) {
\&        print "$bunch\->{version}\en";
\&        print "    $_\->{name}\et$_\->{summary}\en"
\&            foreach @{$bunch\->{revision_descs}};
\&    }
\&    foreach my $bunch ($rb\->reverse_revision_descs\->rebunch(30)) {
\&        print $bunch\->{name1};
\&        print " .. $bunch\->{name2}" if $bunch\->{name2};
\&        print " ($bunch\->{daysago1}";
\&        print " .. $bunch\->{daysago2}" if $bunch\->{name2};
\&        print " days ago)\en";
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class helps front-ends to group revisions. Such grouping is essential
when, for example, the version to be shown contains thousands of revisions.
The front-end may decide to show expandable bunches of 100 revisions each.
.PP
There is a support for revision descriptions (summary, date, creator, email,
and in some cases associated the file name and/or the associated version).
There is a constraint by convention, one bunch may only contain revisions of
the same version, and the ones associated with the same file if applicable.
It is possible to define an order of versions. It is possible to recreate
bunches (rebunch) using a different number of revisions. The constraint
defines the actual number of revisions in different bunches, it is not
guaranteed to be the same.
.SH "METHODS"
.IX Header "METHODS"
The following methods are available:
.PP
\&\fBnew\fR,
\&\fBinit\fR,
\&\fBadd_revision_descs\fR,
\&\fBversions\fR,
\&\fBrebunch\fR,
\&\fBget\fR,
\&\fBclear\fR,
\&\fBreverse_revision_descs\fR,
\&\fBversions\fR,
\&\fBfilepaths\fR.
.IP "\fBnew\fR [\fI\f(CI%args\fI\fR]" 4
.IX Item "new [%args]"
Construct Arch::RevisionBunches object.
.Sp
The \fI\f(CI%args\fI\fR are passed to \fBinit\fR method.
.IP "\fBinit\fR [\fI\f(CI%args\fI\fR]" 4
.IX Item "init [%args]"
The \fI\f(CI%args\fI\fR keys may be \fIbunch_size\fR (to use as the default bunch size
instead of 50), \fImax_sumlen\fR (maximal summary length to keep including
trailing ellipsis, must be greater than 5), \fIversion\fR (if set, then all
revisions are assumed to be of one version, otherwise multiple versions are
assumed), \fIfinal_revision\fR and \fIfinal_filepath\fR (the final revision and
filepath for which the revision bunches are constructed). These last two
\&\fI\f(CI%args\fI\fR keys are not really used yet.
.IP "\fBadd_revision_descs\fR [\fI\f(CI%constant_fields\fI\fR]" 4
.IX Item "add_revision_descs [%constant_fields]"
Add revision descriptions that is arrayref of hashes. See other classes that
return such revision descriptions. If the \fI\f(CI%constant_fields\fI\fR is given, then
add these to all revision descriptions (rarely needed).
.Sp
Return the object, this enables chaining of \fBget\fR or \fBrebunch\fR method call.
.IP "\fBrebunch\fR [\fIbunch_size\fR]" 4
.IX Item "rebunch [bunch_size]"
Group newly added revisions if no \fIbunch_size\fR is specified. Otherwise
regroup all revisions using a given \fIbunch_size\fR. The default bunch size
may be specified in the constructor.
.Sp
Return the same \fBget\fR does.
.IP "\fBget\fR" 4
.IX Item "get"
Return bunches that is arrayref in scalar context, array in list context.
.Sp
Each bunch is hashref with keys:
.Sp
.Vb 12
\&    revision_descs
\&    name1 daysago1 time1 tz1
\&    name2 daysago2 time2 tz2
\&    size
\&    num_creators
\&    num_other_creators
\&    main_creator
\&    main_email
\&    creator
\&    name
\&    date
\&    summary
.Ve
.Sp
and optionally \*(L"version\*(R", \*(L"is_missing\*(R" and \*(L"filepath\*(R" if applicable.
.Sp
This method implicitly calls \fBrebunch\fR with no parameter if new revision
descriptions were added that are not bunched yet.
.IP "\fBclear\fR" 4
.IX Item "clear"
Clear all bunches and their revision descriptions.
.IP "\fBreverse_revision_descs\fR" 4
.IX Item "reverse_revision_descs"
Effectivelly empty all revision descriptions (both old and new) and readd
them in the reverse order.
.Sp
Return the object, this enables chaining of \fBget\fR or \fBrebunch\fR method call.
.IP "\fBversions\fR" 4
.IX Item "versions"
Return distinct versions participated in all bunches. Return empty arrayref
if not applicable, i.e. if \fIversion\fR is given in the constructor.
.IP "\fBfilepaths\fR" 4
.IX Item "filepaths"
Return distinct filepaths participated in all bunches. Return empty arrayref
if not applicable, i.e. if revision descriptions have no \fIfilepath\fR.
.SH "BUGS"
.IX Header "BUGS"
Waiting for your reports.
.SH "AUTHORS"
.IX Header "AUTHORS"
Mikhael Goikhman (migo@homemail.com\*(--Perl\-GPL/arch\-perl\*(--devel).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information, see Arch::Tree, Arch::Log, Arch::Session,
Arch::Library.