NAME

Regexp::Common::debian - regexps for Debian specific strings

SYNOPSIS

use Regexp::Common qw/ debian /;
# Read `perldoc Regexp::Common` for base documentation
# Each pattern provides its own synopsis

DESCRIPTION

Debian GNU/Linux as a management system validates, parses, and generates a lots of data. For sake of some other project I've needed some kind of parser. Part of Debian package management system, namely it's generating part -- dpkg-deb, is written in Perl, but... The API is provided in source-code form -- no docs, no plans, we are unstable. What morons. I've needed something I could depend on. I'm not about code, I'm about API.

So I've gone myself. I believe, that Perl-way of doing such things is packing re-used and intented for re-use in module. And if such module is made anyway, why I shouldn't share it? (hmm, I've already told that someone...) So here we are -- Regexp::Common::debian (applauses, thanks, thanks).

When choosing API I would provide I had an option --

parsing: That would be a bunch of error-prone decisions -- pick a backbone parser, figure out grammar, mix them, build API, implement it,.. And as a net result one more xDpkg:: namespace. I really would like to hear any reasons why.
comparing: String on left, regexp on right, add {-keep}, and get an array of parsed out parts. Other way: string on left, regexp on right, anchor it properly, and get a scalar indicating match/mismatch. The only deficiency I can see is that result is an array, but hash. Hard to argue. That seems I've committed a sin. Should live with it.

As a backbone Regexp::Common was chosen. It has it's own deficiences, but I've failed to find any unhappy user (unsatisfied -- maybe, but unhappy -- no, sir). Maybe I didn't tried hard enough. It provides neat and rich interface, but...

{-keep} and {-i} are provided internally. It's OK with {-keep}, but {-i}... Look, Debian strings are almost all case-sensitive. When case shouldn't matter it's explicitly switched off by template itself. So -- if you play with {-i}, don't blame me then. (I'll experiment with implicit qr/(?i:)/ after that release. And experiments are going.)

(note) Regexp::Common::debian is very permissive in some cases (sometime absurdly permissive). Hopefully, I've noted in docu all such cases.

v0.2.10 The test-suite checks various sources that could be found on Debian system. Those checks are done only upon request. Don't be a bit optimistic about success. README has more.

$RE{debian}{package}

'the-very.strange.package+name' =~ $RE{debian}{package}{-keep};
print "package is $1";

This is Debian package name. Rules are described in Section 5.6.7 of Debian policy.

$1 is a package

$RE{debian}{version}

'10:1+abc~rc.2-ALPHA:now-rc25+w~t.f' =~ $RE{debian}{version}{-keep};
($2 || 0) eq '10'            &&
$3 eq '1+abc~rc.2-ALPHA:now' &&
($4 || 0) eq 'rc25+w~t.f'       or die;

This is Debian version. Rules are described in Section 5.6.12 of Debian policy. $3 and $4 are implicitly caseles (as required).

$1 is a debian_version

$2 is an epoch

if any. Oterwise -- undef. Debian policy requires defaulting here to 0. However Perl disallows assignment special variables $[1-9][0-9]*. So if you have $2 to be undef then assume here 0.

$3 is an upstream_version

If there's no way to match upstream_version than the whole pattern fails.

(caveat) A string like 0--1 will end up with $3 set to weird 0- (hopefully, Debian won't degrade to such versions; though YMMV).

(caveat) v0.2.3 Look for caveat #1 for background. However this RE stayed a bit better than others. In spite of Debian policy, upstream_version can start with number or letter but any version forming character. Should it be configurable? Probably. But think about it: $RE{debian} is for working with strings but verification. And such policy-ignorant versions wouldn't go elsewhere (think changelog.Debian). So in presense of choice between weak and strict you would alomost ever choose weak. And a point of strict then? Nobody cares.

$4 is a debian_revision

(bug) 0-1- will end up with $3 set to 0 and $4 set to 1 (such trailing hyphens will be missing in $1). 0- will end up with $4 undefed. And the same (as with $2) -- omitted debian_revision defaults to 0; $4 can't.

(caveat) The debian_revision is allowed to start with non-digit. This's solely my reading of Debian Policy.

(bug) Either I don't perlre or I didn't tried hard enough. Anyway, I haven't found a way to parse Debian version the way R::C requires in context of perl5.8.8 (perl in stable, going to be oldstable) (perl5.10.0 isn't old-stable yet). qr/(?|)/ saved perl5.10.0 (but see "R_C_d_version()").

R_C_d_version()

use Regexp::Common qw(debian);
# though that works too
# use Regexp::Common::debian;
my $re = Regexp::Common::debian::R_C_d_version;
$version =~ /^$re$/;
$2                   and print "has epoch\n";
$3 || $5 || $6 || $8 and print "has upstream_version\n";
$4 || $7             and print "has debian_revision\n";
$3 && !$4 || !$3 && $4 or die;
$6 && !$7 || !$6 && $7 or die;
$3 && !$5 && !$6 && !$8 or die;
       $5 && !$6 && !$8 or die;
              $6 && !$8 or die;

That's a workaround for perl5.8.8 (read "$RE{debian}{version}" (look for (bug))). Look for (caveat) in "$RE{debian}{version}" -- those apply here too.

$1 is debian_version again
$2 is epoch always
Either $3, or $5, or $6, or $8 is upstream_version: (note) Because R_C_d_version() is going to be dropped soon it wasn't updated to allow non-digit as a leading character.
Either $4 or $7 is debian_revision

That's the best what can be done with RE (in real world it's done functional way). Sorry.

(bug) It always grabs (should be configurable with setting like -keep). OTOH, look, within 2year (or so) (as soon as perl5.10.0 would be oldstable) that dirty piece will be dropped anyway.

(note) R_C_d_version() is unexported function because that follows Regexp::Common's way of providing regexps -- each time you've got a new qr//, but reference. It's unexported for obvious reason.

$RE{debian}{architecture}

$arch =~ $RE{debian}{architecture}{-keep};
$2 && ($3 ||  $4)           and die;
       $3 && !$4            and die;
       $3 &&  $4 eq 'armel' and die;
$2 and print "that's special: $2";
$3 and print "OS is: $3";
$4 and print "arch is: $4";

This is Debian architecture. Rules are described in Section 5.6.8 of Debian policy.

$1 is some of Debian's architectures
$2 is any special: Distinguishing special architectures (all, any, and source) and os-arch pairs is arguable. But I've decided that would be good to separate all and e.g. i386 (what in turn is actually linux-i386).
$3 is os: When !$3 && $4 is true then undefined $3 actually means linux. Since $digits are read-only yielding here anything but undef is impossible. More on that in Section 11.1 of Debian policy.
$4 is arch: Please note that there are architectures which are present only for linux os (namely armel and lpia, at time of writing).

(caveat) Debian policy by itself doesn't specify what os-arch pairs are valid (only specials are mentioned). In turn it relies on qx/dpkg-architecture -L/. In effect R::C::d can desinchronize; Hopefully, that wouldn't stay unnoticed too long.

$RE{debian}{archive}{binary}

'abc_1.2.3-512_all.deb' =~ $RE{debian}{archive}{binary}{-keep};
print "     package is -> $2";
print "     version is -> $3";
print "architecture is -> $4";

This is Debian binary archive (even if there's no binary file (in -B sense) inside it's called "binary" anyway). The naming convention isn't described in Debian policy; Instead it refers to format understood by dpkg (Preface of Chapter 3). deb(5) brings no light either. (Hopefully, someday here will be references to code inside dpkg and dpkg-deb codebase that does those nasty things with package, version, and arch composing in and decomposing out of filenames.)

$1 is deb-filename

That's the whole archive filename with .deb suffix included

$2 is package

$3 is version

There's a big deal of WTF. Filename: in *_Packages miss epoch at all. Archives in pool/ miss them too. Archives in /var/cache/apt/archives ... That seems to be apt-get specific (I don't have reference to code though). As a feature $RE{d}{a}{binary} provides an epoch hack in filenames.

(bug) That extra inteligence should be configurable.

(caveat) v0.2.3 "caveat #1: version starts with letter".

$4 is architecture

(caveat) That would match surprising source or any. Sorry. That'll improve in future. Actually that's even worse: OS can prepend any arch or special.

(caveat) "caveat #2: suffix could be in version"

$RE{debian}{archive}{source_1_0}

'xyz_1-ab.25~6.orig.tar.gz' =~ $RE{debian}{archive}{source_1_0}{-keep};
print "package is $2";
index($3, '-') && $4 eq 'tar' and die;
$4 eq 'orig.tar'              and print "there should be patch";

This is Debian upstream (or Debian-native) source tarball. Naming source archives is outside Debian policy; although

Section 5.6.21 mentions that "the exact forms of the filenames are described in" Section C.3.
Section C.3 points that source archive must be in form package_upstream-version.orig.tar.gz.
Naming Debian-native packages is left completely.
dpkg-source(1) (at least of 1.15.2) shows real life and makes all that a bit more complicated. See section SOURCE PACKAGE FORMATS of dpkg_source(1) for details.

v0.2.3 At that point an incompatible change has been made. $RE{d}{a}{source} has been renamed to $RE{d}{a}{source_1_0} (what in fact it always was). Probably one day there could be an agregating $RE{d}{a}{source} that would match any source filename (if there would be any purpose for). More on different formats below.

Format: 1.0: It's either set of *.orig.tar.gz and acompaning *.diff.gz or lone *.tar.gz (then that's 'native'). That is covered by $RE{d}{a}{source_1_0}
Format: 2.0: That's supposedly unseen in wild. dpkg-source(1) doesn't say what filenames represent it. Probably those of Format: 3.0 (quilt) (refer to $RE{d}{a}{source_3_0_quilt} for details). Not implemented.
Format: 3.0 (native): At that point Format: 1.0 has been split. Debian native packages (those without *.debian.tar.gz) are of this type. Implemented in $RE{d}{a}{source_3_0_native}.
Format: 3.0 (quilt): Those with *.debian.tar.gz are of this second format. Very hot. Implemented in $RE{d}{a}{source_3_0_quilt} and $RE{d}{a}{patch_3_0_quilt}. Refer to respective sections, details are huge.
Format: 3.0 (custom): A secret format. Probably $RE{d}{a}{source_3_0_quilt} would suffice. Not implemented.
Format: 3.0 (git)
Format: 3.0 (bzr): Those are secret too. And again, I believe, $RE{d}{a}{source_3_0_quilt} would be enough. Not implemented.

And now miserable notes about $RE{d}{a}{source_1_0}:

$1 is tarball-filename

Since there's no other suffix, but .gz it's present only in $1

$2 is package

$3 is version

There's a bit (or pile) of complication. Look, if $3 contains minus (-), that means that resulting binary must have debian_revision set (otherwise that minus must not be here), thus implying presense of *.diff.gz, thus implying $4 must be orig.tar but simple tar (what would be Debian native package). OTOH, if there is no minus, then $4 could be either orig.tar or tar. Obviously lack or presence of *.diff.gz falls out of knowledge of $RE{d}{a}{source_1_0}.

(bug) That should fail this package_0.orig-component.tar.gz. It doesn't ($RE{d}{a}{source_3_0_native} for details).

(caveat) Consider this: package_0-1.debian.tar.gz. Is it debian-native (version would be 0-1.debian) of Format: 1.0; or is it debianization tar (version would be 0-1) of Format: 3.0 (quilt)? Without checking Format: entry it's impossible to say. (Are you wondering about hyphen? Think again (unattended-upgrades_0.25.1debian1-0.1 is debian-native).) The good news is that (at time of writing) I've found none debian-native package (of either Format:) which Version: would match qr/debian$/. (Let's check it tomorrow.) And back to the subject: package_0.debian.tar.gz is implicitly prohibited.

(caveat) v0.2.3 "caveat #1: version starts with letter".

$4 is type

This can hold one of 2 strings (orig.tar (regular package) or tar (Debian-native package)).

(bug) Probably that should look behind (if that would be that possible) for hyphen (-) in $3. It doesn't. Because it's OK to have hyphen in Debian-native packages (francine_0.99.8orig-6.tar.gz).

(caveat) "caveat #2: suffix could be in version"

$RE{debian}{archive}{source_3_0_native}

'xyz_1234.tar.lzma' =~ $RE{debian}{archive}{source_3_0_native}{-keep}
print "package is $2";
print "version is $3";
print 'decompress wiht ' .
  $4 eq 'gz'   ? 'gunzip'  :
  $4 eq 'bz2'  ? 'bunzip2' :
  $4 eq 'lzma' ? 'unlzma'  : die;

v0.2.5 That's descandant of $RE{d}{a}{source_1_0} for native packages (those without *.debian.tar.gz).

$1 is tarball-filename

tar with delimiting dots (.) is included only here.

$2 is package

$3 is version

(bug) That must fail on package_0.orig.tar.gz. It doesn't because of package_0.orig-component.tar.gz. It needs variable-length look-behind.

package_0.debian.tar.gz doesn't match. $RE{d}{a}{patch_3_0_quilt} matches instead.

(caveat) v0.2.3 "caveat #1: version starts with letter".

$4 is suffix

It's either gz, bz2, or lzma. Anything else (missing counts as anything) would fail the whole pattern.

(caveat) "caveat #2: suffix could be in version"

$RE{debian}{archive}{source_3_0_quilt}

'xyz_1-ab.25~6.orig-cool-stuff.tar.bz2' =~ $RE{debian}{archive}{source_3_0_native}{-keep};
print "package is $2";
print "version is $3";
print "component happens to be $4" if $4;
print 'decompress with ' .
  $5 eq 'gz'   ? 'gunzip'  :
  $5 eq 'bz2'  ? 'bunzip2' :
  $5 eq 'lzma' ? 'unlzma'  : die;

v0.2.4 That's descendant of $RE{d}{a}{source_1_0} for non-native debian packages (those with *.debian.tar.gz). (note) Also Format: 3.0 (quilt) invents a concept of components.

$1 is tarball-filename

Delimiting dots (.), orig (with or without (if missing) component delimiting hyphen (-)), and tar are present here only. The component itself is present in $4.

$2 is package

$3 is version

(caveat) v0.2.3 "caveat #1: version starts with letter".

$4 is component

My understanding is that the 'component' is specially packed piece of upstream sources (being it packed this way by either upstream or Debian). Thus it's not a patch. Thus it's here ($RE{d}{a}{source_3_0_quilt} but $RE{d}{a}{patch_3_0_quilt}). The component name is either present or missing completely, so this is invalid:

null-component-package_01234.orig-.tar.gz

Although this is perfectly valid:

strange-component-package_98765.orig--.tar.gz

dpkg-source(5) is unclear about this, but my understanding is that component name is closer to package (thus lowercase only) then version (mixed case). However that's not yet enforced.

$5 is suffix

It's either gz, bz2, or lzma. Anything else (missing counts as anything) would fail the whole pattern.

(caveat) "caveat #2: suffix could be in version"

$RE{debian}{archive}{patch_1_0}

'abc_0cba-12.diff.gz' =~ $RE{debian}{archive}{patch_1_0}{-keep};
print "package is $2";
-1 == index $3, '-' and die;
print "debian revision is ", (split /-/, $3)[-1];

This is "debianization diff" (Section C.3 of Debian policy). Naming patches is outside Debian policy; So we're back to guessing. There're rumors (or maybe trends) that Format 1.0 will be deprecated (or maybe obsolete).

v0.2.6 Incompatible change. $RE{d}{a}{patch} has been renamed into $RE{d}{a}{patch_1_0}.

$1 is patch-filename

Since there's no other suffix, but .diff.gz it's present only in $1

$2 is package

$3 is version

(caveat) Consider this. A Debian-native package misses a patch and hyphen in version. A regular package has a patch and must have hyphen in version. $RE{d}{a}{patch_1_0} is absolutely ignorant about that (we are about matching but verifying after all).

(caveat) v0.2.3 "caveat #1: version starts with letter".

(caveat) "caveat #2: suffix could be in version"

$RE{debian}{archive}{patch_3_0_quilt}

Since Format: 3.0 (quilt) has been invented, debianization stuff has changed form from one big diff (*.diff.gz, $RE{d}{a}{patch_1_0}) to debianization stuff (placed in debian/) and set of diffs (if any) (intended to be placed in debian/patches/) in form of single tar-file (*.debian.tar.gz, mostly (as I can observe) *.bz2).

$1 is tar-filename: debian.tar with delimiting dots (.) is seen here only.
$2 is package
$3 is version: (caveat) v0.2.3 "caveat #1: version starts with letter".
$4 is suffix: It's either gz, bz2, or lzma. Anything else (missing counts as anything) would fail the whole pattern.

(caveat) "caveat #2: suffix could be in version"

$RE{debian}{archive}{dsc}

'abc_0cba-12.dsc' =~ $RE{debian}{archive}{dsc}{-keep};
print "package is $2";
print "version is $3";

This is "Debian source control" (Section 5.4 describes its contents but naming). Statistically based guessing, you know (once I'll elaborate to point exact lines in dpkg-dev bundle where it's in use (creating and parsing)).

$1 is dsc-filename: As usual, since the only suffix can be .dsc it's present in $1 only.
$2 is package
$3 is version: (caveat) v0.2.3 "caveat #1: version starts with letter".

(caveat) "caveat #2: suffix could be in version"

$RE{debian}{archive}{changes}

'abc_0cba-12.changes' =~ $RE{debian}{archive}{changes}{-keep};
print "package is $2";
print "version is $3";

This is "Debian changes file" (Section 5.5 describes its contents but naming). dpkg-genchanges(1) is silent too. So this pattern is based on observation too.

$1 is changes-filename: As usual, since the only suffix can be .changes it's present in $1 only.
$2 is package
$3 is version: (caveat) v0.2.3 "caveat #1: version starts with letter".
$4 is architecture: (caveat) "caveat #2: suffix could be in version"

$RE{debian}{sourceslist}

'deb file:/usr/local oldstable main contrib non-free' =~ $RE{debian}{sourceslist}{-keep} and
  system "rm -rf $5" or die;
($4 eq 'http' || $4 eq 'rsh' || $4 eq 'ssh') &&
  !index $5, '//' or die;
($4 eq 'file' || $4 eq 'cdrom' || $4 eq 'copy') &&
  !index($5, '/') && index($5, '/', 1) > 1 or die;
index(reverse($6), '/') || $7 or die;

This is one entry in sources.list resource list. The format is described in sources.list(5) man page (hence a chance for desincronization provided) (gosh, it's not debian any more, it's APT).

$1 is resource_entry

$RE{d}{sourceslist} is very permissive about what would constitute entries, but you can bet on -- the whole entry stays on one line.

$2 is resource_type

That can be either deb or deb-src. Implicit negative lookbehind for qr/\w/ provided (so =deb is accepted, _deb is not; hey, #deb is accepted too! explicit anchoring at your option).

$3 is uri

You think you know what URI is? Read below...

$4 is scheme

Schemes that APT knows have nothing to do with sources.list(5) actually. scheme that APT will use is some executable in /usr/lib/apt/methods (some of them are for transfer, some are not). sources.list(5) (of 0.7.21) defines these:

local filesystem: file, cdrom, copy.
network: http, ftp, rsh, ssh

Delimiting colon : isn't included here (although uri does).

$5 is hier_path

The idea is that someday $RE{d}{sourceslist} would look behind at uri to decide if there should be authority (that one delimited with //) or path_absolute would be enough. Right now that's not the case. (bug) Any non-space sequence is hier_path.

That's very bad, but that's the way it's done right now. Look, parsing URI is a task for standalone pattern. It's not implemented, maybe someday some kind perlist would do that. Yes, I know about Regexp::Common::URI. Apparently R::C::U knows nothing about cdrom:.

$6 is distribution

Debian is full of surprises. Lots of surprises. You think you know what distribution is, don't you? You missed. distribution can be filesystem path. Since sources.list(5) doesn't mention space escaping techniques I assume spaces aren't allowed; so any no-space is allowed. You think that's an overkill? You're obviously wrong (think $ARCH, sources.list(5) has more).

$7 is component_list

In misguided attempt not to make them too different with all that crowd, component_list is space delimited list of non-spaces. If distribution ends with slash (/), then component_list can be empty (I've meant, maybe someday that will look-behind too).

All that is quite messy. Can it be improved? Surely yes (even if we stay in Regexp::Common requirements) (think qr/(?|)/). And then we have one more v5.10.0 only regexp. Someday v5.10.0 will be oldstable...

$RE{debian}{preferences}

<<END_OF_PREFERENCE =~ $RE{debian}{preferences{-keep}} or die;
Explanation: Stay updated!
Package: perl
Pin: version 5.10*
Pin-Priority: 1001
END_OF_PREFERENCES
$2 eq 'perl' and
  print "good, we are looking for perl\n";
$3 eq 'version' and $4 =~ /^5\.10/ and
  print "good, we are looking for recent\n";
$5 =~ /^\d+$/ && $5 > 1000 and
  print "good, we'll stay updated\n";

This is one entry in preferences list. Good news are over, bad news are below. I've failed to find definition of entry in preferences (still looking). apt_preferences(5) suggests on what that looks like providing examples. It's not enough; apt-cache policy behaviour leads from understanding either.

After some experimenting I've found that: In general this is Debian control file format. With some quirks provided. Mine problem isn't how to implement that with REs: mine problem is what those quirks are! Either I figuring out the format, or releasing. (You've released once, so what?) So here we are -- some common case of entry in preferences.

Shortly:

each entry consists of 3 stanzas (Package:, Pin:, Pin-Priority:);
the order matters, no intermediate stanza is allowed;
case doesn't matter (for both name and value of stanza (to some degree));
whatever has gone before Package: or came after Pin-Priority: (line-wise) is ignored;
apt-cache policy fails in one case -- Package: stanza has leading spaces;
misparsed values are ignored, thus invalidating the whole entry (but see below), thus the entry is ignored.

That's what $RE{debian}{preferences} does. More on each stanza below.

(bug) apt-cache policy will accept newlines -- those are spaces in Debian control files, while consequent lines proper indentation provided. $RE{d}{preferences} accepts one line stanzas only.

$1 is a preferences_entry

That's the whole entry -- with all leading and trailing spaces, and an Easter Eggs. apt_preferences(5) invents something called Explanation: stanzas (they should go before Package:, with no empty lines in between). Since we are aware of that, Explanation: sequence is provided in $1 (and it won't be ever $2 (1st, obvious compatibility reasons; 2nd, it's somewhat legalized since it's mentioned; 3rd, it can be easily dropped in case I found that useful)).

$2 is a package_stanza

That's either * (star, match-any-string wildcard) or space separated list of package names (alone package name is degenerated list). That is, if package_stanza is a list, than each (even if there's only one) non-space sequence is treated as package name. apt-cache policy doesn't seem to verify its input, so one can put here anything. Then those sequences will be matched literally against known package names.

(feature) In contrary with everything else, in $RE{d}{preferences}, package names are case-sensitive.

(bug) apt-cache policy will silently accept star among package names. Then, since no-one package name matches (there can't be a package named *) the star will be missing among pinned packages. $RE{d}{preferences} rejects such strings.

$3 is a context_switch

Pin: stanza is broken in two parts. That's the first one. One of 3 acceptable strings are version, origin, or release. Bad news below.

$4 is a context_filter

(bug) (what else?) What would be a correct input here depends on $3. $RE{d}{preferences} takes anything up to the next newline.

$5 is a pin_priority_stanza

In $5 will be a sequence of decimal numbers (yes, hexadecimals are rejected and octals aren't converted), optionally prepended with + (plus) or - (minus) signs up to surprising . (dot). Any trailing decimals and dots (after the first one) will be ignored by apt-cache policy. So does the $RE{d}{preferences} too. The optional dot-decimal trailer will be missing in $5, but present in $1.

It's a mess, isn't it? Go figure.

$RE{debian}{changelog}

<<END_OF_CHANGELOG =~ $RE{debian}{changelog{-keep}} or die;
perl (6.0.0-1) unstable; urgency=high
  * Hourah!
 -- John Doe <doe@example.tld>  Thu, 01 Apr 2010 00:00:00 +0300
END_OF_CHANGELOG
print <<"END_OF_REPORT"
package        : $2
version        : $3
in archive     : $4
flags          : $5
changes        :
${6}uploaded by    : $7
achknowledgment: $8
at time        : $9

This is one entry in debian/changelog. The format is described in Section 4.4 of Debian Policy. In real world parsing of this file is done by parser script. /usr/lib/dpkg/parsechangelog/debian is a Perl script, that's called from dpkg-parsechangelog (of dpkg-dev package (that in turn is Perl script, again)).

There're 2 special Perl modules (namely: Debian::ParseChangelog (of CPAN), and Dpkg::Changelog (of dpkg-dev package)). And now there'is 3rd one (how cute). Those former are read/write engines, $RE{debian}{changelog} is read-only (for obvious reasons). There's a point of desincronization though.

Until Debian Policy v3.8.1.0 there was an option of providing debian/changelog in different format. However [489460@bugs.debian.org] had made it. Now that option has gone.

$1 is a changelog_entry

That's the whole entry of header, delimiting empty lines (if any), and sig-line (with trailing newline). That seems (that's not set explicitly in the debian-policy) that there must be intermediate empty line (what's 'empty line', btw?). And the latest entry in changelog must start with at the very first line. $RE{d}{a}{changelog} pays no attention.

$2 is a debian_package

(bug) Just a sequence of characters allowed in Debian's package name. No other restrictions provided.

$3 is a debian_version

Surrounding braces aren't included.

(bug) That's a simplified too.

(caveat) v0.2.3 "caveat #1: version starts with letter".

$4 is a distributions

v0.2.8 That's space ( ) separated sequence of letters (a .. z) (caseless, enforced) and hyphens (-) in any order, except first character should be letter (weird). Space before terminating semicolon is disallowed (it's not missing in $4, it fails entry). Terminating semicolon isn't included.

$5 is keys (or urgency, if you like)

(note) Debian Policy explicitly states that that field is supposed to be a comma (,) separated list of equal (=) separated key-value pairs. However the only known key is urgency. Maybe I'm too pesimistic, but despite the fact that the only key allowed is urgency the whole key=value pair is put in $5 -- so you've better be prepared and pick a key you're looking for (one day you can get a lot more).

(caveat) v0.1.5 I wasn't enough pessimistic. perl5.8.8 goes nuts sometimes looking for urgency (it happens to be an anchor) (namely: libcompress-zlib-perl_2.015-1) (perl5.10.0 is OK). In misguided attempt to support oldstable $RE{d}{changelog} no more looks for urgency, it looks for a sequence of lowercase letters. (And anchor is \040--\040 of sig-line now.) Sorry.

(caveat) 0.2.8 Log entry of binutils_2.7-5 invents concept of something. Let's call it comment (or wish). Thus anything that's not comma-separated equal-separated key-value pair is skipped (from $5). Obviously, it's present in $1

$6 is changes

That invents concept of empty line.

v0.2.8 For $RE{d}{changelog} "empty line" consists of any number horizontal spaces (space ( ) and tab ("\t")) followed by newline. OTOH, "line" is at least two spaces (one tab counts as at least two spaces) then any non-space character, and anything up to next newline (space counts as "anything" for now). No or one space followed by non-space fails entirely (but watch for trailing signature line). As requested by Debian Policy (or stock parser) leading and trailing empty lines are ignored (they are included in $1 though).

(bug) Handling trailing empty lines is broken. It's useles to describe what empty lines and what number of empty lines will end up in $6. $RE{d}{changelog} must be redone.

(caveat) The recommended way of outlineing changes is starting each subentry with star (*), then adding at least one space to sub-subentries. OTOH, the modern way to highlight work done by different maintainers (or probably non-maintainers at all) is by placing maintainer name in brackets (with two leading spaces). $RE{d}{changelog} accepts anything.

(note) (I can't say is it a bug or feature) The leading and trailing empty lines are said to be optional. However one leading and one trailing empty line are present in each (decent?) entry in Debian changelog file. $RE{d}{changelog} doesn't insist on that.

$7 is a maintainer_name

$RE{d}{changelog} is very permissive about what is maintainer_name (and what it is actually?). $8 and $9 take care of themselves. A leading space-then-double-hyphen and separating space aren't included.

v0.2.10 Any number of space (but null) could be between double-hyphen and $7 (libnet-daemon-perl_0.30-1).

$8 is an email_address

That one (with option to maintainer_address) is subject to be processed with Regexp::Common::Email::Address (or not, under consideration). Anyway, right now it's a sequence of non-spaces surrounded by angle brackets. Surrounding brackets aren't included.

$9 is a changelog_date

That one is subject to be processed with Regexp::Common::Time. Anyway, right now it's a sequence of RFC822-date forming characters, starting with capital letter and terminated with decimal number. Neither leading double-space nor trailing newline are included.

v0.2.9 debian-policy invents an option of 'time zone name or abbreaviation optionally present as a comment in parentheses'. Such comment would be included in $1 but missing in $9. Moreover, if that comment would fall on the next line it will be ignored. All that parody will suffer rewrite in next turn.

(caveat) There could be spaces after last number. They aren't included in $9. And yes, they are present in $1 though.

Pity on me.

BUGS AND CAVEATS

Grep this pod for (bug) and/or (caveat). They all are placed in appropriate sections.

However two caveats affect multiple patterns. They are covered here in details.

caveat #1: version starts with letter

(caveat) v0.2.3 Upon checking what I have in *_Packages I've discovered such thing: cnews_cr.g7-40.4_i386.deb. cnews is a package, i386 is an architecture. Then version is cr.g7-40.4? That doesn't look like it starts with number. Or does it?

Or mine reading of debian-policy has been a bit vague. Now I see it clearly states: should start with a digit. should isn't must. So from now on: version can start with any... For $RE{debian}{version} it starts with any version forming character except colon (:) or hyphen (-) (that will be fixed in next turn). For any other it starts with any VFC without exception. (package_+-12_all.deb is valid. And that's me troll?)

caveat #2: suffix could be in version

(caveat) Consider this: package_0.tar.gz.tar.gz Here the version is 0.tar.gz. Such version could be surprising but otherwise is perfectly valid. In order to parse it every filename pattern looks ahead if after suffix there's no version forming character while version parsing section is explicitly ungreedy. I believe that's easier then implement semantical checks instead (package_0.diff.gz.diff.gz is semantically incorrect, it should be pacage_0.diff.gz-1.diff.gz). However, none such versions has been found so far.

bug #1: no pos()

When working on test-booster for $RE{d}{changelog} I've discovered avful thing. qr/\G$RE{debian}{changelog}{-keep}/sg fails. Subsequent pos() returns undef. Setting pos() is ignored. Probably all other patterns are affected too. I can't say what's a cause. That will be investigated and hopefully fixed in next turn.

AUTHOR

Eric Pozharski, <whynot@cpan.org>

COPYRIGHT AND LICENSE

This library is free in sense: AS-IS, NO-WARANRTY, HOPE-TO-BE-USEFUL. This library is released under LGPLv3.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

BUGS AND CAVEATS

AUTHOR

COPYRIGHT AND LICENSE

SEE ALSO

Module Install Instructions