See L<VERSION OBJECT DETAILS> 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<is_strict()>
-
-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<is_lax()>
-=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<is_strict()>
-=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_strict()> 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<version::Internal> for details of the regular expressions used,
-as well as how to use the regular expressions in your own code.
-
-=back
+See L<version::Internals> 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
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<version.pm> 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
projects / p5sagit/p5-mst-13.2.git / commitdiff