NAME

       Debbugs::Packages - debbugs binary/source package handling

DESCRIPTION

       The Debbugs::Packages module provides support functions to map binary packages to their
       corresponding source packages and vice versa. (This makes sense for software
       distributions, where developers may work on a single source package which produces several
       binary packages for use by users; it may not make sense in other contexts.)

METHODS

   getpkgsrc
       Returns a reference to a hash of binary package names to their corresponding source
       package names.

   getpkgcomponent
       Returns a reference to a hash of binary package names to the component of the archive
       containing those binary packages (e.g. "main", "contrib", "non-free").

   getsrcpkgs
       Returns a list of the binary packages produced by a given source package.

   binary_to_source
            binary_to_source(package => 'foo',
                             version => '1.2.3',
                             arch    => 'i386');

       Turn a binary package (at optional version in optional architecture) into a single (or
       set) of source packages (optionally) with associated versions.

       By default, in LIST context, returns a LIST of array refs of source package, source
       version pairs corresponding to the binary package(s), arch(s), and verion(s) passed.

       In SCALAR context, only the corresponding source packages are returned, concatenated with
       ', ' if necessary.

       If no source can be found, returns undef in scalar context, or the empty list in list
       context.

       binary -- binary package name(s) as a SCALAR or ARRAYREF
       version -- binary package version(s) as a SCALAR or ARRAYREF; optional, defaults to all
       versions.
       arch -- binary package architecture(s) as a SCALAR or ARRAYREF; optional, defaults to all
       architectures.
       source_only -- return only the source name (forced on if in SCALAR context), defaults to
       false.
       scalar_only -- return a scalar only (forced true if in SCALAR context, also causes
       source_only to be true), defaults to false.
       cache -- optional HASHREF to be used to cache results of binary_to_source.

   sourcetobinary
       Returns a list of references to triplets of binary package names, versions, and
       architectures corresponding to a given source package name and version.  If the given
       source package name and version cannot be found in the database but the source package
       name is in the unversioned package-to-source map file, then a reference to a binary
       package name and version pair will be returned, without the architecture.

   getversions
       Returns versions of the package in a distribution at a specific architecture

   get_versions
            get_versions(package=>'foopkg',
                         dist => 'unstable',
                         arch => 'i386',
                        );

       Returns a list of the versions of package in the distributions and architectures listed.
       This routine only returns unique values.

       package -- package to return list of versions
       dist -- distribution (unstable, stable, testing); can be an arrayref
       arch -- architecture (i386, source, ...); can be an arrayref
       time -- returns a version=>time hash at which the newest package matching this version was
       uploaded
       source -- returns source/version instead of just versions
       no_source_arch -- discards the source architecture when arch is not passed. [Used for
       finding the versions of binary packages only.] Defaults to 0, which does not discard the
       source architecture. (This may change in the future, so if you care, please code
       accordingly.)
       return_archs -- returns a version=>[archs] hash indicating which architectures are at
       which versions.
       largest_source_version_only -- if there is more than one source version in a particular
       distribution, discards all versions but the largest in that distribution. Defaults to 1,
       as this used to be the way that the Debian archive worked.

       When called in scalar context, this function will return hashrefs or arrayrefs as
       appropriate, in list context, it will return paired lists or unpaired lists as
       appropriate.

   makesourceversions
            @{$cgi_var{found}} = makesourceversions($cgi_var{package},undef,@{$cgi_var{found}});

       Canonicalize versions into source versions, which have an explicitly named source package.
       This is used to cope with source packages whose names have changed during their history,
       and with cases where source version numbers differ from binary version numbers.

   make_source_versions
            make_source_versions(package => 'foo',
                                 arch    => 'source',
                                 versions => '0.1.1',
                                 guess_source => 1,
                                 warnings => \$warnings,
                                );

       An extended version of makesourceversions (which calls this function internally) that
       allows for multiple packages, architectures, and outputs warnings and debugging
       information to provided SCALARREFs or HANDLEs.

       The guess_source option determines whether the source package is guessed at if there is no
       obviously correct package. Things that use this function for non-transient output should
       set this to false, things that use it for transient output can set this to true.
       Currently it defaults to true, but that is not a sane option.