summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorFlorian Pritz <bluewind@xinu.at>2018-11-19 00:03:42 +0100
committerFlorian Pritz <bluewind@xinu.at>2018-11-19 00:03:42 +0100
commit12201461e927af015caefc583a2ab5514c63668b (patch)
treeabe8cd8efbe54f333096a99201dc0acdade68cef
parente93e80dede905b653e35b8bb4e8f31f0c58719bd (diff)
downloadApp-ArchLinux-PackagerTools-12201461e927af015caefc583a2ab5514c63668b.tar.gz
App-ArchLinux-PackagerTools-12201461e927af015caefc583a2ab5514c63668b.tar.xz
Add documentation
Signed-off-by: Florian Pritz <bluewind@xinu.at>
-rw-r--r--lib/App/ArchLinux/PackagerTools.pm25
-rw-r--r--lib/App/ArchLinux/PackagerTools/CPAN.pm96
-rw-r--r--lib/App/ArchLinux/PackagerTools/Pacman.pm54
3 files changed, 144 insertions, 31 deletions
diff --git a/lib/App/ArchLinux/PackagerTools.pm b/lib/App/ArchLinux/PackagerTools.pm
index d8cb89d..0a45bb8 100644
--- a/lib/App/ArchLinux/PackagerTools.pm
+++ b/lib/App/ArchLinux/PackagerTools.pm
@@ -49,10 +49,35 @@ method new_no_defaults($class: $deps = {}) {
return $self;
}
+=head3 get_distributions_in_repo
+
+ my $dists = $app->get_distributions_in_repo();
+
+Return an arrayref of hashrefs with CPAN distribution information. See
+L<App::ArchLinux::PackagerTools::Pacman/"get_perl_distributions">.
+
+=cut
+
method get_distributions_in_repo() {
return $self->{deps}->{pacman}->get_perl_distributions();
}
+=head3 get_updateable_packages
+
+ my $distribution_names = ['App::ArchLinux::PackagerTools', 'DBI'];
+ my $packages = $app->get_updateable_packages($distribution_names);
+ print $packages[0]->{dist_name};
+ print $packages[0]->{pkgname};
+ print $packages[0]->{repo_version};
+ print $packages[0]->{cpan_version};
+
+Accepts a list of package names and returns a list of packages that can be
+updated. The returned packages contain the name of the distribution, the name
+of the pacman package, and the versions of each, the pacman package (which is
+older) and the CPAN distribution.
+
+=cut
+
method get_updateable_packages($distribution_names) {
my @packages;
for my $dist_name ($distribution_names->@*) {
diff --git a/lib/App/ArchLinux/PackagerTools/CPAN.pm b/lib/App/ArchLinux/PackagerTools/CPAN.pm
index 175e218..c2dcf4a 100644
--- a/lib/App/ArchLinux/PackagerTools/CPAN.pm
+++ b/lib/App/ArchLinux/PackagerTools/CPAN.pm
@@ -17,19 +17,21 @@ App::ArchLinux::PackagerTools::CPAN - Methods to interact with CPAN
=head1 SYNOPSIS
-use App::ArchLinux::PackagerTools::CPAN;
+ use App::ArchLinux::PackagerTools::CPAN;
-# synopsis...
+ my $cpan = App::ArchLinux::PackagerTools::CPAN->new();
=head1 DESCRIPTION
-# longer description...
+Utility methods to search for distributions in CPAN. Maintains an internal
+database that allows to perform case-insensitive searches for distribution
+names.
=head1 METHODS
=head2 new
- App::ArchLinux::PackagerTools::CPAN->new();
+ my $cpan = App::ArchLinux::PackagerTools::CPAN->new();
Returns a new instance.
@@ -54,6 +56,8 @@ method new_no_defaults($class: $deps = {}) {
=head3 is_newer_version_available
+ if ($cpan->is_newer_version_available($dist_name, $version)) {...}
+
Return 1 if a newer version of the distribution is available, 0 otherwise.
=cut
@@ -69,6 +73,66 @@ method is_newer_version_available($dist_name, $version) {
}
}
+=head3 search_dist
+
+ my $name = "App::ArchLinux::PackagerTools";
+ my $dist = $cpan->search_dist($name);
+
+Search for a distribution that matches the supplied, case-insensitive name.
+Either returns a hash that contains the dist_name and version of the found
+distribution or undef if none is found.
+
+Note that it searches for a distribution only, not for a module.
+
+=cut
+
+method search_dist($name) {
+ $name =~ s/::/-/g;
+ $log->tracef("Searching for CPAN distribution matching '%s'", $name);
+
+ my $index_name = $self->{dist_lc_map}->{lc($name)};
+ if (defined $index_name) {
+ return $self->{dists}->{$index_name};
+ }
+
+ return;
+}
+
+=head3 get_dist
+
+ my $name = "App::ArchLinux::PackagerTools";
+ my $dist = $cpan->get_dist($name);
+
+Return a distribution that matches the supplied, case-insensitive name.
+Returns a hash that contains the dist_name and version of the found
+distribution or raises an exception if no distribution is found.
+
+Note that it searches for a distribution only, not for a module.
+
+=cut
+
+method get_dist($dist_name) {
+ $dist_name =~ s/::/-/g;
+ $log->tracef("Getting CPAN data for distribution '%s'", $dist_name);
+
+ my $index_name = $self->{dist_lc_map}->{lc($dist_name)};
+ if (defined $index_name) {
+ return $self->{dists}->{$index_name};
+ }
+
+ croak $log->errorf("Failed to find distribution with name %s", $dist_name);
+}
+
+=head2 Private Methods
+
+=head3 _build_dist_index
+
+ $self->_build_dist_index();
+
+Set up the internal index of CPAN distributions
+
+=cut
+
method _build_dist_index() {
$self->{deps}->{cpanplus_backend}->reload_indices();
# TODO download pacakges list ourselves instead of using cpanplus for it? We may need cpanplus for other features later so keeping it is probably also fine.
@@ -125,30 +189,6 @@ method _build_dist_index() {
}
}
-method search_dist($name) {
- $name =~ s/::/-/g;
- $log->tracef("Searching for CPAN distribution matching '%s'", $name);
-
- my $index_name = $self->{dist_lc_map}->{lc($name)};
- if (defined $index_name) {
- return $self->{dists}->{$index_name};
- }
-
- return;
-}
-
-method get_dist($dist_name) {
- $dist_name =~ s/::/-/g;
- $log->tracef("Getting CPAN data for distribution '%s'", $dist_name);
-
- my $index_name = $self->{dist_lc_map}->{lc($dist_name)};
- if (defined $index_name) {
- return $self->{dists}->{$index_name};
- }
-
- croak $log->errorf("Failed to find distribution with name %s", $dist_name);
-}
-
1;
__END__
diff --git a/lib/App/ArchLinux/PackagerTools/Pacman.pm b/lib/App/ArchLinux/PackagerTools/Pacman.pm
index 765746e..8a26407 100644
--- a/lib/App/ArchLinux/PackagerTools/Pacman.pm
+++ b/lib/App/ArchLinux/PackagerTools/Pacman.pm
@@ -18,8 +18,7 @@ App::ArchLinux::PackagerTools::Pacman - Methods to interact with pacman
=head1 DESCRIPTION
This module allows to query pacman for a list of packages in the repository and
-extract a list of perl distributions that are part of the repository.
-
+extract a list of CPAN distributions that are part of the repository.
=head1 METHODS
@@ -27,7 +26,7 @@ extract a list of perl distributions that are part of the repository.
=head3 new
- App::ArchLinux::PackagerTools::Pacman->new();
+ my $pacman = App::ArchLinux::PackagerTools::Pacman->new();
Returns a new instance.
@@ -55,6 +54,8 @@ method new_no_defaults($class: $deps = {}) {
=head3 get_packages
+ my $packages = $pacman->get_packages();
+
Returns an arrayref of package hashes. Each package hash contains at least the
pkgname and pkgver keys.
@@ -72,12 +73,30 @@ method get_packages() {
return \@packages;
}
+=head3 get_perl_packages
+
+ my $packages = $pacman->get_perl_packages();
+
+Similar to get_packages(), but returns a list filtered to perl packages.
+
+=cut
+
method get_perl_packages() {
my @packages = grep {$_->{pkgname} =~ /^perl-/} $self->get_packages->@*;
$log->debugf("Found %d perl packages", scalar(@packages));
return \@packages;
}
+=head3 get_perl_distributions
+
+ my $dists = $pacman->get_perl_distributions();
+
+Returns a list of CPAN distributions that are in the pacman repo. Returns an
+arrayref of hashrefs that contain dist_name and version keys.
+
+=cut
+
+
method get_perl_distributions() {
my @distributions;
@@ -95,6 +114,14 @@ method get_perl_distributions() {
return \@distributions;
}
+=head3 get_package_version
+
+ my $version = $pacman->get_package_version($pkgname);
+
+Return the version of a package in the pacman package repositories.
+
+=cut
+
method get_package_version($pkgname) {
# TODO do not fork expac for each package here! works for now, but it's sloooow
my $version = `expac -S -1 '%v' -- '$pkgname'`;
@@ -102,13 +129,34 @@ method get_package_version($pkgname) {
return $version;
}
+=head3 get_perl_pkgname
+
+ my $pkgname = $pacman->get_perl_pkgname($dist_name);
+
+Return the pacman package name for a CPAN distribution. In most cases, this
+prefixes the distribution with "perl-" and replaces "::" with "-", but it may
+also return other names if they are mapped differently.
+
+=cut
+
method get_perl_pkgname($dist_name) {
+ # TODO implement mapping
my $pkgname = lc($dist_name);
$pkgname =~ s/::/-/g;
$pkgname = "perl-$pkgname";
return $pkgname;
}
+=head3 get_perl_distribution_version
+
+ my $version = $pacman->get_perl_distribution_version($dist_name);
+
+Return the version of a CPAN distribution's pacman package. This removes
+pacman-specific information from the pacman's package version.
+
+=cut
+
+
method get_perl_distribution_version($dist_name) {
my $pkgname = $self->get_perl_pkgname($dist_name);
my $version = $self->get_package_version($pkgname);