This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
remove Devel-PPPort part change included in e9105d30ed
[perl5.git] / lib / version.pod
CommitLineData
cb5772bb
RGS
1=head1 NAME
2
3version - Perl extension for Version Objects
4
5=head1 SYNOPSIS
6
7 use version;
8 $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
43eaf59d 9 print $version; # v12.2.1
cb5772bb 10 print $version->numify; # 12.002001
43eaf59d 11 if ( $version gt "12.2" ) # true
cb5772bb
RGS
12
13 $alphaver = version->new("1.02_03"); # must be quoted!
43eaf59d 14 print $alphaver; # 1.02_0300
cb5772bb
RGS
15 print $alphaver->is_alpha(); # true
16
43eaf59d 17 $ver = qv("1.2.0"); # v1.2.0
cb5772bb
RGS
18
19 $perlver = version->new(5.005_03); # must not be quoted!
20 print $perlver; # 5.005030
21
22=head1 DESCRIPTION
23
317f7c8a 24Overloaded version objects for all modern versions of Perl. This module
219bf418
RGS
25implements all of the features of version objects which are part
26of Perl 5.10.0. All previous releases (i.e. before 0.74) are deprecated
27and should not be used due to incompatible API changes. If you 'use
28version' in your code, you are strongly urged to set a minimum, e.g.
29
30 use version 0.74; # to remain compatible with Perl v5.10.0
43eaf59d
SP
31
32=head2 BEST PRACTICES
33
34If you intend for your module to be used by different releases of Perl,
35and/or for your $VERSION scalar to mean what you think it means, there
36are a few simple rules to follow:
37
38=over 4
39
40=item * Be consistent
41
42Whichever of the two types of version objects that you choose to employ,
43you should stick to either L<Numeric Versions> or L<Extended Versions>
44and not mix them together. While this is I<possible>, it is very
45confusing to the average user.
46
47If you intend to use L<Extended Versions>, you are strongly encouraged
48to use the L<qv()> operator with a quoted term, e.g.:
49
50 use version; our $VERSION = qv("1.2.3");
51
52on a single line as above.
53
54At the very least, decide on which of the several ways to initialize
55your version objects you prefer and stick with it. It is also best to
56be explicit about what value you intend to assign your version object
57and to not rely on hidden behavior of the parser.
58
59=item * Be careful
60
61If you are using Module::Build or ExtUtils::MakeMaker, so that you can
34ba6322
SP
62release your module to CPAN, you have to recognize that neither of those
63programs completely handles version objects natively (yet). If you use
64version objects with Module::Build, you should add an explicit dependency
65to the release of version.pm in your Build.PL:
66
67 my $builder = Module::Build->new(
68 ...
69 requires => {
70 ... ,
71 'version' => 0.50,
72 ...,
73 },
74 ...
75 );
76
77and it should Just Work(TM). Module::Build will [hopefully soon]
78include full support for version objects; there are no current plans
79to patch ExtUtils::MakeMaker to support version objects.
cb5772bb 80
317f7c8a
RGS
81=back
82
83=head2 Using modules that use version.pm
84
85As much as possible, the version.pm module remains compatible with all
86current code. However, if your module is using a module that has defined
87C<$VERSION> using the version class, there are a couple of things to be
88aware of. For purposes of discussion, we will assume that we have the
89following module installed:
90
91 package Example;
92 use version; $VERSION = qv('1.2.2');
93 ...module code here...
94 1;
95
96=over 4
97
98=item Numeric versions always work
99
100Code of the form:
101
102 use Example 1.002003;
103
104will always work correctly. The C<use> will perform an automatic
105C<$VERSION> comparison using the floating point number given as the first
106term after the module name (e.g. above 1.002.003). In this case, the
107installed module is too old for the requested line, so you would see an
108error like:
109
110 Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
111
112=item Extended version work sometimes
113
114With Perl >= 5.6.2, you can also use a line like this:
115
116 use Example 1.2.3;
117
118and it will again work (i.e. give the error message as above), even with
119releases of Perl which do not normally support v-strings (see L<What about
120v-strings> below). This has to do with that fact that C<use> only checks
121to see if the second term I<looks like a number> and passes that to the
122replacement L<UNIVERSAL::VERSION>. This is not true in Perl 5.005_04,
123however, so you are B<strongly encouraged> to always use a numeric version
124in your code, even for those versions of Perl which support the extended
125version.
126
127=back
128
cb5772bb
RGS
129=head2 What IS a version
130
131For the purposes of this module, a version "number" is a sequence of
43eaf59d
SP
132positive integer values separated by one or more decimal points and
133optionally a single underscore. This corresponds to what Perl itself
134uses for a version, as well as extending the "version as number" that
135is discussed in the various editions of the Camel book.
cb5772bb 136
43eaf59d 137There are actually two distinct kinds of version objects:
cb5772bb
RGS
138
139=over 4
140
141=item * Numeric Versions
142
143Any initial parameter which "looks like a number", see L<Numeric
43eaf59d 144Versions>. This also covers versions with a single decimal point and
cb5772bb
RGS
145a single embedded underscore, see L<Numeric Alpha Versions>, even though
146these must be quoted to preserve the underscore formatting.
147
7de739db 148=item * Extended Versions
cb5772bb
RGS
149
150Any initial parameter which contains more than one decimal point
43eaf59d
SP
151and an optional embedded underscore, see L<Extended Versions>. This
152is what is commonly used in most open source software as the "external"
153version (the one used as part of the tag or tarfile name). The use
154of the exported L<qv()> function also produces this kind of version
155object.
cb5772bb
RGS
156
157=back
158
159Both of these methods will produce similar version objects, in that
160the default stringification will yield the version L<Normal Form> only
161if required:
162
163 $v = version->new(1.002); # 1.002, but compares like 1.2.0
164 $v = version->new(1.002003); # 1.002003
f34c6aaf 165 $v2 = version->new("1.2.3"); # v1.2.3
cb5772bb
RGS
166
167In specific, version numbers initialized as L<Numeric Versions> will
8cb289bd
RGS
168stringify as they were originally created (i.e. the same string that was
169passed to C<new()>. Version numbers initialized as L<Extended Versions>
cb5772bb
RGS
170will be stringified as L<Normal Form>.
171
cb5772bb
RGS
172=head2 Numeric Versions
173
174These correspond to historical versions of Perl itself prior to 5.6.0,
175as well as all other modules which follow the Camel rules for the
176$VERSION scalar. A numeric version is initialized with what looks like
177a floating point number. Leading zeros B<are> significant and trailing
178zeros are implied so that a minimum of three places is maintained
179between subversions. What this means is that any subversion (digits
180to the right of the decimal place) that contains less than three digits
181will have trailing zeros added to make up the difference, but only for
182purposes of comparison with other version objects. For example:
183
43eaf59d 184 # Prints Equivalent to
8cb289bd
RGS
185 $v = version->new( 1.2); # 1.2 v1.200.0
186 $v = version->new( 1.02); # 1.02 v1.20.0
43eaf59d 187 $v = version->new( 1.002); # 1.002 v1.2.0
8cb289bd
RGS
188 $v = version->new( 1.0023); # 1.0023 v1.2.300
189 $v = version->new( 1.00203); # 1.00203 v1.2.30
43eaf59d 190 $v = version->new( 1.002003); # 1.002003 v1.2.3
cb5772bb 191
43eaf59d
SP
192All of the preceding examples are true whether or not the input value is
193quoted. The important feature is that the input value contains only a
194single decimal. See also L<Alpha Versions> for how to handle
cb5772bb 195
43eaf59d
SP
196IMPORTANT NOTE: As shown above, if your numeric version contains more
197than 3 significant digits after the decimal place, it will be split on
198each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need
199to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation.
200Any trailing zeros are ignored for mathematical comparison purposes.
cb5772bb 201
7de739db 202=head2 Extended Versions
cb5772bb
RGS
203
204These are the newest form of versions, and correspond to Perl's own
205version style beginning with 5.6.0. Starting with Perl 5.10.0,
206and most likely Perl 6, this is likely to be the preferred form. This
43eaf59d
SP
207method normally requires that the input parameter be quoted, although
208Perl's after 5.8.1 can use v-strings as a special form of quoting, but
209this is highly discouraged.
cb5772bb 210
43eaf59d
SP
211Unlike L<Numeric Versions>, Extended Versions have more than
212a single decimal point, e.g.:
cb5772bb 213
43eaf59d
SP
214 # Prints
215 $v = version->new( "v1.200"); # v1.200.0
216 $v = version->new("v1.20.0"); # v1.20.0
f34c6aaf 217 $v = qv("v1.2.3"); # v1.2.3
43eaf59d
SP
218 $v = qv("1.2.3"); # v1.2.3
219 $v = qv("1.20"); # v1.20.0
cb5772bb 220
7de739db 221In general, Extended Versions permit the greatest amount of freedom
cb5772bb
RGS
222to specify a version, whereas Numeric Versions enforce a certain
223uniformity. See also L<New Operator> for an additional method of
224initializing version objects.
225
43eaf59d
SP
226Just like L<Numeric Versions>, Extended Versions can be used as
227L<Alpha Versions>.
228
cb5772bb
RGS
229=head2 Numeric Alpha Versions
230
231The one time that a numeric version must be quoted is when a alpha form is
43eaf59d 232used with an otherwise numeric version (i.e. a single decimal point). This
cb5772bb
RGS
233is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha
234versions for automatic updating purposes. Since some developers have used
235only two significant decimal places for their non-alpha releases, the
236version object will automatically take that into account if the initializer
237is quoted. For example Module::Example was released to CPAN with the
238following sequence of $VERSION's:
239
240 # $VERSION Stringified
8cb289bd
RGS
241 0.01 0.01
242 0.02 0.02
243 0.02_01 0.02_01
244 0.02_02 0.02_02
245 0.03 0.03
cb5772bb
RGS
246 etc.
247
8cb289bd
RGS
248The stringified form of numeric versions will always be the same string
249that was used to initialize the version object.
cb5772bb
RGS
250
251=head2 Object Methods
252
253Overloading has been used with version objects to provide a natural
254interface for their use. All mathematical operations are forbidden,
f34c6aaf
JP
255since they don't make any sense for base version objects. Consequently,
256there is no overloaded numification available. If you want to use a
257version object in a numeric context for some reason, see the L<numify>
258object method.
cb5772bb
RGS
259
260=over 4
261
262=item * New Operator
263
264Like all OO interfaces, the new() operator is used to initialize
265version objects. One way to increment versions when programming is to
266use the CVS variable $Revision, which is automatically incremented by
267CVS every time the file is committed to the repository.
268
269In order to facilitate this feature, the following
270code can be employed:
271
272 $VERSION = version->new(qw$Revision: 2.7 $);
273
274and the version object will be created as if the following code
275were used:
276
277 $VERSION = version->new("v2.7");
278
279In other words, the version will be automatically parsed out of the
280string, and it will be quoted to preserve the meaning CVS normally
281carries for versions. The CVS $Revision$ increments differently from
282numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if
7de739db 283it were a L<Extended Version>.
cb5772bb
RGS
284
285A new version object can be created as a copy of an existing version
286object, either as a class method:
287
288 $v1 = version->new(12.3);
289 $v2 = version->new($v1);
290
291or as an object method:
292
293 $v1 = version->new(12.3);
f34c6aaf
JP
294 $v2 = $v1->new(12.3);
295
296and in each case, $v1 and $v2 will be identical. NOTE: if you create
297a new object using an existing object like this:
298
cb5772bb
RGS
299 $v2 = $v1->new();
300
f34c6aaf
JP
301the new object B<will not> be a clone of the existing object. In the
302example case, $v2 will be an empty object of the same type as $v1.
cb5772bb
RGS
303
304=back
305
306=over 4
307
308=item * qv()
309
310An alternate way to create a new version object is through the exported
311qv() sub. This is not strictly like other q? operators (like qq, qw),
312in that the only delimiters supported are parentheses (or spaces). It is
313the best way to initialize a short version without triggering the floating
314point interpretation. For example:
315
316 $v1 = qv(1.2); # 1.2.0
317 $v2 = qv("1.2"); # also 1.2.0
318
43eaf59d
SP
319As you can see, either a bare number or a quoted string can usually
320be used interchangably, except in the case of a trailing zero, which
321must be quoted to be converted properly. For this reason, it is strongly
322recommended that all initializers to qv() be quoted strings instead of
323bare numbers.
cb5772bb 324
92dcf8ce
JP
325To prevent the C<qv()> function from being exported to the caller's namespace,
326either use version with a null parameter:
327
328 use version ();
329
330or just require version, like this:
331
332 require version;
333
334Both methods will prevent the import() method from firing and exporting the
335C<qv()> sub. This is true of subclasses of version as well, see
336L<SUBCLASSING> for details.
337
cb5772bb
RGS
338=back
339
340For the subsequent examples, the following three objects will be used:
341
342 $ver = version->new("1.2.3.4"); # see "Quoting" below
343 $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
43eaf59d 344 $nver = version->new(1.002); # see "Numeric Versions" above
cb5772bb
RGS
345
346=over 4
347
348=item * Normal Form
349
350For any version object which is initialized with multiple decimal
351places (either quoted or if possible v-string), or initialized using
352the L<qv()> operator, the stringified representation is returned in
353a normalized or reduced form (no extraneous zeros), and with a leading 'v':
354
43eaf59d 355 print $ver->normal; # prints as v1.2.3.4
cb5772bb
RGS
356 print $ver->stringify; # ditto
357 print $ver; # ditto
358 print $nver->normal; # prints as v1.2.0
359 print $nver->stringify; # prints as 1.002, see "Stringification"
360
361In order to preserve the meaning of the processed version, the
362normalized representation will always contain at least three sub terms.
363In other words, the following is guaranteed to always be true:
364
365 my $newver = version->new($ver->stringify);
366 if ($newver eq $ver ) # always true
367 {...}
368
369=back
370
371=over 4
372
373=item * Numification
374
375Although all mathematical operations on version objects are forbidden
43eaf59d
SP
376by default, it is possible to retrieve a number which corresponds
377to the version object through the use of the $obj->numify
cb5772bb
RGS
378method. For formatting purposes, when displaying a number which
379corresponds a version object, all sub versions are assumed to have
380three decimal places. So for example:
381
43eaf59d 382 print $ver->numify; # prints 1.002003004
cb5772bb
RGS
383 print $nver->numify; # prints 1.002
384
385Unlike the stringification operator, there is never any need to append
386trailing zeros to preserve the correct version value.
387
388=back
389
390=over 4
391
392=item * Stringification
393
8cb289bd
RGS
394The default stringification for version objects returns exactly the same
395string as was used to create it, whether you used C<new()> or C<qv()>,
396with one exception. The sole exception is if the object was created using
397C<qv()> and the initializer did not have two decimal places or a leading
398'v' (both optional), then the stringified form will have a leading 'v'
399prepended, in order to support round-trip processing.
cb5772bb 400
8cb289bd 401For example:
cb5772bb 402
8cb289bd
RGS
403 Initialized as Stringifies to
404 ============== ==============
405 version->new("1.2") 1.2
406 version->new("v1.2") v1.2
407 qv("1.2.3") 1.2.3
408 qv("v1.3.5") v1.3.5
409 qv("1.2") v1.2 ### exceptional case
cb5772bb 410
8cb289bd
RGS
411See also L<UNIVERSAL::VERSION>, as this also returns the stringified form
412when used as a class method.
cb5772bb 413
219bf418
RGS
414IMPORTANT NOTE: There is one exceptional cases shown in the above table
415where the "initializer" is not stringwise equivalent to the stringified
416representation. If you use the C<qv()> operator on a version without a
417leading 'v' B<and> with only a single decimal place, the stringified output
418will have a leading 'v', to preserve the sense. See the L<qv()> operator
419for more details.
420
421IMPORTANT NOTE 2: Attempting to bypass the normal stringification rules by
422manually applying L<numify()> and L<normal()> will sometimes yield
423surprising results:
424
425 print version->new(version->new("v1.0")->numify)->normal; # v1.0.0
426
427The reason for this is that the L<numify()> operator will turn "v1.0"
428into the equivalent string "1.000000". Forcing the outer version object
429to L<normal()> form will display the mathematically equivalent "v1.0.0".
430
431As the example in L<new()> shows, you can always create a copy of an
432existing version object with the same value by the very compact:
433
434 $v2 = $v1->new($v1);
435
436and be assured that both C<$v1> and C<$v2> will be completely equivalent,
437down to the same internal representation as well as stringification.
438
cb5772bb
RGS
439=back
440
441=over 4
442
443=item * Comparison operators
444
43eaf59d
SP
445Both C<cmp> and C<E<lt>=E<gt>> operators perform the same comparison between
446terms (upgrading to a version object automatically). Perl automatically
cb5772bb
RGS
447generates all of the other comparison operators based on those two.
448In addition to the obvious equalities listed below, appending a single
449trailing 0 term does not change the value of a version for comparison
450purposes. In other words "v1.2" and "1.2.0" will compare as identical.
451
452For example, the following relations hold:
453
43eaf59d
SP
454 As Number As String Truth Value
455 ------------- ---------------- -----------
456 $ver > 1.0 $ver gt "1.0" true
457 $ver < 2.5 $ver lt true
458 $ver != 1.3 $ver ne "1.3" true
459 $ver == 1.2 $ver eq "1.2" false
460 $ver == 1.2.3.4 $ver eq "1.2.3.4" see discussion below
cb5772bb
RGS
461
462It is probably best to chose either the numeric notation or the string
463notation and stick with it, to reduce confusion. Perl6 version objects
43eaf59d 464B<may> only support numeric comparisons. See also L<Quoting>.
cb5772bb 465
43eaf59d 466WARNING: Comparing version with unequal numbers of decimal points (whether
cb5772bb
RGS
467explicitly or implicitly initialized), may yield unexpected results at
468first glance. For example, the following inequalities hold:
469
470 version->new(0.96) > version->new(0.95); # 0.960.0 > 0.950.0
471 version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0
472
473For this reason, it is best to use either exclusively L<Numeric Versions> or
43eaf59d 474L<Extended Versions> with multiple decimal points.
cb5772bb
RGS
475
476=back
477
478=over 4
479
480=item * Logical Operators
481
482If you need to test whether a version object
483has been initialized, you can simply test it directly:
484
485 $vobj = version->new($something);
486 if ( $vobj ) # true only if $something was non-blank
487
488You can also test whether a version object is an L<Alpha version>, for
489example to prevent the use of some feature not present in the main
490release:
491
492 $vobj = version->new("1.2_3"); # MUST QUOTE
493 ...later...
494 if ( $vobj->is_alpha ) # True
495
496=back
497
498=head2 Quoting
499
500Because of the nature of the Perl parsing and tokenizing routines,
501certain initialization values B<must> be quoted in order to correctly
43eaf59d
SP
502parse as the intended version, especially when using the L<qv()> operator.
503In all cases, a floating point number passed to version->new() will be
504identically converted whether or not the value itself is quoted. This is
505not true for L<qv()>, however, when trailing zeros would be stripped on
506an unquoted input, which would result in a very different version object.
507
508In addition, in order to be compatible with earlier Perl version styles,
509any use of versions of the form 5.006001 will be translated as v5.6.1.
510In other words, a version with a single decimal point will be parsed as
511implicitly having three digits between subversions, but only for internal
512comparison purposes.
cb5772bb
RGS
513
514The complicating factor is that in bare numbers (i.e. unquoted), the
515underscore is a legal numeric character and is automatically stripped
516by the Perl tokenizer before the version code is called. However, if
517a number containing one or more decimals and an underscore is quoted, i.e.
518not bare, that is considered a L<Alpha Version> and the underscore is
519significant.
520
521If you use a mathematic formula that resolves to a floating point number,
522you are dependent on Perl's conversion routines to yield the version you
523expect. You are pretty safe by dividing by a power of 10, for example,
524but other operations are not likely to be what you intend. For example:
525
526 $VERSION = version->new((qw$Revision: 1.4)[1]/10);
527 print $VERSION; # yields 0.14
528 $V2 = version->new(100/9); # Integer overflow in decimal number
529 print $V2; # yields something like 11.111.111.100
530
531Perl 5.8.1 and beyond will be able to automatically quote v-strings but
532that is not possible in earlier versions of Perl. In other words:
533
534 $version = version->new("v2.5.4"); # legal in all versions of Perl
535 $newvers = version->new(v2.5.4); # legal only in Perl >= 5.8.1
536
43eaf59d
SP
537=head2 What about v-strings?
538
539Beginning with Perl 5.6.0, an alternate method to code arbitrary strings
540of bytes was introduced, called v-strings. They were intended to be an
541easy way to enter, for example, Unicode strings (which contain two bytes
542per character). Some programs have used them to encode printer control
543characters (e.g. CRLF). They were also intended to be used for $VERSION,
544but their use as such has been problematic from the start.
545
546There are two ways to enter v-strings: a bare number with two or more
547decimal points, or a bare number with one or more decimal points and a
548leading 'v' character (also bare). For example:
549
550 $vs1 = 1.2.3; # encoded as \1\2\3
551 $vs2 = v1.2; # encoded as \1\2
552
f34c6aaf
JP
553However, the use of bare v-strings to initialize version objects is
554B<strongly> discouraged in all circumstances (especially the leading
555'v' style), since the meaning will change depending on which Perl you
556are running. It is better to directly use L<"Extended Versions"> to
557ensure the proper interpretation.
558
559If you insist on using bare v-strings with Perl > 5.6.0, be aware of the
560following limitations:
43eaf59d 561
f34c6aaf
JP
5621) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses,
563based on some characteristics of v-strings. You B<must> use a three part
564version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.
565
5662) For Perl releases 5.8.1 and later, v-strings have changed in the Perl
567core to be magical, which means that the version.pm code can automatically
568determine whether the v-string encoding was used.
cb5772bb 569
8cb289bd
RGS
5703) In all cases, a version created using v-strings will have a stringified
571form that has a leading 'v' character, for the simple reason that sometimes
572it is impossible to tell whether one was present initially.
573
cb5772bb
RGS
574=head2 Types of Versions Objects
575
576There are two types of Version Objects:
577
578=over 4
579
580=item * Ordinary versions
581
582These are the versions that normal modules will use. Can contain as
583many subversions as required. In particular, those using RCS/CVS can
584use the following:
585
586 $VERSION = version->new(qw$Revision: 2.7 $);
587
588and the current RCS Revision for that file will be inserted
589automatically. If the file has been moved to a branch, the Revision
590will have three or more elements; otherwise, it will have only two.
591This allows you to automatically increment your module version by
592using the Revision number from the primary file in a distribution, see
593L<ExtUtils::MakeMaker/"VERSION_FROM">.
594
595=item * Alpha Versions
596
597For module authors using CPAN, the convention has been to note
598unstable releases with an underscore in the version string, see
599L<CPAN>. Alpha releases will test as being newer than the more recent
600stable release, and less than the next stable release. For example:
601
602 $alphaver = version->new("12.03_01"); # must be quoted
603
604obeys the relationship
605
606 12.03 < $alphaver < 12.04
607
43eaf59d 608Alpha versions with a single decimal point will be treated exactly as if
8cb289bd
RGS
609they were L<Numeric Versions>, for parsing and output purposes. The
610underscore will be output when an alpha version is stringified, in the same
611place as it was when input.
cb5772bb 612
43eaf59d 613Alpha versions with more than a single decimal point will be treated
7de739db 614exactly as if they were L<Extended Versions>, and will display without any
cb5772bb
RGS
615trailing (or leading) zeros, in the L<Version Normal> form. For example,
616
617 $newver = version->new("12.3.1_1");
618 print $newver; # v12.3.1_1
619
f34c6aaf
JP
620=back
621
cb5772bb
RGS
622=head2 Replacement UNIVERSAL::VERSION
623
624In addition to the version objects, this modules also replaces the core
625UNIVERSAL::VERSION function with one that uses version objects for its
8cb289bd
RGS
626comparisons. The return from this operator is always the stringified form,
627but the warning message generated includes either the stringified form or
628the normal form, depending on how it was called.
cb5772bb
RGS
629
630For example:
631
632 package Foo;
633 $VERSION = 1.2;
634
635 package Bar;
636 $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)
637
638 package main;
639 use version;
640
641 print $Foo::VERSION; # prints 1.2
642
643 print $Bar::VERSION; # prints 1.003005
644
8cb289bd
RGS
645 eval "use foo 10";
646 print $@; # prints "foo version 10 required..."
647 eval "use foo 1.3.5; # work in Perl 5.6.1 or better
648 print $@; # prints "foo version 1.3.5 required..."
649
650 eval "use bar 1.3.6";
651 print $@; # prints "bar version 1.3.6 required..."
652 eval "use bar 1.004"; # note numeric version
653 print $@; # prints "bar version 1.004 required..."
654
cb5772bb
RGS
655
656IMPORTANT NOTE: This may mean that code which searches for a specific
657string (to determine whether a given module is available) may need to be
8cb289bd
RGS
658changed. It is always better to use the built-in comparison implicit in
659C<use> or C<require>, rather than manually poking at C<class->VERSION>
660and then doing a comparison yourself.
cb5772bb
RGS
661
662The replacement UNIVERSAL::VERSION, when used as a function, like this:
663
664 print $module->VERSION;
665
8cb289bd
RGS
666will also exclusively return the stringified form. See L<Stringification>
667for more details.
cb5772bb
RGS
668
669=head1 SUBCLASSING
670
671This module is specifically designed and tested to be easily subclassed.
672In practice, you only need to override the methods you want to change, but
673you have to take some care when overriding new() (since that is where all
674of the parsing takes place). For example, this is a perfect acceptable
675derived class:
676
677 package myversion;
678 use base version;
679 sub new {
680 my($self,$n)=@_;
681 my $obj;
682 # perform any special input handling here
683 $obj = $self->SUPER::new($n);
684 # and/or add additional hash elements here
685 return $obj;
686 }
687
688See also L<version::AlphaBeta> on CPAN for an alternate representation of
689version strings.
690
92dcf8ce
JP
691B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
692function exported into the caller's namespace, a subclass of version will
693inherit an import() function which will perform the correct magic on behalf
694of the subclass.
cb5772bb
RGS
695
696=head1 EXPORT
697
7de739db 698qv - Extended Version initialization operator
cb5772bb
RGS
699
700=head1 AUTHOR
701
702John Peacock E<lt>jpeacock@cpan.orgE<gt>
703
704=head1 SEE ALSO
705
706L<perl>.
707
708=cut