File Coverage

blib/lib/Gentoo/VDB.pm
Criterion Covered Total %
statement 19 20 95.0
branch 2 4 50.0
condition 1 2 50.0
subroutine 8 8 100.0
pod 5 5 100.0
total 35 39 89.7


line stmt bran cond sub pod time code
1 3     3   159466 use 5.006; # our
  3         9  
2 3     3   15 use strict;
  3         4  
  3         72  
3 3     3   13 use warnings;
  3         9  
  3         1184  
4              
5             package Gentoo::VDB;
6              
7             our $VERSION = '0.001002';
8              
9             # ABSTRACT: Simple API for querying VDB Implementations
10              
11             # AUTHORITY
12              
13             # Note: VDB format is not well defined, and its an implementation
14             # detail of Portage itself, which fortunately is mostly similar to
15             # the implementations in other Portage clients.
16             #
17             # However, there's no requirement that the VDB definition be any
18             # specific way, as the only PMS requirement is that every PMS
19             # implementation *should* have a VDB of some description, but
20             # the definition is up to the implementer.
21             #
22             # Hence, all this design is to make that doable.
23             our $BACKENDS = {
24             'portage' => sub {
25             require Gentoo::VDB::Portage;
26             return 'Gentoo::VDB::Portage';
27             },
28             };
29              
30             sub new {
31 3     3 1 18476 my ( $self, @args ) = @_;
32 3 50       15 my $config = { ref $args[0] ? %{ $args[0] } : @args };
  0         0  
33 3   50     22 my $backend_name = delete $config->{backend} || 'portage';
34             die "Unknown backend $backend_name"
35 3 50       13 unless exists $BACKENDS->{$backend_name};
36 3         14 my $backend_module = $BACKENDS->{$backend_name}->();
37 3         11 my $backend = $backend_module->new($config);
38 3         16 return bless { backend => $backend, config => $config }, $self;
39             }
40              
41             # ->categories() -> list of CAT
42 6     6 1 43 sub categories { $_[0]->{backend}->categories( @_[ 1 .. $#_ ] ) }
43              
44             # ->packages() -> list of CAT/PN-V
45             # ->packages({ in => 'dev-perl' }) -> list of CAT/PN-V in dev-perl/
46 8     8 1 37 sub packages { $_[0]->{backend}->packages( @_[ 1 .. $#_ ] ) }
47              
48             # ->properties({ for => 'cat/pn-v' }) -> list of HASH
49 1     1 1 6 sub properties { $_[0]->{backend}->properties( @_[ 1 .. $#_ ] ) }
50              
51             # ->get_property({ for => 'cat/pn-v', property => 'propname' }) -> HASH
52 32     32 1 60570 sub get_property { $_[0]->{backend}->get_property( @_[ 1 .. $#_ ] ) }
53              
54             1;
55              
56             =head1 NAME
57              
58             Gentoo::VDB - Simple API for querying Gentoo's installed-package database
59              
60             =head1 SYNOPSIS
61              
62             use Gentoo::VDB;
63             my $vdb = Gentoo::VDB->new();
64              
65             my (@categories) = $vdb->categories;
66             ## Note: next line is slow
67             my (@packages) = $vdb->packages;
68             ## Much faster
69             my (@packages) = $vdb->packages({ in => 'dev-perl' });
70              
71             =head1 METHODS
72              
73             =head2 C
74              
75             my $instance = Gentoo::VDB->new(\%ARGS);
76              
77             =head2 C
78              
79             Returns a list of single-token category names that are
80             valid.
81              
82             my (@categories) = $vdb->categories;
83              
84             Note: Categories that have no definite installed
85             packages are omitted, even if their dirs are present.
86              
87             This is mostly because this is the only way to disambiguate between
88             a temporary directory and a category.
89              
90             It is mostly equivalent to
91              
92             find /var/db/pkg \
93             -maxdepth 1 \
94             -mindepth 1 \
95             -not -empty \
96             -printf '%f\n'
97              
98             And should be similarly performant.
99              
100             =head2 C
101              
102             Returns a list of valid packages in C form.
103              
104             my ( @packages ) = $vdb->packages();
105             # Show only packages in dev-perl, much faster
106             my ( @packages ) = $vdb->packages({ in => 'dev-perl' });
107              
108             This is mostly equivalent to:
109              
110             find /var/db/pkg \
111             -maxdepth 2 \
112             -mindepth 2 \
113             -not -empty \
114             -printf '%p\n' | \
115             sed -r 's|^.*/([^/]+)/([^/]+)$|\1/\2|'
116             or
117              
118             find /var/db/pkg/dev-perl \
119             -maxdepth 1 \
120             -mindepth 1 \
121             -not -empty \
122             -printf '%p\n' | \
123             sed -r 's|^.*/([^/]+)/([^/]+)$|\1/\2|'
124              
125             And should be similarly performant.
126              
127             =head2 C
128              
129             Returns a list of hash entries describing properties of the given C
130              
131             my ( @properties ) = $vdb->properties({ for => 'dev-lang/perl-5.22.1-r1' });
132              
133             A property contains:
134              
135             {
136             property => .... # the name of the property ( backend specific )
137             label => .... # usually the same as 'property' but is defined by
138             # Gentoo::VDB, some special cases like
139             # 'special:source_ebuild' and 'unknown:' . $property
140             # exist.
141             type => .... # Gentoo::VDB specific hint for decoding the
142             # data.
143             for => .... # CAT/PN-V entry
144              
145             # Selectively ...
146             content => # For "generic" types like "file", this is generally
147             # a MIME type for the undelying decoded data.
148             # ie: No VDB Specific decoding hint, just amorphous
149             # blob of bytes that have to be handled thusly
150             # eg: text/plain, application/octet-stream
151              
152             encoding => # if the data has some sort of protocol encoding,
153             # for instance, a bzip encoded text source
154             # this will be populated respectively, eg:
155             # application/x-bzip2
156             }
157              
158             A given record may overlap with another record in part, eg: One "property"
159             may yield 2 different hashes with different labels and types.
160              
161             But this is just an idea at this stage, and there's no implementation behind it.
162              
163             Mostly pertinent for large objects like `environment.bz2` that can yield additional
164             metadata.
165              
166             =head2 C
167              
168             Fetch a given property as a string blob
169              
170             my $prop = $vdb->get_property({ for => 'dev-lang/perl-5.22.1-r1', property => 'BackendName' });
171              
172             =head1 AUTHOR
173              
174             Kent Fredric
175              
176             =head1 LICENSE
177              
178             This software is copyright (c) 2016 by Kent Fredric.
179              
180             This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
181              
182             =cut