
==== OVERVIEW ====

  The Regexp::Common::debian is collection of REs for various strings
  found in the Debian Porject <http://debian.org>.  It's no way intended
  to be a validation tool.

  Since Regexp::Common::debian uses our declaration that was introduced
  in ``v5.6.0'', R::C::d needs ``v5.6.0'' to run.  I should admit
  though, I'll do my best to support perl distributed with ``stable''
  release of Debian GNU/Linux (at time of writing it is ``v5.10.0''). 
  And I'll try hard to support perl in ``oldstable'' (``v5.8.8'').


==== INSTALL ====

  The R::C::d builds with Module::Build.

      $ perl Build.PL
      $ perl Build
      $ perl Build test
      $ perl Build install

  Since we're about strings we need a lots of strings to test against
  (Test::More, unspecified version).  To access them easily (it's all
  about reuse, not implemented yet) I need an apropriate storage. 
  Accidentally it's YAML::Tiny (unspecified version).

  ``v0.2.1'' Reading reports of cpantesters I've got to conclusion that
  YAML::Tiny isn't popular.  And avoiding installing (or unability to
  install (there could be reasons)) build requirements isn't that
  uncommon.  Although I experience a strong belief that some YAML reader
  happens to be installed anyway.  And still I can't find a way to
  specify that *%build_requires* one of but all known to me YAML reader.
  So here is a dirty trick.  t::TestSuite attempts to require() one of
  known (to me, see below) YAML reader.  Then (upon initial ``perl
  Build.PL'') t::TestSuite is asked what it has found (if nothing then
  cosmetic ``Compilation failed in require'' message will be seen).  And
  one what has been found will be added to *%build_requires*; If nothing
  then fair YAML::Tiny will be added.  (I think it's fair because
  YAML::Tiny is pure-Perl, small footprint, and no dependencies.)

  (note) I'm talking about "known to me YAML readers" because I've found
  out that different YAML readers treat source differently.  So I
  attempt to keep t/*.yaml files semantically equal and sintactically
  correct.  Hopefully there're no differences among versions in wild.

  ``v0.2.2'' Various (all, except t/preferences.t and t/sourceslist.t)
  test-units know a magic command '$ENV{RCD_ASK_DEBIAN}'.  Apply it this
  way (enabling all possible external inquiries):

      RCD_ASK_DEBIAN=all ./Build test

  or this (separate keys with any non-word):

      RCD_ASK_DEBIAN=binary,architecture ./Build test

  When applied a test-unit would ask Debian's commands or inspect Debian
  specific files for information the test-unit is interested in.  For
  obvious reasons that magic will fail on non-Debian system; So don't. 
  Although if used correctly that could warn of strange ('not known
  before') compatibility problems.  Details:

: architecture of t/architecture.t
      This asks ``dpkg-architecture -L'' for list of known architectures
      (per Section 11.1 of debian-policy).  That wouldn't find
      architectures dropped (had that happen ever?) but omissions won't
      stay unnoted anymore.

: binary of t/archive.misc.t
      ``v0.2.3'' Inspects all records in /var/lib/apt/lists/*_Packages,
      extracts *Filename:* entries matches all of them against
      ``m/^$RE{debian}{archive}{binary}$/''.  All (if any) failure will
      be reported at the end.

: changelog of t/changelog.t
      ``v0.2.8'' That will inspect /usr/share/doc/*/changelog.Debian
      files.  To do a complete scan it would take loads of time
      (really).  You should understand, that's not enough to just run
      through changelogs.  It has to be verified that none entry is
      skipped.  The only reliable (for sake of interface, and,
      trivially, presence) source of verification is
      ``dpkg-parsechangelog''.  And here's the fork-mare.  ``perl''
      forks ``shell'', then ``perl'', then ``perl'' again.  There seems
      to be fork of ``tail'' too.  And that for each entry.  (Not to
      count ``gunzip'' to decompress the changelog.) ``loadavg'' climbs
      over 1.50..2.00 You've got the picture.  Although that's where
      choice begins.

:     *changelog*
          ``v0.2.9'' That defaults to ``changelog=5''.  See below.

:     *changelog=package*
          Only one changelog will be checked.  The one that ``eq''s. 
          The package name is picked from directory name.

:     *changelog=a*
          Only those changelogs will be checked that ``m/^a/''.

:     *changelog=5*
          ``v0.2.9'' That will check all changelogs, although it will
          look no more than requested number of entries.  (~15min for
          ~1200 changelogs (and that's with *APT::Install-Recommends*
          disabled).) And that has a perfect sense.  Do you know that
          ``cron'' once changed it's name to ``Cron'' (beware leading
          block) (cron_3.0pl1-46)? C'mon, it has happened 12 (tweleve)
          years ago! I can't degrade $RE{d}{changelog} to accommodate
          that.  (And you know what? That default is pretty fair
          (liblog-log4perl-perl_1.16-1).  Probably it should look for
          time passed but entry number.)

:     *changelog=-5*
          ``v0.2.9'' That's different.  It will check as many entries as
          possible (there are changelogs what $RE{d}{changelog} finds
          out more entries than dpkg-parsechangelog (``dpkg_1.2.13'' vs
          ``dpkg_0.93.79''), but if the offending record is more than
          that far from top then it's reported and otherwise ignored.

:     *changelog=0*
          (bug) ``v0.2.9'' That will check all changelogs, check all
          possible entries and BAIL_OUT off first failure.  Shortly --
          don't.  You're warned.  (Although, do it.  t/changelog.t will
          give up pretty soon.)

      To slightly sweeten all that, t/changelog.t attempts to filter
      duplicates.  And it BAIL_OUTs upon first failure.

: package of t/package.t
      ``v0.2.10'' Nothing special.  Output of ``dpkg-query -f
      '${Package}\n' -W'' is matched against m/^$RE{debian}{package}$/. 
      Probably should parse *_Packagees.

: source of t/archive.source.t
      ``v0.2.3'' Inspects all records in /var/lib/apt/lists/*_Sources,
      extracts *Files:* entries, then collects trailing filenames.  They
      are matched against ``m/^$RE{debian}{archive}{source_1_0}$/'',
      ``m/^$RE{debian}{archive}{patch_1_0}$/'',
      ``m/^$RE{debian}{archive}{source_3_0_native}$/'',
      ``m/^$RE{debian}{archive}{source_3_0_quilt}$/'',
      ``m/^$RE{debian}{archive}{patch_3_0_quilt}$/'', and
      ``m/^$RE{debian}{archive}{dsc}$/'' (in fact ``||'').  If none
      matches then it will be reported at the end. 
      ``m/$RE{debian}{archive}{changes}/'' is missing here because there
      is no source of such on build undedicated system.

: version of t/version.t
      ``v0.2.10'' Again nothing special.  Output of ``dpkg-query -f
      '${Version}\n' -W'' is matched against m/^$RE{debian}{version}$/. 
      Probably should parse *_Packages too.

  If any test string fails I need to know what and how.  To provide that
  info I've picked Test::Differences (maybe there's other option I'm not
  aware of?) (I'm, Test::Deep).  (Surely I could go one of fail-proof
  ways described in T::D pod; and what if something goes wrong? let's no
  play stupid hope -- I must know what happened.) (After looking at
  number of ``UNKNOWN'' results from CPAN-Testers -- I think, I should.)
  That yeilds a big problem.  T::D has two (actually one) open bugs --
  [38320@rt.cpan.org] and [41241@rt.cpan.org] -- at time of writing they
  are still open, no maintainer responce, patch is provided.  Some test
  strings of R::C::d give ``undef'' as predicted result.  That will
  provide a lots of "use of undef" warnings (really, a lots of).  And as
  a matter of fact, T::D will be somewhat useles -- forgive me, let me
  figure out version relations first.


==== AVAILABILITY ====

: pure distribution
          http://search.cpan.org/dist/Regexp-Common-debian/


==== BUGS ====

: please report here
          http://rt.cpan.org/Public/Dist/Display.html?Name=Regexp-Common-debian


==== COPYRIGHT AND LICENSING ====

: *   Copyright 2008--2010 Eric Pozharski <whynot@cpan.org>

: *   AS-IS, NO-WARRANTY, HOPE-TO-BE-USEFUL

: *   GNU Lesser General Public License v3
      <http://www.gnu.org/licenses/lgpl.txt>

