##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

DiaColloDB::Upgrade - DiaColloDB utilities: auto-magic upgrades: top level

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 use DiaColloDB::Upgrade;
 
 @packages = $CLASS_OR_OBJECT->available();
 @needed   = $CLASS_OR_OBJECT->needed($dbdir,  \%opts?, @packages);
 @which    = $CLASS_OR_OBJECT->which($dbdir,   \%opts?, @packages);
 $bool     = $CLASS_OR_OBJECT->upgrade($dbdir, \%opts?, @packages);
 

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

DiaColloDB::Upgrade
is a convenience package for performing automatic in-place upgrades to
L<DiaColloDB|DiaColloDB> database directories,
used by the
L<dcdb-upgrade.perl|dcdb-upgrade.perl> script included in the DiaColloDB distribution.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Upgrade: Globals
=pod

=head2 Globals

=over 4

=item Variable: @ISA

DiaColloDB::Upgrade
inherits from
L<DiaColloDB::Logger|DiaColloDB::Logger>.

=item Variable: @upgrades

An ARRAY of available automagic upgrade sub-packages
(C<DiaColloDB::Upgrade::> suffixes).

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Upgrade: Top-level
=pod

=head2 Top-level

=over 4

=item available

 @upgrades = $CLASS_OR_OBJECT->available();

Returns list of available upgrade-packages (C<DiaColloDB::Upgrade::> suffixes).

=item needed

 @needed = $CLASS_OR_OBJECT->needed($dbdir, \%opts?, @packages);

Returns list of those upgrade-packages in C<@packages> which are applicable to the
local L<DiaColloDB|DiaColloDB> index in C<$dbdir>.
C<%opts> are passed to upgrade-package L<new|DiaColloDB::Upgrade::Base/new>() methods.

=item which

 @which = $CLASS_OR_OBJECT->which($dbdir, \%opts?);

Returns a list of upgrades previously applied to C<$dbdir>.
Returned list is created by parsing C<"upgraded"> field from C<"$dbdir/header.json">.
If the upgrade-item C<"by"> keyword is the name of a package inheriting from L<DiaColloDB::Upgrade::Base|DiaColloDB::Upgrade::Base>,
a new object will be created and appended to the returned list; otherwise the
parsed HASH-ref is returned as-is.
C<%opts> are passed to upgrade-package L<new|DiaColloDB::Upgrade::Base/new>() methods.

=item upgrade

 $bool = $CLASS_OR_OBJECT->upgrade($dbdir, \%opts?, \@upgrades_or_pkgs);

Force-applies upgrades in C<@upgrades> to the local L<DiaColloDB|DiaColloDB> index in C<$dbdir>;
C<%opts> are passed to upgrade-package L<new|DiaColloDB::Upgrade::Base/new>() methods.

=back

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<dcdb-upgrade.perl(1)|dcdb-upgrade.perl>,
L<DiaColloDB::Upgrade::Base(3pm)|DiaColloDB::Upgrade::Base>,
L<DiaColloDB::Upgrade::v0_04_dlimits(3pm)|DiaColloDB::Upgrade::v0_04_dlimits>,
L<DiaColloDB::Upgrade::v0_09_multimap(3pm)|DiaColloDB::Upgrade::v0_09_multimap>,
L<DiaColloDB::Upgrade::v0_10_x2t(3pm)|DiaColloDB::Upgrade::v0_10_x2t>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
