argra****@users*****
argra****@users*****
2012年 12月 6日 (木) 00:52:42 JST
Index: docs/modules/version-0.77/version.pod
diff -u /dev/null docs/modules/version-0.77/version.pod:1.1
--- /dev/null Thu Dec 6 00:52:42 2012
+++ docs/modules/version-0.77/version.pod Thu Dec 6 00:52:42 2012
@@ -0,0 +1,793 @@
+
+=head1 NAME
+
+=begin original
+
+version - Perl extension for Version Objects
+
+=end original
+
+version - バージョンオブジェクトのための Perl 拡張
+
+=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 0.77; our $VERSION = version->declare("v1.2.3"); # formal
+ use version 0.77; our $VERSION = qv("v1.2.3"); # shorthand
+ use version 0.77; our $VERSION = qv("v1.2_3"); # alpha
+
+ # Declaring an old-style decimal $VERSION (use quotes!)
+
+ use version 0.77; our $VERSION = version->parse("1.0203"); # formal
+ use version 0.77; 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
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+ use version 0.77; # even for Perl v.5.10.0
+
+=head1 TYPES OF VERSION OBJECTS
+
+=begin original
+
+There are two different types of version objects, corresponding to the two
+different styles of versions in use:
+
+=end original
+
+There are two different types of version objects, corresponding to the two
+different styles of versions in use:
+(TBT)
+
+=over 2
+
+=item Decimal Versions
+
+=begin original
+
+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 (without
+quotes) into your source file.
+
+=end original
+
+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 (without
+quotes) into your source file.
+(TBT)
+
+=item Dotted Decimal Versions
+
+=begin original
+
+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
+strongly recommended for clarity, and will throw a warning in a future
+release if omitted.
+
+=end original
+
+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
+strongly recommended for clarity, and will throw a warning in a future
+release if omitted.
+(TBT)
+
+=back
+
+=begin original
+
+See L<VERSION OBJECT DETAILS> for further information.
+
+=end original
+
+See L<VERSION OBJECT DETAILS> for further information.
+(TBT)
+
+=head1 DECLARING VERSIONS
+
+=begin original
+
+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:
+
+=end original
+
+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:
+(TBT)
+
+ our $VERSION = 1.02;
+
+=begin original
+
+Since Perl v5.10.0 includes the version.pm comparison logic anyways,
+you don't need to do anything at all.
+
+=end original
+
+Since Perl v5.10.0 includes the version.pm comparison logic anyways,
+you don't need to do anything at all.
+(TBT)
+
+=head2 How to convert a module from decimal to dotted-decimal
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=begin original
+
+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:
+
+=end original
+
+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:
+(TBT)
+
+ $ perl -Mversion -e 'print version->parse("1.02")->normal'
+ v1.20.0
+
+=begin original
+
+Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0).
+
+=end original
+
+Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0).
+(TBT)
+
+=head2 How to C<declare()> a dotted-decimal version
+
+ use version 0.77; our $VERSION = version->declare("v1.2.3");
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=begin original
+
+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:
+
+=end original
+
+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:
+(TBT)
+
+=over 2
+
+=item *
+
+=begin original
+
+Always use a dotted-decimal with (at least) three components
+
+=end original
+
+Always use a dotted-decimal with (at least) three components
+(TBT)
+
+=item *
+
+=begin original
+
+Always use a leading-v
+
+=end original
+
+Always use a leading-v
+(TBT)
+
+=item *
+
+=begin original
+
+Always quote the version
+
+=end original
+
+Always quote the version
+(TBT)
+
+=back
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=begin original
+
+See also L<VERSION OBJECT DETAILS> for more on version number conversion,
+quoting, calculated version numbers and declaring developer or "alpha" version
+numbers.
+
+=end original
+
+See also L<VERSION OBJECT DETAILS> for more on version number conversion,
+quoting, calculated version numbers and declaring developer or "alpha" version
+numbers.
+(TBT)
+
+=head1 PARSING AND COMPARING VERSIONS
+
+=begin original
+
+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 can
+use version.pm to parse them all into objects for comparison.
+
+=end original
+
+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 can
+use version.pm to parse them all into objects for comparison.
+(TBT)
+
+=head2 How to C<parse()> a version
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=over 2
+
+=item *
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=item *
+
+=begin original
+
+Decimal: regular decimal numbers (literal or in a string)
+
+=end original
+
+Decimal: regular decimal numbers (literal or in a string)
+(TBT)
+
+=back
+
+=begin original
+
+Some examples:
+
+=end original
+
+Some examples:
+(TBT)
+
+ $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
+
+=begin original
+
+See L<VERSION OBJECT DETAILS> for more on version number conversion.
+
+=end original
+
+See L<VERSION OBJECT DETAILS> for more on version number conversion.
+(TBT)
+
+=head2 How to compare version objects
+
+=begin original
+
+Version objects overload the C<cmp> and C<< E<lt>=E<gt> >> operators. Perl
+automatically generates all of the other comparison operators based on those
+two so all the normal logical comparisons will work.
+
+=end original
+
+Version objects overload the C<cmp> and C<< E<lt>=E<gt> >> operators. Perl
+automatically generates all of the other comparison operators based on those
+two so all the normal logical comparisons will work.
+(TBT)
+
+ if ( version->parse($v1) == version->parse($v2) ) {
+ # do stuff
+ }
+
+=begin original
+
+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:
+
+=end original
+
+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:
+(TBT)
+
+ $v1 = version->parse("v0.95.0");
+ $bool = $v1 < 0.96; # FALSE since 0.96 is v0.960.0
+
+=begin original
+
+Always comparing to a version object will help avoid surprises:
+
+=end original
+
+Always comparing to a version object will help avoid surprises:
+(TBT)
+
+ $bool = $v1 < version->parse("v0.96.0"); # TRUE
+
+=head1 VERSION OBJECT DETAILS
+
+=head2 Equivalence between Decimal and Dotted-Decimal Versions
+
+=begin original
+
+When Perl 5.6.0 was released, the decision was made to provide a
+transformation between the old-style decimal versions and new-style
+dotted-decimal versions:
+
+=end original
+
+When Perl 5.6.0 was released, the decision was made to provide a
+transformation between the old-style decimal versions and new-style
+dotted-decimal versions:
+(TBT)
+
+ 5.6.0 == 5.006000
+ 5.005_04 == 5.5.40
+
+=begin original
+
+The floating point number is taken and split first on the single decimal
+place, then each group of three digits to the right of the decimal makes up
+the next digit, and so on until the number of significant digits is exhausted,
+B<plus> enough trailing zeros to reach the next multiple of three.
+
+=end original
+
+The floating point number is taken and split first on the single decimal
+place, then each group of three digits to the right of the decimal makes up
+the next digit, and so on until the number of significant digits is exhausted,
+B<plus> enough trailing zeros to reach the next multiple of three.
+(TBT)
+
+=begin original
+
+This was the method that version.pm adopted as well. Some examples may be
+helpful:
+
+=end original
+
+This was the method that version.pm adopted as well. Some examples may be
+helpful:
+(TBT)
+
+ equivalent
+ decimal zero-padded dotted-decimal
+ ------- ----------- --------------
+ 1.2 1.200 v1.200.0
+ 1.02 1.020 v1.20.0
+ 1.002 1.002 v1.2.0
+ 1.0023 1.002300 v1.2.300
+ 1.00203 1.002030 v1.2.30
+ 1.002003 1.002003 v1.2.3
+
+=head2 Quoting rules
+
+=begin original
+
+Because of the nature of the Perl parsing and tokenizing routines,
+certain initialization values B<must> be quoted in order to correctly
+parse as the intended version, especially when using the L<declare> or
+L<qv> methods. While you do not have to quote decimal numbers when
+creating version objects, it is always safe to quote B<all> initial values
+when using version.pm methods, as this will ensure that what you type is
+what is used.
+
+=end original
+
+Because of the nature of the Perl parsing and tokenizing routines,
+certain initialization values B<must> be quoted in order to correctly
+parse as the intended version, especially when using the L<declare> or
+L<qv> methods. While you do not have to quote decimal numbers when
+creating version objects, it is always safe to quote B<all> initial values
+when using version.pm methods, as this will ensure that what you type is
+what is used.
+(TBT)
+
+=begin original
+
+Additionally, if you quote your initializer, then the quoted value that goes
+B<in> will be be exactly what comes B<out> when your $VERSION is printed
+(stringified). If you do not quote your value, Perl's normal numeric handling
+comes into play and you may not get back what you were expecting.
+
+=end original
+
+Additionally, if you quote your initializer, then the quoted value that goes
+B<in> will be be exactly what comes B<out> when your $VERSION is printed
+(stringified). If you do not quote your value, Perl's normal numeric handling
+comes into play and you may not get back what you were expecting.
+(TBT)
+
+=begin original
+
+If you use a mathematic formula that resolves to a floating point number,
+you are dependent on Perl's conversion routines to yield the version you
+expect. You are pretty safe by dividing by a power of 10, for example,
+but other operations are not likely to be what you intend. For example:
+
+=end original
+
+If you use a mathematic formula that resolves to a floating point number,
+you are dependent on Perl's conversion routines to yield the version you
+expect. You are pretty safe by dividing by a power of 10, for example,
+but other operations are not likely to be what you intend. For example:
+(TBT)
+
+ $VERSION = version->new((qw$Revision: 1.4)[1]/10);
+ print $VERSION; # yields 0.14
+ $V2 = version->new(100/9); # Integer overflow in decimal number
+ print $V2; # yields something like 11.111.111.100
+
+=begin original
+
+Perl 5.8.1 and beyond are able to automatically quote v-strings but
+that is not possible in earlier versions of Perl. In other words:
+
+=end original
+
+Perl 5.8.1 and beyond are able to automatically quote v-strings but
+that is not possible in earlier versions of Perl. In other words:
+(TBT)
+
+ $version = version->new("v2.5.4"); # legal in all versions of Perl
+ $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
+
+=head2 What about v-strings?
+
+(v-文字列はどう?)
+
+=begin original
+
+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
+leading 'v' character (also bare). For example:
+
+=end original
+
+v-文字列を入力する方法は 2 つあります。
+2 つ以上の小数点を持つ裸の数値か、先頭に裸の文字 'v' があって
+1 つ以上の小数点を持つ裸の数値です。
+例えば:
+
+ $vs1 = 1.2.3; # encoded as \1\2\3
+ $vs2 = v1.2; # encoded as \1\2
+
+=begin original
+
+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.
+
+=end original
+
+しかしながら、バージョンオブジェクトを初期化するために裸のv-文字列を
+使用することは、どのような状況であっても B<強く> 非推奨です。
+Also, bare
+v-strings are not completely supported in any version of Perl prior to
+5.8.1.
+(TBT)
+
+=begin original
+
+If you insist on using bare v-strings with Perl > 5.6.0, be aware of the
+following limitations:
+
+=end original
+
+もし Perl > 5.6.0 で裸のv-文字列を使うことにこだわる場合、以下の制限に
+注意してください。
+
+=begin original
+
+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.
+
+=end original
+
+Perl のリリース 5.6.0 から 5.8.0 において、v-文字列コードはv-文字列の
+いくつかの特徴に基づいて単に推測を行うのみです。
+このヒューリスティクスが成功するためには、必ず 3 つの部分
+(例えば 1.2.3 や v1.2.3) のバージョンを使わなければ B<なりません>。
+
+=begin original
+
+2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl
+core to be magical, which means that the version.pm code can automatically
+determine whether the v-string encoding was used.
+
+=end original
+
+Perl のリリース 5.8.1 以降では、v-文字列は Perl コアでマジカルになるように
+変更されました。
+つまり、version.pm コードがv-文字列エンコーディングが使われたかどうかを
+自動的に判断できるようになったということです。
+
+=begin original
+
+3) In all cases, a version created using v-strings will have a stringified
+form that has a leading 'v' character, for the simple reason that sometimes
+it is impossible to tell whether one was present initially.
+
+=end original
+
+3) 全ての場合で、v-文字列を使って作成されたバージョンは
+文字列化形式にしたときに先頭に 'v' の文字がつきます;
+ときどき、これが先頭に付いていたかを確認することが不可能であるという
+単純な理由によります。
+
+=head2 Alpha versions
+
+(αバージョン)
+
+=begin original
+
+For module authors using CPAN, the convention has been to note unstable
+releases with an underscore in the version string. (See L<CPAN>.) version.pm
+follows this convention and alpha releases will test as being newer than the
+more recent stable release, and less than the next stable release. For
+dotted-decimal versions, only the last element may be separated by an
+underscore:
+
+=end original
+
+CPAN を使用しているモジュール作者の間で、不安定なリリースを示すために
+バージョン文字列内にアンダースコアを付ける慣習ができています。
+(L<CPAN> を参照。)
+version.pm はこの関連に従い、αリリースは、その直前の安定リリースよりも
+新しく、次の安定リリースよりも小さく判定されます。
+dotted-decimal versions, only the last element may be separated by an
+underscore:
+(TBT)
+
+
+ # Declaring
+ use version 0.77; our $VERSION = version->declare("v1.2_3");
+
+ # Parsing
+ $v1 = version->parse("v1.2_3");
+ $v1 = version->parse("1.002_003");
+
+=head1 OBJECT METHODS
+
+=head2 is_alpha()
+
+=begin original
+
+True if and only if the version object was created with a underscore, e.g.
+
+=end original
+
+True if and only if the version object was created with a underscore, e.g.
+(TBT)
+
+ version->parse('1.002_03')->is_alpha; # TRUE
+ version->declare('1.2.3_4')->is_alpha; # TRUE
+
+=head2 is_qv()
+
+=begin original
+
+True only if the version object is a dotted-decimal version, e.g.
+
+=end original
+
+True only if the version object is a dotted-decimal version, e.g.
+(TBT)
+
+ 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()
+
+=begin original
+
+Returns a string with a standard 'normalized' dotted-decimal form with a
+leading-v and at least 3 components.
+
+=end original
+
+Returns a string with a standard 'normalized' dotted-decimal form with a
+leading-v and at least 3 components.
+(TBT)
+
+ version->declare('v1.2')->normal; # v1.2.0
+ version->parse('1.2')->normal; # v1.200.0
+
+=head2 numify()
+
+=begin original
+
+Returns a value representing the object in a pure decimal form without
+trailing zeroes.
+
+=end original
+
+Returns a value representing the object in a pure decimal form without
+trailing zeroes.
+(TBT)
+
+ version->declare('v1.2')->numify; # 1.002
+ version->parse('1.2')->numify; # 1.2
+
+=head2 stringify()
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+ 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()
+
+=begin original
+
+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:
+
+=end original
+
+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:
+(TBT)
+
+ use version 0.77 ();
+
+=head1 AUTHOR
+
+John Peacock E<lt>jpeac****@cpan*****<gt>
+
+=head1 SEE ALSO
+
+L<version::Internal>.
+
+L<perl>.
+
+=begin meta
+
+Translate: Kenji Inoue <kenz****@oct*****> (0.70)
+Update: SHIRAKATA Kentaro <argra****@ub32*****> (0.74-)
+Status: in progress
+
+=end meta
+
+=cut
+