versionomy 0.1.3 → 0.2.0

data/lib/versionomy/conversion.rb

@@ -0,0 +1,145 @@
+# -----------------------------------------------------------------------------
+# 
+# Versionomy conversion interface and registry
+# 
+# -----------------------------------------------------------------------------
+# 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
+  
+  
+  # === Conversion between version schemas.
+  # 
+  # Conversions are algorithms for converting from one schema to another.
+  # This is useful for performing conversions as well as comparing version
+  # numbers that use different schemas.
+  # 
+  # To implement a conversion algorithm, implement the API defined by
+  # Versionomy::Conversion::Base. Then, register your conversion by calling
+  # Versionomy::Conversion#register. You will need to specify which schemas
+  # (from and to) that your conversion should handle. From that point on,
+  # whenever Versionomy needs to convert a value between those two schemas,
+  # it will use your conversion. You can register the same conversion object
+  # for multiple pairs of schemas, but you can register only one conversion
+  # object for any pair.
+  # 
+  # A common technique for doing conversions is to unparse the version to a
+  # string, and then parse it in the new format. Versionomy provides a tool,
+  # Versionomy::Conversion::Parsing, for performing such conversions. The
+  # conversions between the standard and rubygems formats uses this tool.
+  # See Versionomy::Conversion::Rubygems for annotated examples.
+  
+  module Conversion
+    
+    @registry = ::Hash.new
+    
+    class << self
+      
+      
+      # Convert the given value to the given format. This is identical to
+      # calling <tt>value_.convert(format_, convert_params_)</tt>.
+      # 
+      # The format may be specified as a format object or as the name of a
+      # format in the Format registry.
+      # 
+      # Raises Versionomy::Errors::ConversionError if the value could not
+      # be converted.
+      
+      def convert(value_, format_, convert_params_=nil)
+        value_.convert(format_, convert_params_)
+      end
+      
+      
+      # Get a conversion capable of converting between the given schemas.
+      # 
+      # The schemas may be specified as format names, Format objects,
+      # schema wrapper objects, or the root field of the schema.
+      # 
+      # If strict is set to false, returns nil if no such conversion could
+      # be found. If strict is set to true, may raise one of these errors:
+      # 
+      # Raises Versionomy::Errors::UnknownFormatError if a format was
+      # specified by name but the name is not known.
+      # 
+      # Raises Versionomy::Errors::UnknownConversionError if the formats
+      # were recognized but no conversion was found to handle them.
+      
+      def get(from_schema_, to_schema_, strict_=false)
+        key_ = _get_key(from_schema_, to_schema_)
+        conversion_ = @registry[key_]
+        if strict_ && conversion_.nil?
+          raise Errors::UnknownConversionError
+        end
+        conversion_
+      end
+      
+      
+      # Register the given conversion as the handler for the given schemas.
+      # 
+      # The schemas may be specified as format names, Format objects,
+      # schema wrapper objects, or the root field of the schema.
+      # 
+      # Raises Versionomy::Errors::ConversionRedefinedError if a conversion
+      # has already been registered for the given schemas.
+      # 
+      # Raises Versionomy::Errors::UnknownFormatError if a format was
+      # specified by name but the name is not known.
+      
+      def register(from_schema_, to_schema_, conversion_)
+        key_ = _get_key(from_schema_, to_schema_)
+        if @registry.include?(key_)
+          raise Errors::ConversionRedefinedError
+        end
+        @registry[key_] = conversion_
+      end
+      
+      
+      private
+      
+      def _get_key(from_schema_, to_schema_)  # :nodoc:
+        [_get_schema(from_schema_), _get_schema(to_schema_)]
+      end
+      
+      def _get_schema(schema_)  # :nodoc:
+        schema_ = Format.get(schema_, true) if schema_.kind_of?(::String) || schema_.kind_of?(::Symbol)
+        schema_ = schema_.schema if schema_.respond_to?(:schema)
+        schema_ = schema_.root_field if schema_.respond_to?(:root_field)
+        schema_
+      end
+      
+      
+    end
+    
+  end
+  
+  
+end

data/lib/versionomy/errors.rb

@@ -109,7 +109,7 @@ module Versionomy
     
     
     # This exception is raised during schema creation if you try to
-    # create a circular dependency.
+    # create a circular graph.
     
     class CircularDescendantError < SchemaCreationError
     end
@@ -128,13 +128,33 @@ module Versionomy
     end
     
     
-    # Raised by the Formats registry if you try to retrieve a format with
+    # Raised by the Format registry if you try to retrieve a format with
     # an unrecognized name in strict mode.
     
     class UnknownFormatError < VersionomyError
     end
     
     
+    # Raised when a conversion fails.
+    
+    class ConversionError < VersionomyError
+    end
+    
+    
+    # Raised when a conversion fails because no conversion implementation
+    # was found.
+    
+    class UnknownConversionError < ConversionError
+    end
+    
+    
+    # Raised when you try to register a conversion when one already
+    # exists for its schemas.
+    
+    class ConversionRedefinedError < VersionomyError
+    end
+    
+    
   end
   
 end

data/lib/versionomy/format/base.rb

@@ -44,10 +44,14 @@ module Versionomy
     # 
     # This format doesn't actually do anything useful. It causes all strings
     # to parse to the schema's default value, and unparses all values to the
-    # empty string.
+    # empty string. Instead, the purpose here is to define the API for a
+    # format.
+    # 
+    # All formats must define the methods +schema+, +parse+, and +unparse+.
+    # It is also recommended that formats define the <tt>===</tt> method,
+    # though this is not strictly required. Finally, formats may optionally
+    # implement <tt>uparse_for_serialize</tt>.
     # 
-    # Instead, the purpose here is to define the API for a format. All
-    # formats must define the methods +schema+, +parse+, and +unparse+.
     # Formats need not extend this base class, as long as they duck-type
     # these methods.
     
@@ -57,14 +61,23 @@ module Versionomy
       # Create an instance of this base format, with the given schema.
       
       def initialize(schema_)
-        @schema = schema_
+        @_schema = schema_
+      end
+      
+      
+      def inspect   # :nodoc:
+        "#<#{self.class}:0x#{object_id.to_s(16)} schema=#{@_schema.inspect}>"
+      end
+      
+      def to_s   # :nodoc:
+        inspect
       end
       
       
       # Returns the schema understood by this format.
       
       def schema
-        @schema
+        @_schema
       end
       
       
@@ -90,6 +103,41 @@ module Versionomy
       end
       
       
+      # An optional method that does unparsing especially for serialization.
+      # Implement this if normal unparsing is "lossy" and doesn't guarantee
+      # reconstruction of the version number. This method should attempt to
+      # unparse in such a way that the entire version value can be
+      # reconstructed from the unparsed string. Serialization routines will
+      # first attempt to call this method to unparse for serialization. If
+      # this method is not present, the normal unparse method will be used.
+      # 
+      # Return either the unparsed string, or an array consisting of the
+      # unparsed string and a hash of parse params to pass to the parser
+      # when the string is to be reconstructed. You may also either return
+      # nil or raise Versionomy::Errors::UnparseError if the unparsing
+      # cannot be done satisfactorily for serialization. In this case,
+      # serialization will be done using the raw value data rather than an
+      # unparsed string.
+      # 
+      # This default implementation just turns around and calls unparse.
+      # Thus it is equivalent to the method not being present at all.
+      
+      def unparse_for_serialization(value_)
+        unparse(value_)
+      end
+      
+      
+      # Determine whether the given value uses this format.
+      
+      def ===(obj_)
+        if obj_.kind_of?(Value)
+          obj_.format == self
+        else
+          obj_ == self
+        end
+      end
+      
+      
     end
     
     

data/lib/versionomy/format/delimiter.rb

@@ -70,9 +70,9 @@ module Versionomy
     # the parse and unparse methods for details.
     # 
     # For a usage example, see the definition of the standard format in
-    # Versionomy::Formats#_create_standard.
+    # Versionomy::Format::Standard#create.
     
-    class Delimiter
+    class Delimiter < Base
       
       
       # Create a format using delimiter tools.
@@ -128,11 +128,11 @@ module Versionomy
       # 
       # <tt>:extra_characters</tt>::
       #   Determines what to do if the entire string cannot be consumed by
-      #   the parsing process. If set to <tt>:ignore</tt> (the default),
-      #   any extra characters are ignored. If set to <tt>:suffix</tt>,
-      #   the extra characters are set as the <tt>:suffix</tt> unparse
-      #   parameter and are thus appended to the end of the string when
-      #   unparsing takes place. If set to <tt>:error</tt>, causes a
+      #   the parsing process. If set to <tt>:ignore</tt>, any extra
+      #   characters are ignored. If set to <tt>:suffix</tt>, the extra
+      #   characters are set as the <tt>:suffix</tt> unparse parameter and
+      #   are thus appended to the end of the string when unparsing takes
+      #   place. If set to <tt>:error</tt> (the default), causes a
       #   Versionomy::Errors::ParseError to be raised if there are
       #   uninterpreted characters.
       
@@ -152,10 +152,12 @@ module Versionomy
         end
         if parse_params_[:string].length > 0
           case parse_params_[:extra_characters]
-          when :error
-            raise Errors::ParseError, "Extra characters: #{parse_params_[:string].inspect}"
+          when :ignore
+            # do nothing
           when :suffix
             unparse_params_[:suffix] = parse_params_[:string]
+          else
+            raise Errors::ParseError, "Extra characters: #{parse_params_[:string].inspect}"
           end
         end
         Value.new(values_, self, unparse_params_)
@@ -412,7 +414,7 @@ module Versionomy
         # 
         # The standard format uses styles to preserve the different
         # syntaxes for the release_type field. See the source code in
-        # Versionomy::Formats#_create_standard for this example.
+        # Versionomy::Format::Standard#create for this example.
         
         def field(name_, opts_={}, &block_)
           name_ = name_.to_sym
@@ -689,15 +691,17 @@ module Versionomy
           @style = opts_[:style]
           @default_value_optional = opts_[:default_value_optional]
           @regexp_options = opts_[:case_sensitive] ? nil : ::Regexp::IGNORECASE
-          @value_regexp = ::Regexp.new("^(#{value_regexp_})", @regexp_options)
-          regexp_ = opts_.fetch(:delimiter_regexp, '\.')
-          @delimiter_regexp = regexp_.length > 0 ? ::Regexp.new("^(#{regexp_})", @regexp_options) : nil
-          regexp_ = opts_.fetch(:post_delimiter_regexp, '')
-          @post_delimiter_regexp = regexp_.length > 0 ? ::Regexp.new("^(#{regexp_})", @regexp_options) : nil
-          regexp_ = opts_.fetch(:expected_follower_regexp, '')
-          @follower_regexp = regexp_.length > 0 ? ::Regexp.new("^(#{regexp_})", @regexp_options) : nil
-          @default_delimiter = opts_.fetch(:default_delimiter, '.')
-          @default_post_delimiter = opts_.fetch(:default_post_delimiter, '')
+          @value_regexp = ::Regexp.new("\\A(#{value_regexp_})", @regexp_options)
+          regexp_ = opts_[:delimiter_regexp] || '\.'
+          @delimiter_regexp = regexp_.length > 0 ? ::Regexp.new("\\A(#{regexp_})", @regexp_options) : nil
+          @full_delimiter_regexp = regexp_.length > 0 ? ::Regexp.new("\\A(#{regexp_})\\z", @regexp_options) : nil
+          regexp_ = opts_[:post_delimiter_regexp] || ''
+          @post_delimiter_regexp = regexp_.length > 0 ? ::Regexp.new("\\A(#{regexp_})", @regexp_options) : nil
+          @full_post_delimiter_regexp = regexp_.length > 0 ? ::Regexp.new("\\A(#{regexp_})\\z", @regexp_options) : nil
+          regexp_ = opts_[:expected_follower_regexp] || ''
+          @follower_regexp = regexp_.length > 0 ? ::Regexp.new("\\A(#{regexp_})", @regexp_options) : nil
+          @default_delimiter = opts_[:default_delimiter] || '.'
+          @default_post_delimiter = opts_[:default_post_delimiter] || ''
           @requires_previous_field = opts_.fetch(:requires_previous_field, true)
           name_ = field_.name
           @default_field_value = field_.default_value
@@ -777,13 +781,21 @@ module Versionomy
           then
             str_ = unparsed_value(value_, style_, unparse_params_)
             if str_
-              delim_ = unparse_params_[@delim_unparse_param_key]
-              if !delim_ || @delimiter_regexp && @delimiter_regexp !~ delim_
-                delim_ = @default_delimiter
+              if !@full_delimiter_regexp
+                delim_ = ''
+              else
+                delim_ = unparse_params_[@delim_unparse_param_key] || @default_delimiter
+                if @full_delimiter_regexp !~ delim_
+                  delim_ = @default_delimiter
+                end
               end
-              post_delim_ = unparse_params_[@post_delim_unparse_param_key]
-              if !post_delim_ || @post_delimiter_regexp && @post_delimiter_regexp !~ post_delim_
-                post_delim_ = @default_post_delimiter
+              if !@full_post_delimiter_regexp
+                post_delim_ = ''
+              else
+                post_delim_ = unparse_params_[@post_delim_unparse_param_key] || @default_post_delimiter
+                if @full_post_delimiter_regexp !~ post_delim_
+                  post_delim_ = @default_post_delimiter
+                end
               end
               str_ = delim_ + str_ + post_delim_
             end
@@ -876,7 +888,7 @@ module Versionomy
         end
         
         def unparsed_value(value_, style_, unparse_params_)
-          value_
+          value_.to_s
         end
         
       end
@@ -921,7 +933,7 @@ module Versionomy
           regexps_ = @mappings_in_order.map{ |map_| "(#{map_[0]})" }
           setup(field_, regexps_.join('|'), opts_)
           @mappings_in_order.each do |map_|
-            map_[0] = ::Regexp.new("^(#{map_[0]})", @regexp_options)
+            map_[0] = ::Regexp.new("\\A(#{map_[0]})", @regexp_options)
           end
         end
         

data/lib/versionomy/format/rubygems.rb

@@ -0,0 +1,234 @@
+# -----------------------------------------------------------------------------
+# 
+# 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 Format
+    
+    
+    # Get the rubygems format.
+    # This is identical to calling <tt>get('rubygems')</tt>.
+    # 
+    # The rubygems format is designed to be parse-compatible with the
+    # Gem::Version class used in rubygems. The only caveat is, whereas
+    # Gem::Version handles an arbitrary number of fields, this format is
+    # limited to a maximum of 8.
+    # 
+    # For the exact annotated definition of the rubygems schema and format,
+    # see the source code for Versionomy::Format::Rubygems#create.
+    
+    def self.rubygems
+      get('rubygems')
+    end
+    
+    
+    # This is a namespace for the implementation of the Rubygems schema
+    # and format.
+    
+    module Rubygems
+      
+      
+      # Extra methods added to version values that use the rubygems schema.
+      
+      module ExtraMethods
+        
+        
+        # Returns true if the version is a prerelease version-- that is,
+        # if any of the fields is non-numeric.
+        # 
+        # This behaves the same as the Gem::Version#prerelease? method
+        # in rubygems.
+        
+        def prerelease?
+          values_array.any?{ |val_| val_.kind_of?(::String) }
+        end
+        
+        
+        # Returns the release for this version.
+        # For example, converts "1.2.0.a.1" to "1.2.0".
+        # Non-prerelease versions return themselves.
+        # 
+        # This behaves the same as the Gem::Version#release method
+        # in rubygems.
+        
+        def release
+          values_ = []
+          self.each_field_object do |field_, val_|
+            break unless val_.kind_of?(::Integer)
+            values_ << val_
+          end
+          Value.new(values_, self.format, self.unparse_params)
+        end
+        
+        
+        # Returns a list of the field values, in field order, with
+        # trailing zeroes stripped off.
+        # 
+        # This behaves the same as the Gem::Version#parts method
+        # in rubygems.
+        
+        def parts
+          unless @parts
+            @parts = values_array
+            @parts.pop while @parts.size > 1 && @parts.last == 0
+          end
+          @parts
+        end
+        
+        
+      end
+      
+      
+      # Create the 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 schema and format
+      # definition DSLs.
+      
+      def self.create
+        
+        # The following is the definition of the rubygems schema
+        schema_ = Schema.create do
+          
+          # Global comparison function
+          to_compare_type(:string) do |a_, b_|
+            if a_.kind_of?(::Integer)
+              if b_.kind_of?(::Integer)
+                a_ - b_
+              else
+                1
+              end
+            else
+              if b_.kind_of?(::Integer)
+                -1
+              else
+                a_ <=> b_
+              end
+            end
+          end
+          
+          # Global canonicalization function
+          to_canonicalize_type(:string) do |val_|
+            if val_.kind_of?(::Integer)
+              val_
+            else
+              val_ = val_.to_s
+              if val_ =~ /\A\d*\z/
+                val_.to_i
+              else
+                val_
+              end
+            end
+          end
+          
+          # The first field has the default value of 1. All other fields
+          # have a default value of 0. Thus, the default version number
+          # overall is "1.0".
+          field(:field0, :type => :integer, :default_value => 1) do
+            field(:field1, :type => :string) do
+              field(:field2, :type => :string) do
+                field(:field3, :type => :string) do
+                  field(:field4, :type => :string) do
+                    field(:field5, :type => :string) do
+                      field(:field6, :type => :string) do
+                        field(:field7, :type => :string)
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+          
+          # Add the methods in this module to each value
+          add_module(Format::Rubygems::ExtraMethods)
+        end
+        
+        # The following is the definition of the standard format. It
+        # understands the standard schema defined above.
+        format_ = Format::Delimiter.new(schema_) do
+          
+          # All version number strings must start with the major version.
+          # Unlike other fields, it is not preceded by any delimiter.
+          field(:field0) do
+            recognize_number(:delimiter_regexp => '', :default_delimiter => '')
+          end
+          
+          # The remainder of the version number are represented as strings
+          # or integers delimited by periods by default. Each is also
+          # dependent on the presence of the previous field, so
+          # :requires_previous_field retains its default value of true.
+          # Finally, they can be optional in an unparsed string if they are
+          # set to the default value of 0.
+          field(:field1) do
+            recognize_regexp('[0-9a-zA-Z]+', :default_value_optional => true)
+          end
+          field(:field2) do
+            recognize_regexp('[0-9a-zA-Z]+', :default_value_optional => true)
+          end
+          field(:field3) do
+            recognize_regexp('[0-9a-zA-Z]+', :default_value_optional => true)
+          end
+          field(:field4) do
+            recognize_regexp('[0-9a-zA-Z]+', :default_value_optional => true)
+          end
+          field(:field5) do
+            recognize_regexp('[0-9a-zA-Z]+', :default_value_optional => true)
+          end
+          field(:field6) do
+            recognize_regexp('[0-9a-zA-Z]+', :default_value_optional => true)
+          end
+          field(:field7) do
+            recognize_regexp('[0-9a-zA-Z]+', :default_value_optional => true)
+          end
+          
+          # By default, we require that at least the first two fields
+          # appear in an unparsed version string.
+          default_unparse_params(:required_fields => [:field1])
+        end
+      end
+      
+      
+    end
+    
+    
+    register('rubygems', Format::Rubygems.create) unless get('rubygems')
+    
+    
+  end
+  
+end