Provided by: lintian_2.5.81ubuntu1_all 
NAME
Lintian::Lab -- Interface to the Lintian Lab
SYNOPSIS
use Lintian::Lab;
# Static lab
my $lab = Lintian::Lab->new ('/var/lib/lintian/static-lab');
if (!$lab->exists) {
$lab->create;
}
$lab->open;
# Fetch a package from the lab
my $lpkg = $lab->get_package ('lintian', 'binary', '2.5.4', 'all');
my $visitor = sub {
my ($lpkg, $pkg_name, $pkg_ver, $pkg_arch) = @_;
# do stuff with that entry
};
$lab->visit_packages ($visitor, 'source');
$lab->close;
DESCRIPTION
This module provides an abstraction from "How and where" packages are placed. It handles
creation and deletion of the Lintian Lab itself as well as providing access to the
entries.
CLASS METHODS
new ([DIR])
Creates a new Lab instance. If DIR is defined it will be used as the path to the lab
and the lab will be in static mode. Otherwise the lab will be in temporary mode and
will point to a temporary directory.
INSTANCE METHODS
dir Returns the absolute path to the base of the lab.
Note: This may return the empty string if either the lab has been deleted or this is a
temporary lab that has not been created yet. In the latter case, "create" or "open"
should be run to get a non-empty value from this method.
is_open
Returns a truth value if this lab is open.
Note: If the lab is open, it also exists. However, if the lab is closed then the lab
may or may not exist (see "exists").
exists
Returns a truth value if the instance points to an existing lab.
Note: This never implies that the lab is open. Though it may imply the lab is closed
(see "is_open").
get_package (NAME, TYPE[, EXTRA]), get_package (PROC)
Fetches an existing package from the lab.
The first argument can be a processable. In that case all other arguments are
ignored.
If the first calling convention is used then this method will search for an existing
package. The EXTRA argument can be used to narrow the search or even to add a new
entry.
EXTRA consists of (in order):
• version
• arch (ignored if TYPE is "source")
If version or arch is omitted (or if it is undef) then that search parameter is
consider a wildcard for "any". Example:
# Returns all eclipse-platform packages with architecture i386 regardless
# of their version (if any)
@ps = $lab->get_package ('eclipse-platform', 'binary', undef, 'i386');
# Returns all eclipse-platform packages with version 3.5.2-11 regardless
# of their architecture (if any)
@ps = $lab->get_package ('eclipse-platform', 'binary', '3.5.2-11');
# Return the eclipse-platform package with version 3.5.2-11 and architecture
# i386 (or undef)
$pkg = $lab->get_package ('eclipse-platform', 'binary', '3.5.2-11', 'i386');
In list context, this returns a list of matches. In scalar context this returns the
first match (if any). Note there is no guaranteed order (e.g. the returned list is
not ordered).
If the second calling convention is used, then this method will search for an entry
matching the processable passed. If such an entry does not exists, a new "non-
existing" entry will be returned. This entry can be created by using the create
method on the entry.
lab_query (QUERY)
Process a given QUERY and return the results from it. A QUERY is a string of the
format:
[TYPE:]NAME[/VERSION[/ARCH]]
TYPE can be one of the regular package type (e.g. "binary") or one of the two special
values "ALL" (default if omitted) or "GROUP". If TYPE is ALL, then the query is one
once for each of package type.
NAME is the name of the package to request. For GROUP queries, this is the name of
the source package. It is not possible to do any kind of wildcards in NAME:
VERSION is the version of the package. For GROUP queries, this is the version of the
source package. If omitted or the string '_', then any version will match.
ARCH is the architecture of the package. For GROUP and "source" queries, ARCH is
ignored (if given). If ARCH is omitted or the string '_', then any package
architecture will match. NB: The ARCH field should match the architecture field of
the entry (which for .changes files usually contains spaces).
lab_query will return a list of entries matching the query. If no entries match, an
empty list will be returned.
visit_packages (VISITOR[, TYPE])
Passes each lab entry to VISITOR. If TYPE is passed, then only entries of that type
are passed.
VISITOR is given a reference to the entry, the package name, the package version and
the package architecture (may be undef for source packages).
generate_diffs (LIST)
Each member of LIST must be a Lintian::Lab::Manifest.
The lab will generate a diff between the given member and its state for the given
package type.
The diffs are accurate until the original manifest is modified or a package is added
or removed to the lab.
repair
Checks the lab contents against the current meta-data and syncs them. The lab must be
open and should not be access while this method is running.
This returns the number of corrections done by this process. If there were any
corrections, the state files are written before returning.
The method may croak if it is unable to do a full check of the lab or if it is unable
to write the corrected metadata.
Note: This may (and generally will) correct "broken" entries by removing them.
create ([OPTS])
Creates a new lab. It will create "dir" if it does not exist. It will also create a
basic empty lab. If this is a temporary lab, this method will also setup the
temporary dir for the lab.
The lab will not be opened by this method. This should be done afterwards by invoking
the "open" method.
OPTS (if present) is a hashref containing options. The following options are
accepted:
keep-lab
If "keep-lab" points to a truth value the temporary directory will not be removed
by closing the lab (nor exiting the application). However, explicitly calling
"remove" will remove the lab.
mode
If present, this will be used as mode for creating directories. Will default to
0777 if not specified. It is passed to mkdir and is thus subject to umask
settings.
Note: This will not create parent directories of "dir" and will croak if these does
not exist.
Note: This may update the value of "dir" as resolving the path requires it to exist.
Note: This does nothing if the lab appears to already exists.
open
Opens the lab and reads the contents into caches. If the lab is temporary and does
not exists, this method will call create to initialize the temporary lab.
This will croak if the lab is already open. It may also croak for the same reasons as
"create" if the lab is temporary.
Note: for static labs, "dir" must point to an existing consistent lab or this will
croak. To open a new lab, please use "create".
Note: It is not possible to pass options to the creation of the temporary lab. If
special options are required, please use "create" directly.
close
Close the lab - all state caches will be flushed to the disk and the lab can no longer
be used. All references to entries in the lab should be considered invalid.
Note: if the lab is a temporary one, this will be deleted unless it was created with
"keep-lab" (see "create").
remove
Removes the lab and everything in it. Any reference to an entry returned from this
lab will immediately become invalid.
If this is a temporary lab, the lab root dir (as returned "dir") will be removed as
well on success. Otherwise the lab root dir will not be removed by this call.
On success, this will return a truth value. If the lab is a temporary lab, the
directory path will be set to the empty string (that is, "dir" will return '').
On error, this method will croak.
If the lab has already been removed (or does not exist), this will return a truth
value.
is_temp
Returns a truth value if lab is a temporary lab.
Note: This returns a truth value, even if the lab was created with the "keep-lab"
property.
Changes to the lab format.
Lab formats up to (and including) "10" used to store the lab format with each entry. The
files in $LAB/info/ were used to list packages from a mirror (dist).
In lab format 11 the lab format is stored in $LAB/info/lab-info. The rest of the files in
$LAB/info/* have been re-purposed to be a list of packages in the lab.
The $LAB/info/lab-info is parsed as a debian control file (See Debian Policy Manual X5.1
for syntax). The consists of a single paragraph and only the following fields are
allowed:
Lab-Format (simple, mandatory)
This field contains the lab format of this lab. Generally this is simply an integer
(though during development non-integers have been used).
Layout (simple, optional)
The layout parameter describes how packages are stored in the lab. Currently the only
accepted value is "pool" and the value is not case-sensitive.
The pool format dictates that packages are stored in:
pool/$l/${name}/${name}_${version}[_${arch}]_${type}/
Note that $arch is left out for source packages, $l is the first letter of the package
name (except if the name starts with "lib", then it is the first 4 letters of the
package name). Whitespace (e.g. " ") are replaced with dashes ("-") and colons (":")
with underscores ("_").
If the field is missing, it defaults to "pool".
It is allowed to use comments in $LAB/info/lab-info as described in the Debian Policy
Manual X5.1.
AUTHOR
Niels Thykier <niels@thykier.net>
Based on the work of various others.