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