Arch::RevisionBunches(3pm)				User Contributed Perl Documentation				Arch::RevisionBunches(3pm)

NAME

       Arch::RevisionBunches - manage bunches of related revisions

SYNOPSIS

	   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}
";
	       print "	  $_->{name}	$_->{summary}
"
		   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)
";
	   }

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.

       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.

METHODS

       The following methods are available:

       new, init, add_revision_descs, versions, rebunch, get, clear, reverse_revision_descs, versions, filepaths.

       new [%args]
	   Construct Arch::RevisionBunches object.

	   The %args are passed to init method.

       init [%args]
	   The %args keys may be bunch_size (to use as the default bunch size instead of 50), max_sumlen (maximal summary length to keep including
	   trailing ellipsis, must be greater than 5), version (if set, then all revisions are assumed to be of one version, otherwise multiple
	   versions are assumed), final_revision and final_filepath (the final revision and filepath for which the revision bunches are
	   constructed). These last two %args keys are not really used yet.

       add_revision_descs [%constant_fields]
	   Add revision descriptions that is arrayref of hashes. See other classes that return such revision descriptions. If the %constant_fields
	   is given, then add these to all revision descriptions (rarely needed).

	   Return the object, this enables chaining of get or rebunch method call.

       rebunch [bunch_size]
	   Group newly added revisions if no bunch_size is specified. Otherwise regroup all revisions using a given bunch_size. The default bunch
	   size may be specified in the constructor.

	   Return the same get does.

       get Return bunches that is arrayref in scalar context, array in list context.

	   Each bunch is hashref with keys:

	       revision_descs
	       name1 daysago1 time1 tz1
	       name2 daysago2 time2 tz2
	       size
	       num_creators
	       num_other_creators
	       main_creator
	       main_email
	       creator
	       name
	       date
	       summary

	   and optionally "version", "is_missing" and "filepath" if applicable.

	   This method implicitly calls rebunch with no parameter if new revision descriptions were added that are not bunched yet.

       clear
	   Clear all bunches and their revision descriptions.

       reverse_revision_descs
	   Effectivelly empty all revision descriptions (both old and new) and readd them in the reverse order.

	   Return the object, this enables chaining of get or rebunch method call.

       versions
	   Return distinct versions participated in all bunches. Return empty arrayref if not applicable, i.e. if version is given in the
	   constructor.

       filepaths
	   Return distinct filepaths participated in all bunches. Return empty arrayref if not applicable, i.e. if revision descriptions have no
	   filepath.

BUGS

       Waiting for your reports.

AUTHORS

       Mikhael Goikhman (migo@homemail.com--Perl-GPL/arch-perl--devel).

SEE ALSO

       For more information, see Arch::Tree, Arch::Log, Arch::Session, Arch::Library.

perl v5.10.1							    2005-02-21						Arch::RevisionBunches(3pm)