versionomy 0.1.3 → 0.2.0

data/History.rdoc

@@ -1,6 +1,20 @@
+=== 0.2.0 / 2009-11-05
+
+* API CHANGE: Slight change to value comparison semantics. Value#eql? returns true only if the schemas are the same, whereas Value#== and the greater than and less than comparisons attempt to compare the semantic value, and thus may perform automatic schema conversion on the RHS.
+* API CHANGE: Merged Formats namespace into Format. Versionomy::Formats is now a (deprecated) alias for Versionomy::Format.
+* API CHANGE: The delimiter parsing algorithm now defaults :extra_characters to :error instead of :ignore.
+* Added a mechanism for converting from one format/schema to another.
+* Added Rubygems format, along with conversions to and from the standard format.
+* Values now include Comparable.
+* Values can now be serialized using Marshal and YAML.
+* Schemas can now add custom methods to value objects. Added "prerelease?" and "release" methods to rubygems and standard format values.
+* Added default field settings to schema DSL.
+* Implemented #=== for schemas and formats.
+* Many minor bug fixes and documentation updates.
+
 === 0.1.3 / 2009-10-29
 
-* Fixed an issue with parsing the "-p" patchlevel delimiter (e.g. "1.9.1-p243").
+* Fixed an issue with parsing the "-p" patchlevel delimiter, e.g. "1.9.1-p243". (Reported by Luis Lavena.)
 
 === 0.1.2 / 2009-10-28
 

data/README.rdoc

@@ -4,15 +4,46 @@ Versionomy is a generalized version number library.
 It provides tools to represent, manipulate, parse, and compare version
 numbers in the wide variety of versioning schemes in use.
 
+=== Version numbers done right?
+
+Let's be honest. Version numbers are not easy to deal with, and very
+seldom seem to be done right.
+Imagine the common case of testing the Ruby version. Most of us, if we
+need to worry about Ruby VM compatibility, will do something like:
+ 
+ do_something if RUBY_VERSION >= "1.8.7"
+
+Treating the version number as a string works well enough, until it
+doesn't. The above code will do the right thing for Ruby 1.8.6, 1.8.7,
+1.8.8, and 1.9.1. But it will fail if the version is "1.8.10".
+
+There are a few version number classes out there that do better than
+treating version numbers as plain strings. One well-known class is
+Gem::Version, part of rubygems. This class separates the version into
+fields and lets you manipulate and compare version numbers more robustly.
+It provides limited support for "prerelease" versions through using
+string-valued fields as a bit of a hack. However, it's still a little
+clumsy. A prerelease version has to be represented like this: "1.9.2.b.1"
+or "1.9.2.preview.2". Wouldn't it be nice to be able to parse more typical
+version number formats such as "1.9.2b1" and "1.9.2 preview-2"? Wouldn't
+it be nice for a version like "1.9.2b1" to _understand_ that it's a "beta"
+version and behave accordingly?
+
+With Versionomy, you can!
+
 === Some examples
 
  require 'versionomy'
  
- v1 = Versionomy.parse('1.3.2')
+ # Create version numbers that understand their own semantics
+ v1 = Versionomy.create(:major => 1, :minor => 3, :tiny => 2)
  v1.major                                 # => 1
  v1.minor                                 # => 3
  v1.tiny                                  # => 2
+ v1.release_type                          # => :final
+ v1.patchlevel                            # => 0
  
+ # Parse version numbers, including common prerelease syntax
  v2 = Versionomy.parse('1.4a3')
  v2.major                                 # => 1
  v2.minor                                 # => 4
@@ -20,7 +51,9 @@ numbers in the wide variety of versioning schemes in use.
  v2.release_type                          # => :alpha
  v2.alpha_version                         # => 3
  v2 > v1                                  # => true
+ v2.to_s                                  # => '1.4a3'
  
+ # Another parsing example.
  v3 = Versionomy.parse('1.4.0b2')
  v3.major                                 # => 1
  v3.minor                                 # => 4
@@ -31,29 +64,44 @@ numbers in the wide variety of versioning schemes in use.
  v3 > v2                                  # => true
  v3.to_s                                  # => '1.4.0b2'
  
- v4 = v3.bump(:beta_version)
+ # You can bump any field
+ v4 = Versionomy.parse('1.4.0b2').bump(:beta_version)
  v4.to_s                                  # => '1.4.0b3'
+ v5 = v4.bump(:tiny)
+ v5.to_s                                  # => '1.4.1'
  
- v5 = v4.bump(:release_type)
- v5.to_s                                  # => '1.4.0rc1'
- 
- v6 = v5.bump(:release_type)
- v6.to_s                                  # => '1.4.0'
- 
- v7 = v3.bump(:tiny)
- v7.to_s                                  # => '1.4.1'
+ # Bumping the release type works as you would expect
+ v6 = Versionomy.parse('1.4.0b2').bump(:release_type)
+ v6.release_type                          # => :release_candidate
+ v6.to_s                                  # => '1.4.0rc1'
+ v7 = v6.bump(:release_type)
+ v7.release_type                          # => :final
+ v7.to_s                                  # => '1.4.0'
  
- v8 = v3.bump(:major)
+ # If a version has trailing zeros, it remembers how many fields to
+ # unparse; however, you can also change this.
+ v8 = Versionomy.parse('1.4.0b2').bump(:major)
  v8.to_s                                  # => '2.0.0'
  v8.unparse(:optional_fields => [:tiny])  # => '2.0'
+ v8.unparse(:required_fields => [:tiny2]) # => '2.0.0.0'
  
+ # Comparisons are semantic, so will behave as expected even if the
+ # formatting is set up differently.
  v9 = Versionomy.parse('2.0.0.0')
  v9.to_s                                  # => '2.0.0.0'
- v9 == v8                                 # => true
+ v9 == Versionomy.parse('2')              # => true
  
- v10 = v8.bump(:patchlevel)
+ # Patchlevels are supported when the release type is :final
+ v10 = Versionomy.parse('2.0.0').bump(:patchlevel)
+ v10.patchlevel                           # => 1
  v10.to_s                                 # => '2.0.0-1'
+ v11 = Versionomy.parse('2.0p1')
+ v11.patchlevel                           # => 1
+ v11.to_s                                 # => '2.0p1'
+ v11 == v10                               # => true
  
+ # You can create your own format from scratch or by modifying an
+ # existing format
  microsoft_format = Versionomy.default_format.modified_copy do
    field(:minor) do
      recognize_number(:default_value_optional => true,
@@ -61,12 +109,12 @@ numbers in the wide variety of versioning schemes in use.
                       :default_delimiter => ' SP')
    end
  end
- v11 = microsoft_format.parse('2008 SP2')
- v11.major                                # => 2008
- v11.minor                                # => 2
- v11.tiny                                 # => 0
- v11.to_s                                 # => '2008 SP2'
- v11 == Versionomy.parse('2008.2')        # => true
+ v12 = microsoft_format.parse('2008 SP2')
+ v12.major                                # => 2008
+ v12.minor                                # => 2
+ v12.tiny                                 # => 0
+ v12.to_s                                 # => '2008 SP2'
+ v12 == Versionomy.parse('2008.2')        # => true
 
 === Feature list
 
@@ -82,12 +130,15 @@ custom formats.
 
 Finally, Versionomy also lets you to create alternate versioning "schemas".
 You can define any number of version number fields, and provide your own
-semantics for comparing, parsing, and modifying version numbers.
+semantics for comparing, parsing, and modifying version numbers. You can
+provide conversions from one schema to another. As an example, Versionomy
+provides a schema and formatter/parser matching Gem::Version.
 
 === Requirements
 
-* Ruby 1.8.6 or later (1.8.7 recommended), Ruby 1.9.1 or later, or JRuby 1.4 or later.
-* blockenspiel gem.
+* Ruby 1.8.6 or later (1.8.7 recommended), Ruby 1.9.1 or later, or JRuby
+  1.4 or later.
+* blockenspiel 0.3 or later.
 
 === Installation
 

data/Rakefile

@@ -89,7 +89,7 @@ gemspec_ = Gem::Specification.new do |s_|
   s_.has_rdoc = true
   s_.test_files = FileList['tests/tc_*.rb']
   s_.platform = Gem::Platform::RUBY
-  s_.add_dependency('blockenspiel', '>= 0.2.2')
+  s_.add_dependency('blockenspiel', '>= 0.3.0')
 end
 Rake::GemPackageTask.new(gemspec_) do |task_|
   task_.need_zip = false

data/lib/versionomy/{formats.rb → conversion/base.rb}

@@ -1,6 +1,6 @@
 # -----------------------------------------------------------------------------
 # 
-# Versionomy format registry
+# Versionomy conversion base class
 # 
 # -----------------------------------------------------------------------------
 # Copyright 2008-2009 Daniel Azuma
@@ -37,51 +37,50 @@
 module Versionomy
   
   
-  # === Version number format regsitry.
-  # 
-  # Use the methods of this module to register formats with a name. This
-  # allows version numbers to be serialized with their format.
-  # 
-  # You may also access predefined formats such as the standard format from
-  # this module. It also contains the implementations of these formats as
-  # examples.
-  
-  module Formats
-    
-    
-    @names = ::Hash.new
+  module Conversion
     
     
-    # Get the format with the given name.
+    # The base conversion class.
     # 
-    # If the given name has not been defined, and strict is set to true,
-    # raises Versionomy::Errors::UnknownFormatError. If strict is set to
-    # false, returns nil if the given name has not been defined.
+    # This base class defines the API for a conversion. All conversions must
+    # define the method <tt>convert_value</tt> documented here. Conversions
+    # need not actually extend this base class, as long as they duck-type
+    # this method. However, this base class does provide a few convenience
+    # methods such as a sane implementation of inspect.
     
-    def self.get(name_, strict_=false)
-      format_ = @names[name_.to_s]
-      if format_.nil? && strict_
-        raise Errors::UnknownFormatError, name_
+    class Base
+      
+      
+      # Convert the given value to the given format and return the converted
+      # value.
+      # 
+      # The convert_params may be interpreted however the particular
+      # conversion wishes.
+      # 
+      # Raises Versionomy::Errors::ConversionError if the conversion failed.
+      
+      def convert_value(value_, format_, convert_params_=nil)
+        raise Errors::ConversionError, "Conversion not implemented"
       end
-      format_
-    end
-    
-    
-    # Register the given format under the given name.
-    # 
-    # Raises Versionomy::Errors::FormatRedefinedError if the name has
-    # already been defined.
-    
-    def self.register(name_, format_)
-      name_ = name_.to_s
-      if @names.include?(name_)
-        raise Errors::FormatRedefinedError, name_
+      
+      
+      # Inspect this conversion.
+      
+      def inspect
+        "#<#{self.class}:0x#{object_id.to_s(16)}>"
       end
-      @names[name_] = format_
+      
+      
+      # The default to_s implementation just calls inspect.
+      
+      def to_s
+        inspect
+      end
+      
+      
     end
     
     
   end
   
-  
 end

data/lib/versionomy/conversion/parsing.rb

@@ -0,0 +1,173 @@
+# -----------------------------------------------------------------------------
+# 
+# Versionomy conversion base class
+# 
+# -----------------------------------------------------------------------------
+# Copyright 2008-2009 Daniel Azuma
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# -----------------------------------------------------------------------------
+;
+
+
+module Versionomy
+  
+  
+  module Conversion
+    
+    
+    # A conversion strategy that relies on parsing.
+    # Essentially, it unparses the value and then attempts to parse it with
+    # the new format.
+    
+    class Parsing < Base
+      
+      
+      # Create a parsing conversion.
+      # 
+      # By default, this just unparses and reparses using the default
+      # parse settings. In some cases, this may be enough, but you may
+      # wish to improve the reliability of the conversion by tweaking the
+      # parsing settings. To do so, pass a block to the new method, and
+      # call methods of Versionomy::Conversion::Parsing::Builder in that
+      # block.
+      
+      def initialize(&block_)
+        if block_
+          builder_ = Builder.new
+          ::Blockenspiel.invoke(block_, builder_)
+          @string_modifier = builder_._get_string_modifier
+          @unparse_params_modifier = builder_._get_unparse_params_modifier
+          @parse_params_generator ||= builder_._get_parse_params_generator
+        end
+      end
+      
+      
+      # Returns a value equivalent to the given value in the given format.
+      # 
+      # The convert_params are passed to this conversion's customization
+      # blocks (if any).
+      # 
+      # Raises Versionomy::Errors::ConversionError if the conversion failed.
+      # Typically, this is due to a failure of the parsing or unparsing.
+      
+      def convert_value(value_, format_, convert_params_=nil)
+        begin
+          unparse_params_ = value_.unparse_params
+          if @unparse_params_modifier
+            unparse_params_ = @unparse_params_modifier.call(unparse_params_, convert_params_)
+          end
+          string_ = value_.unparse(unparse_params_)
+          if @string_modifier
+            string_ = @string_modifier.call(string_, convert_params_)
+          end
+          if @parse_params_generator
+            parse_params_ = @parse_params_generator.call(convert_params_)
+          else
+            parse_params_ = nil
+          end
+          new_value_ = format_.parse(string_, parse_params_)
+          return new_value_
+        rescue Errors::UnparseError => ex_
+          raise Errors::ConversionError, "Unparsing failed: #{ex_.inspect}"
+        rescue Errors::ParseError => ex_
+          raise Errors::ConversionError, "Parsing failed: #{ex_.inspect}"
+        end
+      end
+      
+      
+      # Call methods of this class in the block passed to
+      # Versionomy::Conversion::Parsing#new to fine-tune the behavior of
+      # the converter.
+      
+      class Builder
+        
+        include ::Blockenspiel::DSL
+        
+        
+        def initialize  # :nodoc:
+          @string_modifier = nil
+          @parse_params_generator = nil
+          @unparse_params_modifier = nil
+        end
+        
+        
+        # Provide a block that generates the params used to parse the new
+        # value. The block should take one parameter, the convert_params
+        # passed to convert_value (which may be nil). It should return the
+        # parse params that should be used.
+        
+        def to_generate_parse_params(&block_)
+          @parse_params_generator = block_
+        end
+        
+        
+        # Provide a block that can modify the params used to unparse the
+        # old value. The block should take two parameters: first, the
+        # original unparse params from the old value (which may be nil),
+        # and second, the convert_params passed to convert_value (which
+        # may also be nil). It should return the unparse params that
+        # should actually be used.
+        
+        def to_modify_unparse_params(&block_)
+          @unparse_params_modifier = block_
+        end
+        
+        
+        # Provide a block that can modify the unparsed string prior to
+        # it being passed to the parser. The block should take two
+        # parameters: first, the string resulting from unparsing the old
+        # value, and second, the convert_params passed to convert_value
+        # (which may be nil). It should return the string to be parsed to
+        # get the new value.
+        
+        def to_modify_string(&block_)
+          @string_modifier = block_
+        end
+        
+        
+        def _get_string_modifier  # :nodoc:
+          @string_modifier
+        end
+        
+        def _get_unparse_params_modifier  # :nodoc:
+          @unparse_params_modifier
+        end
+        
+        def _get_parse_params_generator  # :nodoc:
+          @parse_params_generator
+        end
+        
+      end
+      
+      
+    end
+    
+    
+  end
+  
+end

data/lib/versionomy/conversion/rubygems.rb

@@ -0,0 +1,138 @@
+# -----------------------------------------------------------------------------
+# 
+# Versionomy standard format implementation
+# 
+# -----------------------------------------------------------------------------
+# Copyright 2008-2009 Daniel Azuma
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# -----------------------------------------------------------------------------
+;
+
+
+module Versionomy
+  
+  module Conversion
+    
+    
+    # This is a namespace for the implementation of the conversion between
+    # the rubygems and standard formats.
+    
+    module Rubygems
+      
+      
+      # Create the conversion from standard to rubygems format.
+      # This method is called internally when Versionomy initializes itself,
+      # and you should not need to call it again. It is documented, however,
+      # so that you can inspect its source code from RDoc, since the source
+      # contains useful examples of how to use the conversion DSLs.
+        
+      def self.create_standard_to_rubygems
+        
+        # We'll use a parsing conversion.
+        Conversion::Parsing.new do
+          
+          # We're going to modify how the standard format version is
+          # unparsed, so the rubygems format will have a better chance
+          # of parsing it.
+          to_modify_unparse_params do |params_, convert_params_|
+            
+            params_ ||= {}
+            
+            # If the standard format version has a prerelease notation,
+            # make sure it is set off using a delimiter that the rubygems
+            # format can recognized. So instead of "1.0b2", we force the
+            # unparsing to generate "1.0.b.2".
+            params_[:release_type_delim] = '.'
+            params_[:release_type_postdelim] = '.'
+            
+            # If the standard format version has a patchlevel notation,
+            # force it to use the default number rather than letter style.
+            # So instead of "1.2c", we force the unparsing to generate
+            # "1.2-3".
+            params_[:patchlevel_style] = nil
+            
+            # If the standard format version has a patchlevel notation,
+            # force it to use the default delimiter of "-" so the rubygems
+            # format will recognize it. So instead of "1.9.1p243", we force
+            # the unparsing to generate "1.9.1-243".
+            params_[:patchlevel_delim] = nil
+            
+            params_
+          end
+          
+          # Standard formats sometimes allow hyphens and spaces in field
+          # delimiters, but the rubygems format requires periods. So modify
+          # the unparsed string to conform to rubygems's expectations.
+          to_modify_string do |str_, convert_params_|
+            str_.gsub(/[\.\s-]+/, '.')
+          end
+          
+        end
+        
+      end
+      
+      
+      # Create the conversion from rubygems to standard format.
+      # This method is called internally when Versionomy initializes itself,
+      # and you should not need to call it again. It is documented, however,
+      # so that you can inspect its source code from RDoc, since the source
+      # contains useful examples of how to use the conversion DSLs.
+      
+      def self.create_rubygems_to_standard
+        
+        # We'll use a parsing conversion.
+        Conversion::Parsing.new do
+          
+          # Handle the case where the rubygems version ends with a string
+          # field, e.g. "1.0.b". We want to treat this like "1.0b0" rather
+          # than "1.0-2" since the rubygems semantic states that this is a
+          # prerelease version. So we add 0 to the end of the parsed string
+          # if it ends in a letter.
+          to_modify_string do |str_, convert_params_|
+            str_.gsub(/([[:alpha:]])\z/, '\10')
+          end
+          
+        end
+        
+      end
+      
+      
+      unless Conversion.get(:standard, :rubygems)
+        Conversion.register(:standard, :rubygems, create_standard_to_rubygems)
+      end
+      unless Conversion.get(:rubygems, :standard)
+        Conversion.register(:rubygems, :standard, create_rubygems_to_standard)
+      end
+      
+      
+    end
+    
+    
+  end
+  
+end