This was an e-mail that David Golden sent to p5p in November 2008; does his suggested changes make more sense (modulo the fact that there is no version->parse sub)?
John
--- Begin Message ---I've started looking over the version.pm POD to see what would be required to describe it in terms of declare() and parse(). So far, I've just been playing with the synopsis on the assumption that many people will stop reading the documentation there. And as I do it, I'm reminded again of why this gets so complex, particularly for alpha versions. But I think I can describe "best practices" for module authors that should keep both new dotted-decimal version authors and old decimal version authors out of trouble. Generally, for declarations, I think the rule is to always use quotes and always put a leading "v" for dotted-decimal style. Again this is the "versions for dummies" approach -- trying to make it hard to screw up. Yes, TIMTOWTDI, but not in the synopsis. :-) The one place that approach breaks down is for Perl version numbers, where 5.005_03 shouldn't be quoted if used with new(). To that end, I suggest adding another affordance like this: version->perl("5.005_03") I think all it needs to do internally is eval the argument and pass it to version->new(). This ensures that version->perl(5.00503) == version->perl("5.005_03"). There is still room for error (5.10.0 vs 5.10 vs 5.010) but I think the synopsis example will guide people to correct usage. So with that function added, here's my rough cut at a new synopsis: # Parsing version strings (decimal or dotted-decimal) use version; $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!) use version; our $VERSION = version->parse("1.0203"); # formal use version; our $VERSION = version->parse("1.02_03"); # alpha # Specifying a version of Perl $ver = version->perl("5.005_03"); # decimal (old style) $ver = version->perl("5.010"); # decimal $ver = version->perl("5.10.0"); # dotted-decimal # 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; Anyone interested, please comment if you think this is helpful, not helpful, could be clearer, etc. John -- I've been doing this work on an SVK mirror of the svn.perl.org repository trunk, so if you think I'm on the right path, I can either send you the resulting patch when I'm done or you can give me a commit bit. My username on svn.perl.org is "dagolden". -- David
--- End Message ---
