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.