From: John Peacock Date: Wed, 27 Jan 2010 01:47:54 +0000 (-0500) Subject: Document usage of version regexps X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=42bd538f820268331bc55a66fa9df0673de69250;p=p5sagit%2Fp5-mst-13.2.git Document usage of version regexps Move the discussion of what each regexp coveres to version::Internals and limit the discussion in the main POD to just include examples. --- diff --git a/lib/version.pod b/lib/version.pod index a42eeca..e09a288 100644 --- a/lib/version.pod +++ b/lib/version.pod @@ -171,68 +171,41 @@ Some examples: See L for more on version number conversion. -=head2 How to check for a version +=head2 How to check for a legal version string If you do not want to actually create a full blown version object, but would still like to verify that a given string meets the criteria to -be parsed as a version, there are now regular expressions included with -the version module and there are two helper functions that can be +be parsed as a version, there are two helper functions that can be employed directly: -=over 2 - -=item C - -If you want to limit youself to a much more narrow definition of what -a version string constitutes, you can use this function, which limits -legal version strings to the following list: - -=over 2 - -=item v1.234.5 - -For dotted-decimal versions, requires a leading 'v', three sub-versions -of no more than three digits. A leading 0 (zero) before the first -sub-version (in the above example, '1') is also prohibited. - -=item 2.3456 - -For standard decimal version, requires an integer portion (no leading -0), a decimal, and one or more digits to the right of the decimal - -=back +=over 4 =item C -=over 2 +The lax criteria corresponds to what is currently allowed by the +version parser. All of the following formats are acceptable +for dotted-decimal formats strings: -=item v1.2 -=item 1.2345.6 -=item 1.23_4 + v1.2 + 1.2345.6 + v1.23_4 + 1.2345 + 1.2345_01 -With the lax criteria, all of the above styles are acceptable for -dotted-decimal formats. The leading 'v' is optional if two or more -decimals appear. If only a single decimal is included, then the leading -'v' is required to trigger the dotted-decimal parsing. A leading zero -is permitted, though not recommended except when quoted, because of the -risk that Perl will treat the number as octal. A trailing underscore -plus one or more digits denotes an alpha or development release -(and must be quoted to be parsed properly). +=item C -=item 1.2345 -=item 1.2345_01 +If you want to limit youself to a much more narrow definition of what +a version string constitutes, C is limited to version +strings like the following list: -For decimal versions, the lax form is nearly identical to the strict -form except that the alpha form is allowed and a leading zero is -permitted. Just like the lax dotted-decimal version, quoting the -values is required for alpha/development forms to be parsed correctly. + v1.234.5 + 2.3456 =back -See L for details of the regular expressions used, -as well as how to use the regular expressions in your own code. - -=back +See L for details of the regular expressions +that define the legal version string forms, as well as how to use +those regular expressions in your own code. =head2 How to compare version objects diff --git a/lib/version/Internals.pod b/lib/version/Internals.pod index 597b465..856383c 100644 --- a/lib/version/Internals.pod +++ b/lib/version/Internals.pod @@ -130,6 +130,91 @@ following sequence of $VERSION's: The stringified form of Decimal versions will always be the same string that was used to initialize the version object. +=head2 Regular Expressions for Version Parsing + +A formalized definition of the legal forms for version strings is +included in the main F file. Primitives are included for +common elements, although they are scoped to the file so they are useful +for reference purposes only. There are two publicly accessible scalars +that can be used in other code (not exported): + +=over 4 + +=item C<$version::LAX> + +This regexp covers all of the legal forms allowed under the current +version string parser. This is not to say that all of these forms +are recommended, and some of them can only be used when quoted. + +For dotted decimals: + + v1.2 + 1.2345.6 + v1.23_4 + +The leading 'v' is optional if two or more decimals appear. If only +a single decimal is included, then the leading 'v' is required to +trigger the dotted-decimal parsing. A leading zero is permitted, +though not recommended except when quoted, because of the risk that +Perl will treat the number as octal. A trailing underscore plus one +or more digits denotes an alpha or development release (and must be +quoted to be parsed properly). + +For decimal versions: + + 1 + 1.2345 + 1.2345_01 + +an integer portion, an optional decimal point, and optionally one or +more digits to the right of the decimal are all required. A trailing +underscore is permitted and a leading zero is permitted. Just like +the lax dotted-decimal version, quoting the values is required for +alpha/development forms to be parsed correctly. + +=item C<$version::STRICT> + +This regexp covers a much more limited set of formats and constitutes +the best practices for initializing version objects. Whether you choose +to employ decimal or dotted-decimal for is a personal preference however. + +=over 4 + +=item v1.234.5 + +For dotted-decimal versions, a leading 'v' is required, with three or +more sub-versions of no more than three digits. A leading 0 (zero) +before the first sub-version (in the above example, '1') is also +prohibited. + +=item 2.3456 + +For decimal versions, an integer portion (no leading 0), a decimal point, +and one or more digits to the right of the decimal are all required. + +=back + +=back + +Both of the provided scalars are already compiled as regular expressions +and do not contain either anchors or implicit groupings, so they can be +included in your own regular expressions freely. For example, consider +the following code: + + ($pkg, $ver) =~ / + ^[ \t]* + use [ \t]+($PKGNAME) + (?:[ \t]+($version::STRICT))? + [ \t]*; + /x; + +This would match a line of the form: + + use Foo::Bar::Baz v1.2.3; # legal only in Perl 5.8.1+ + +where C<$PKGNAME> is another regular expression that defines the legal +forms for package names. + =head1 High level design =head2 version objects