NAME

       Debbugs::Common -- Common routines for all of Debbugs

SYNOPSIS

       use Debbugs::Common qw(:url :html);

DESCRIPTION

       This module is a replacement for the general parts of errorlib.pl.  subroutines in
       errorlib.pl will be gradually phased out and replaced with equivalent (or better)
       functionality here.

FUNCTIONS

UTILITIES

       The following functions are exported by the ":util" tag

   getbugcomponent
            my $file = getbugcomponent($bug_number,$extension,$location)

       Returns the path to the bug file in location $location, bug number $bugnumber and
       extension $extension

   getbuglocation
            getbuglocation($bug_number,$extension)

       Returns the the location in which a particular bug exists; valid locations returned
       currently are archive, db-h, or db. If the bug does not exist, returns undef.

   getlocationpath
            getlocationpath($location)

       Returns the path to a specific location

   get_hashname
            get_hashname

       Returns the hash of the bug which is the location within the archive

   buglog
            buglog($bugnum);

       Returns the path to the logfile corresponding to the bug.

       Returns undef if the bug does not exist.

   bug_status
            bug_status($bugnum)

       Returns the path to the summary file corresponding to the bug.

       Returns undef if the bug does not exist.

   appendfile
            appendfile($file,'data','to','append');

       Opens a file for appending and writes data to it.

   overwritefile
            ovewritefile($file,'data','to','append');

       Opens file.new, writes data to it, then moves file.new to file.

   open_compressed_file
            my $fh = open_compressed_file('foo.gz') or
                 die "Unable to open compressed file: $!";

       Opens a file; if the file ends in .gz, .xz, or .bz2, the appropriate decompression program
       is forked and output from it is read.

       This routine by default opens the file with UTF-8 encoding; if you want some other
       encoding, specify it with the second option.

   getparsedaddrs
            my $address = getparsedaddrs($address);
            my @address = getparsedaddrs($address);

       Returns the output from Mail::Address->parse, or the cached output if this address has
       been parsed before. In SCALAR context returns the first address parsed.

   getmaintainers
            my $maintainer = getmaintainers()->{debbugs}

       Returns a hashref of package => maintainer pairs.

   getmaintainers_reverse
            my @packages = @{getmaintainers_reverse->{'don@debian.org'}||[]};

       Returns a hashref of maintainer => [qw(list of packages)] pairs.

   package_maintainer
            my @s = package_maintainer(source => [qw(foo bar baz)],
                                       binary => [qw(bleh blah)],
                                      );

       source -- scalar or arrayref of source package names to return maintainers for, defaults
       to the empty arrayref.
       binary -- scalar or arrayref of binary package names to return maintainers for;
       automatically returns source package maintainer if the package name starts with 'src:',
       defaults to the empty arrayref.
       reverse -- whether to return the source/binary packages a maintainer maintains instead
       rehash -- whether to reread the maintainer and source maintainer files; defaults to 0

   getpseudodesc
            my $pseudopkgdesc = getpseudodesc(...);

       Returns the entry for a pseudo package from the $config{pseudo_desc_file}. In cases where
       pseudo_desc_file is not defined, returns an empty arrayref.

       This function can be used to see if a particular package is a pseudopackage or not.

   sort_versions
            sort_versions('1.0-2','1.1-2');

       Sorts versions using AptPkg::Versions::compare if it is available, or
       Debbugs::Versions::Dpkg::vercmp if it isn't.

DATE

           my $english = secs_to_english($seconds);
           my ($days,$english) = secs_to_english($seconds);

       XXX This should probably be changed to use Date::Calc

LOCK

       These functions are exported with the :lock tag

   filelock
            filelock($lockfile);
            filelock($lockfile,$locks);

       FLOCKs the passed file. Use unfilelock to unlock it.

       Can be passed an optional $locks hashref, which is used to track which files are locked
       (and how many times they have been locked) to allow for cooperative locking.

   simple_filelock
           my ($fh,$t_lockfile,$errors) =
               simple_filelock($lockfile,$count,$wait);

       Does a flock of lockfile. If $count is zero, does a blocking lock.  Otherwise, does a non-
       blocking lock $count times, waiting $wait seconds in between.

       In list context, returns the lockfile filehandle, lockfile name, and any errors which
       occured.

       When the lockfile filehandle is undef, locking failed.

       These lockfiles must be unlocked manually at process end.

   simple_unlockfile
            simple_unlockfile($fh,$lockfile);

   unfilelock
            unfilelock()
            unfilelock($locks);

       Unlocks the file most recently locked.

       Note that it is not currently possible to unlock a specific file locked with filelock.

   lockpid
             lockpid('/path/to/pidfile');

       Creates a pidfile '/path/to/pidfile' if one doesn't exist or if the pid in the file does
       not respond to kill 0.

       Returns 1 on success, false on failure; dies on unusual errors.

   checkpid
            checkpid('/path/to/pidfile');

       Checks a pid file and determines if the process listed in the pidfile is still running.
       Returns the pid if it is, 0 if it isn't running, and undef if the pidfile doesn't exist or
       cannot be read.

QUIT

       These functions are exported with the :quit tag.

   quit
            quit()

       Exits the program by calling die.

       Usage of quit is deprecated; just call die instead.

MISC

       These functions are exported with the :misc tag

   make_list
            LIST = make_list(@_);

       Turns a scalar or an arrayref into a list; expands a list of arrayrefs into a list.

       That is, make_list([qw(a b c)]); returns qw(a b c); make_list([qw(a b)],[qw(c d)] returns
       qw(a b c d);

   english_join
            print english_join(list => \@list);
            print english_join(\@list);

       Joins list properly to make an english phrase.

       normal -- how to separate most values; defaults to ', '
       last -- how to separate the last two values; defaults to ', and '
       only_two -- how to separate only two values; defaults to ' and '
       list -- ARRAYREF values to join; if the first argument is an ARRAYREF, it's assumed to be
       the list of values to join

       In cases where "list" is empty, returns ''; when there is only one element, returns that
       element.

   globify_scalar
            my $handle = globify_scalar(\$foo);

       if $foo isn't already a glob or a globref, turn it into one using IO::Scalar. Gives a new
       handle to /dev/null if $foo isn't defined.

       Will carp if given a scalar which isn't a scalarref or a glob (or globref), and return
       /dev/null. May return undef if IO::Scalar or IO::File fails. (Check $!)

       The scalar will fill with octets, not perl's internal encoding, so you must use
       decode_utf8() after on the scalar, and encode_utf8() on it before. This appears to be a
       bug in the underlying modules.

   cleanup_eval_fail()
            print "Something failed with: ".cleanup_eval_fail($@);

       Does various bits of cleanup on the failure message from an eval (or any other die
       message)

       Takes at most two options; the first is the actual failure message (usually $@ and
       defaults to $@), the second is the debug level (defaults to $DEBUG).

       If debug is non-zero, the code at which the failure occured is output.

   hash_slice
            hash_slice(%hash,qw(key1 key2 key3))

       For each key, returns matching values and keys of the hash if they exist