Export and document is_lax and is_strict functions

Allow the is_lax and is_strict functions to be optionally
exported to the caller's namespace (without having to use Exporter).

Document the usage of is_lax and is_strict, plus nuke some trailing
spaces.

1 files changed, 71 insertions, 8 deletions

diff --git a/lib/version.pod b/lib/version.pod
index 090b5969ee..a42eeca563 100644
--- a/lib/version.pod
+++ b/lib/version.pod
@@ -37,7 +37,7 @@ objects for older version of Perl and provides the version object API for all
 versions of Perl.  All previous releases before 0.74 are deprecated and should
 not be used due to incompatible API changes.  Version 0.77 introduces the new
 'parse' and 'declare' methods to standardize usage.  You are strongly urged to
-set 0.77 as a minimum in your code, e.g. 
+set 0.77 as a minimum in your code, e.g.
 
   use version 0.77; # even for Perl v.5.10.0
 
@@ -58,7 +58,7 @@ quotes) into your source file.
 
 The more modern form of version assignment, with 3 (or potentially more)
 integers seperated by decimal points (e.g. v1.2.3).  This is the form that
-Perl itself has used since 5.6.0 was released.  The leading "v" is now 
+Perl itself has used since 5.6.0 was released.  The leading "v" is now
 strongly recommended for clarity, and will throw a warning in a future
 release if omitted.
 
@@ -74,14 +74,14 @@ nothing that version.pm gains you over a simple $VERSION assignment:
 
   our $VERSION = 1.02;
 
-Since Perl v5.10.0 includes the version.pm comparison logic anyways, 
+Since Perl v5.10.0 includes the version.pm comparison logic anyways,
 you don't need to do anything at all.
 
 =head2 How to convert a module from decimal to dotted-decimal
 
 If you have used a decimal $VERSION in the past and wish to switch to a
 dotted-decimal $VERSION, then you need to make a one-time conversion to
-the new format. 
+the new format.
 
 B<Important Note>: you must ensure that your new $VERSION is numerically
 greater than your current decimal $VERSION; this is not always obvious. First,
@@ -171,6 +171,69 @@ Some examples:
 
 See L<VERSION OBJECT DETAILS> for more on version number conversion.
 
+=head2 How to check for a version
+
+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
+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
+
+=item C<is_lax()>
+
+=over 2
+
+=item v1.2
+=item 1.2345.6
+=item 1.23_4
+
+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 1.2345
+=item 1.2345_01
+
+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.
+
+=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
+
 =head2 How to compare version objects
 
 Version objects overload the C<cmp> and C<< E<lt>=E<gt> >> operators.  Perl
@@ -255,21 +318,21 @@ that is not possible in earlier versions of Perl.  In other words:
 =head2 What about v-strings?
 
 There are two ways to enter v-strings: a bare number with two or more
-decimal points, or a bare number with one or more decimal points and a 
+decimal points, or a bare number with one or more decimal points and a
 leading 'v' character (also bare).  For example:
 
   $vs1 = 1.2.3; # encoded as \1\2\3
-  $vs2 = v1.2;  # encoded as \1\2 
+  $vs2 = v1.2;  # encoded as \1\2
 
 However, the use of bare v-strings to initialize version objects is
 B<strongly> discouraged in all circumstances.  Also, bare
 v-strings are not completely supported in any version of Perl prior to
 5.8.1.
 
-If you insist on using bare v-strings with Perl > 5.6.0, be aware of the 
+If you insist on using bare v-strings with Perl > 5.6.0, be aware of the
 following limitations:
 
-1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses, 
+1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses,
 based on some characteristics of v-strings.  You B<must> use a three part
 version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.