From 12201461e927af015caefc583a2ab5514c63668b Mon Sep 17 00:00:00 2001 From: Florian Pritz Date: Mon, 19 Nov 2018 00:03:42 +0100 Subject: Add documentation Signed-off-by: Florian Pritz --- lib/App/ArchLinux/PackagerTools.pm | 25 ++++++++ lib/App/ArchLinux/PackagerTools/CPAN.pm | 96 ++++++++++++++++++++++--------- lib/App/ArchLinux/PackagerTools/Pacman.pm | 54 ++++++++++++++++- 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. + +=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); -- cgit v1.2.3-24-g4f1b