diff options
author | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
commit | e5c6e6d9c56fbfc54508fa2c32b03a5a870b7553 (patch) | |
tree | 40fcc93aa383c1e45d31ddc42d03f15cbada7076 /Master/tlpkg/tlperl/lib/version.pod | |
parent | 300c1eb6d37d46078d448d6d58938d5a80cd68ff (diff) |
oops, remove 5.16 tlperl files
git-svn-id: svn://tug.org/texlive/trunk@33649 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/version.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/version.pod | 322 |
1 files changed, 0 insertions, 322 deletions
diff --git a/Master/tlpkg/tlperl/lib/version.pod b/Master/tlpkg/tlperl/lib/version.pod deleted file mode 100644 index f4328f54391..00000000000 --- a/Master/tlpkg/tlperl/lib/version.pod +++ /dev/null @@ -1,322 +0,0 @@ -=head1 NAME - -version - Perl extension for Version Objects - -=head1 SYNOPSIS - - # Parsing version strings (decimal or dotted-decimal) - - use version 0.77; # get latest bug-fixes and API - $ver = version->parse($string) - - # Declaring a dotted-decimal $VERSION (keep on one line!) - - use version; our $VERSION = version->declare("v1.2.3"); # formal - use version; our $VERSION = qv("v1.2.3"); # shorthand - use version; our $VERSION = qv("v1.2_3"); # alpha - - # Declaring an old-style decimal $VERSION (use quotes!) - - our $VERSION = "1.0203"; # recommended - use version; our $VERSION = version->parse("1.0203"); # formal - use version; our $VERSION = version->parse("1.02_03"); # alpha - - # Comparing mixed version styles (decimals, dotted-decimals, objects) - - if ( version->parse($v1) == version->parse($v2) ) { - # do stuff - } - - # Sorting mixed version styles - - @ordered = sort { version->parse($a) <=> version->parse($b) } @list; - -=head1 DESCRIPTION - -Version objects were added to Perl in 5.10. This module implements version -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. - - use version 0.77; # even for Perl v.5.10.0 - -=head1 TYPES OF VERSION OBJECTS - -There are two different types of version objects, corresponding to the two -different styles of versions in use: - -=over 2 - -=item Decimal Versions - -The classic floating-point number $VERSION. The advantage to this style is -that you don't need to do anything special, just type a number into your -source file. Quoting is recommended, as it ensures that trailing zeroes -("1.50") are preserved in any warnings or other output. - -=item Dotted Decimal Versions - -The more modern form of version assignment, with 3 (or potentially more) -integers separated 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 -strongly recommended for clarity, and will throw a warning in a future -release if omitted. A leading 'v' character is required to pass the -L</is_strict()> test. - -=back - -=head1 DECLARING VERSIONS - -If you have a module that uses a decimal $VERSION (floating point), and you -do not intend to ever change that, this module is not for you. There is -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, -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. - -B<Important Note>: you must ensure that your new $VERSION is numerically -greater than your current decimal $VERSION; this is not always obvious. First, -convert your old decimal version (e.g. 1.02) to a normalized dotted-decimal -form: - - $ perl -Mversion -e 'print version->parse("1.02")->normal' - v1.20.0 - -Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0). - -=head2 How to C<declare()> a dotted-decimal version - - use version; our $VERSION = version->declare("v1.2.3"); - -The C<declare()> method always creates dotted-decimal version objects. When -used in a module, you B<must> put it on the same line as "use version" to -ensure that $VERSION is read correctly by PAUSE and installer tools. You -should also add 'version' to the 'configure_requires' section of your -module metadata file. See instructions in L<ExtUtils::MakeMaker> or -L<Module::Build> for details. - -B<Important Note>: Even if you pass in what looks like a decimal number -("1.2"), a dotted-decimal will be created ("v1.200.0"). To avoid confusion -or unintentional errors on older Perls, follow these guidelines: - -=over 2 - -=item * - -Always use a dotted-decimal with (at least) three components - -=item * - -Always use a leading-v - -=item * - -Always quote the version - -=back - -If you really insist on using version.pm with an ordinary decimal version, -use C<parse()> instead of declare. See the L<PARSING AND COMPARING VERSIONS> -for details. - -See also L<version::Internals> for more on version number conversion, -quoting, calculated version numbers and declaring developer or "alpha" version -numbers. - -=head1 PARSING AND COMPARING VERSIONS - -If you need to compare version numbers, but can't be sure whether they are -expressed as numbers, strings, v-strings or version objects, then you should -use version.pm to parse them all into objects for comparison. - -=head2 How to C<parse()> a version - -The C<parse()> method takes in anything that might be a version and returns -a corresponding version object, doing any necessary conversion along the way. - -=over 2 - -=item * - -Dotted-decimal: bare v-strings (v1.2.3) and strings with more than one -decimal point and a leading 'v' ("v1.2.3"); NOTE you can technically use a -v-string or strings with a leading-v and only one decimal point (v1.2 or -"v1.2"), but you will confuse both yourself and others. - -=item * - -Decimal: regular decimal numbers (literal or in a string) - -=back - -Some examples: - - $variable version->parse($variable) - --------- ------------------------- - 1.23 v1.230.0 - "1.23" v1.230.0 - v1.23 v1.23.0 - "v1.23" v1.23.0 - "1.2.3" v1.2.3 - "v1.2.3" v1.2.3 - -See L<version::Internals> for more on version number conversion. - -=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 two helper functions that can be -employed directly: - -=over 4 - -=item C<is_lax()> - -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: - - v1.2 - 1.2345.6 - v1.23_4 - 1.2345 - 1.2345_01 - -=item C<is_strict()> - -If you want to limit yourself to a much more narrow definition of what -a version string constitutes, C<is_strict()> is limited to version -strings like the following list: - - v1.234.5 - 2.3456 - -=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 if C<is_lax()> and -C<is_strict()> are not sufficient for your needs. - -=head2 How to compare version objects - -Version objects overload the C<cmp> and C<< <=> >> operators. Perl -automatically generates all of the other comparison operators based on those -two so all the normal logical comparisons will work. - - if ( version->parse($v1) == version->parse($v2) ) { - # do stuff - } - -If a version object is compared against a non-version object, the non-object -term will be converted to a version object using C<parse()>. This may give -surprising results: - - $v1 = version->parse("v0.95.0"); - $bool = $v1 < 0.96; # FALSE since 0.96 is v0.960.0 - -Always comparing to a version object will help avoid surprises: - - $bool = $v1 < version->parse("v0.96.0"); # TRUE - -Note that "alpha" version objects (where the version string contains -a trailing underscore segment) compare as less than the equivalent -version without an underscore: - - $bool = version->parse("1.23_45") < version->parse("1.2345"); # TRUE - -See L<version::Internals> for more details on "alpha" versions. - -=head1 OBJECT METHODS - -=head2 is_alpha() - -True if and only if the version object was created with a underscore, e.g. - - version->parse('1.002_03')->is_alpha; # TRUE - version->declare('1.2.3_4')->is_alpha; # TRUE - -=head2 is_qv() - -True only if the version object is a dotted-decimal version, e.g. - - version->parse('v1.2.0')->is_qv; # TRUE - version->declare('v1.2')->is_qv; # TRUE - qv('1.2')->is_qv; # TRUE - version->parse('1.2')->is_qv; # FALSE - -=head2 normal() - -Returns a string with a standard 'normalized' dotted-decimal form with a -leading-v and at least 3 components. - - version->declare('v1.2')->normal; # v1.2.0 - version->parse('1.2')->normal; # v1.200.0 - -=head2 numify() - -Returns a value representing the object in a pure decimal form without -trailing zeroes. - - version->declare('v1.2')->numify; # 1.002 - version->parse('1.2')->numify; # 1.2 - -=head2 stringify() - -Returns a string that is as close to the original representation as possible. -If the original representation was a numeric literal, it will be returned the -way perl would normally represent it in a string. This method is used whenever -a version object is interpolated into a string. - - version->declare('v1.2')->stringify; # v1.2 - version->parse('1.200')->stringify; # 1.200 - version->parse(1.02_30)->stringify; # 1.023 - -=head1 EXPORTED FUNCTIONS - -=head2 qv() - -This function is no longer recommended for use, but is maintained for -compatibility with existing code. If you do not want to have it exported -to your namespace, use this form: - - use version 0.77 (); - -=head2 is_lax() - -(Not exported by default) - -This function takes a scalar argument and returns a boolean value indicating -whether the argument meets the "lax" rules for a version number. Leading and -trailing spaces are not allowed. - -=head2 is_strict() - -(Not exported by default) - -This function takes a scalar argument and returns a boolean value indicating -whether the argument meets the "strict" rules for a version number. Leading -and trailing spaces are not allowed. - -=head1 AUTHOR - -John Peacock E<lt>jpeacock@cpan.orgE<gt> - -=head1 SEE ALSO - -L<version::Internals>. - -L<perl>. - -=cut |