versionomy 0.1.3 → 0.2.0

data/lib/versionomy/schema/wrapper.rb

@@ -46,7 +46,7 @@ module Versionomy
     # fields. If you provide a block, you must use the methods in
     # Versionomy::Schema::Builder in the block to create the root field.
     
-    def self.create(field_=nil, &block_)
+    def self.create(field_=nil, opts_={}, &block_)
       if field_ && block_
         raise ::ArgumentError, 'You may provide either a root field or block but not both'
       end
@@ -54,8 +54,11 @@ module Versionomy
         builder_ = Schema::Builder.new
         ::Blockenspiel.invoke(block_, builder_)
         field_ = builder_._get_field
+        modules_ = builder_._get_modules
+      else
+        modules_ = opts_[:modules] || []
       end
-      Schema::Wrapper.new(field_)
+      Schema::Wrapper.new(field_, modules_)
     end
     
     
@@ -68,33 +71,59 @@ module Versionomy
       # This is a low-level method. Usually you should call
       # Versionomy::Schema#create instead.
       
-      def initialize(field_)
+      def initialize(field_, modules_=[])
         @root_field = field_
         @names = @root_field._descendants_by_name
+        @modules = modules_
+      end
+      
+      
+      def inspect   # :nodoc:
+        "#<#{self.class}:0x#{object_id.to_s(16)} root=#{@root_field.inspect}>"
+      end
+      
+      def to_s   # :nodoc:
+        inspect
       end
       
       
       # Returns true if this schema is equivalent to the other schema.
       # Two schemas are equivalent if their root fields are the same--
-      # which means that the entire field tree is the same.
+      # which means that the entire field tree is the same-- and they
+      # include the same value modules.
+      # Note that this is different from the definition of <tt>==</tt>.
       
       def eql?(obj_)
         return false unless obj_.kind_of?(Schema::Wrapper)
-        return @root_field == obj_.root_field
+        return @root_field == obj_.root_field && @modules == obj_.modules
       end
       
       
-      # Returns true if this schema is equivalent to the other schema.
-      # Two schemas are equivalent if their root fields are the same--
-      # which means that the entire field tree is the same.
+      # Returns true if this schema is compatible with the other schema.
+      # Two schemas are compatible if their root fields are the same--
+      # which means that the entire field tree is the same. They may,
+      # however, include different value modules.
+      # Note that this is different from the definition of <tt>eql?</tt>.
       
       def ==(obj_)
         eql?(obj_)
       end
       
       
+      # If the RHS is a schema, returns true if the schemas are equivalent.
+      # If the RHS is a value, returns true if the value uses this schema.
+      
+      def ===(obj_)
+        if obj_.kind_of?(Value)
+          obj_.schema == self
+        else
+          obj_ == self
+        end
+      end
+      
+      
       def hash  # :nodoc:
-        @hash ||= @root_field.hash
+        @hash ||= @root_field.hash ^ @modules.hash
       end
       
       
@@ -121,6 +150,14 @@ module Versionomy
       end
       
       
+      # Returns an array of modules that should be included in values that
+      # use this schema.
+      
+      def modules
+        @modules.dup
+      end
+      
+      
     end
     
     
@@ -133,6 +170,8 @@ module Versionomy
       
       def initialize()  # :nodoc:
         @field = nil
+        @modules = []
+        @defaults = { :integer => {}, :string => {}, :symbol => {} }
       end
       
       
@@ -161,7 +200,34 @@ module Versionomy
         if @field
           raise Errors::RangeOverlapError, "Root field already defined"
         end
-        @field = Schema::Field.new(name_, opts_, &block_)
+        @field = Schema::Field.new(name_, opts_.merge(:master_builder => self), &block_)
+      end
+      
+      
+      # Add a module to values that use this schema.
+      
+      def add_module(mod_)
+        @modules << mod_
+      end
+      
+      
+      def to_bump_type(type_, &block_)
+        @defaults[type_][:bump] = block_
+      end
+      
+      
+      def to_compare_type(type_, &block_)
+        @defaults[type_][:compare] = block_
+      end
+      
+      
+      def to_canonicalize_type(type_, &block_)
+        @defaults[type_][:canonicalize] = block_
+      end
+      
+      
+      def default_value_for_type(type_, value_)
+        @defaults[type_][:value] = value_
       end
       
       
@@ -169,6 +235,14 @@ module Versionomy
         @field
       end
       
+      def _get_modules  # :nodoc:
+        @modules
+      end
+      
+      def _get_default_setting(type_, setting_)  # :nodoc:
+        @defaults[type_][setting_]
+      end
+      
     end
     
     

data/lib/versionomy/schema.rb

@@ -43,17 +43,20 @@ module Versionomy
   # The schema controls what fields are present in the version, how
   # version numbers are compared, what the default values are, and how
   # values can change. Version numbers with the same schema can be
-  # compared with one another, and version numbers can be converted to
-  # formats that share the same schema.
+  # compared with one another, and version numbers can be converted
+  # trivially to formats that share the same schema, without requiring a
+  # Conversion implementation.
   # 
   # At its simplest, a version number is defined as a sequence of fields,
   # each with a name and data type. These fields may be integer-valued,
   # string-valued, or symbolic, though most will probably be integers.
-  # Symbolic fields are useful, for example, if you want a field to specify
-  # the type of prerelease (e.g. "alpha", "beta", or "release candidate").
+  # Symbolic fields are enumerated types that are useful, for example, if
+  # you want a field to specify the type of prerelease (e.g. "alpha",
+  # "beta", or "release candidate").
   # 
-  # As a simple example, you could construct a schema for versions numbers
-  # of the form "major.minor.tiny" like this:
+  # As a simple conceptual example, you could construct a schema for
+  # version numbers of the form "major.minor.tiny" like this. (This is a
+  # conceptual diagram, not actual syntax.)
   # 
   #  ("major": integer), ("minor": integer), ("tiny": integer)
   # 

data/lib/versionomy/value.rb

@@ -34,6 +34,9 @@
 ;
 
 
+require 'yaml'
+
+
 module Versionomy
   
   
@@ -64,18 +67,21 @@ module Versionomy
       unless values_.kind_of?(::Hash) || values_.kind_of?(::Array)
         raise ::ArgumentError, "Expected hash or array but got #{values_.class}"
       end
-      @format = format_
-      @unparse_params = unparse_params_
-      @field_path = []
-      @values = {}
-      field_ = @format.schema.root_field
+      @_format = format_
+      @_unparse_params = unparse_params_
+      @_field_path = []
+      @_values = {}
+      schema_ = @_format.schema
+      field_ = schema_.root_field
       while field_
-        value_ = values_.kind_of?(Hash) ? values_[field_.name] : values_.shift
+        value_ = values_.kind_of?(::Hash) ? values_[field_.name] : values_.shift
         value_ = value_ ? field_.canonicalize_value(value_) : field_.default_value
-        @field_path << field_
-        @values[field_.name] = value_
+        @_field_path << field_
+        @_values[field_.name] = value_
         field_ = field_.child(value_)
       end
+      modules_ = schema_.modules
+      extend(*modules_) if modules_.size > 0
     end
     
     
@@ -90,7 +96,7 @@ module Versionomy
     
     def _inspect  # :nodoc:
       "#<#{self.class}:0x#{object_id.to_s(16)} " +
-        @field_path.map{ |field_| "#{field_.name}=#{@values[field_.name].inspect}" }.join(' ')
+        @_field_path.map{ |field_| "#{field_.name}=#{@_values[field_.name].inspect}" }.join(' ')
     end
     
     
@@ -107,26 +113,103 @@ module Versionomy
     end
     
     
-    # Unparse this version number.
+    # Marshal this version number.
+    
+    def marshal_dump  # :nodoc:
+      format_name_ = Format.canonical_name_for(@_format, true)
+      unparsed_data_ = nil
+      if @_format.respond_to?(:unparse_for_serialization)
+        unparsed_data_ = @_format.unparse_for_serialization(self) rescue nil
+      end
+      unparsed_data_ ||= @_format.unparse(self) rescue nil
+      data_ = [format_name_]
+      case unparsed_data_
+      when ::Array
+        data_ << unparsed_data_[0]
+        data_ << unparsed_data_[1] if unparsed_data_[1]
+      when ::String
+        data_ << unparsed_data_
+      else
+        data_ << values_array
+        data_ << @_unparse_params if @_unparse_params
+      end
+      data_
+    end
+    
+    
+    # Unmarshal this version number.
+    
+    def marshal_load(data_)  # :nodoc:
+      format_ = Format.get(data_[0], true)
+      if data_[1].kind_of?(::String)
+        val_ = format_.parse(data_[1], data_[2])
+        initialize(val_.values_array, format_, val_.unparse_params)
+      else
+        initialize(data_[1], format_, data_[2])
+      end
+    end
+    
+    
+    yaml_as "tag:danielazuma.com,2009:version"
+    
+    
+    # Deserialize a version number from YAML
+    
+    def self.yaml_new(klass_, tag_, data_)  # :nodoc:
+      unless data_.kind_of?(::Hash)
+        raise ::YAML::TypeError, "Invalid version format: #{val_.inspect}"
+      end
+      format_ = Format.get(data_['format'], true)
+      value_ = data_['value']
+      if value_
+        format_.parse(value_, data_['parse_params'])
+      else
+        Value.new(format_, data_['fields'], data_['unparse_params'])
+      end
+    end
+    
+    
+    # Serialize this version number to YAML format.
+    
+    def to_yaml(opts_={})
+      data_ = marshal_dump
+      ::YAML::quick_emit(nil, opts_) do |out_|
+        out_.map(taguri, to_yaml_style) do |map_|
+          map_.add('format', data_[0])
+          if data_[1].kind_of?(::String)
+            map_.add('value', data_[1])
+            map_.add('parse_params', data_[2]) if data_[2]
+          else
+            map_.add('fields', data_[1])
+            map_.add('unparse_params', data_[2]) if data_[2]
+          end
+        end
+      end
+    end
+    
+    
+    # Unparse this version number and return a string.
     # 
     # Raises Versionomy::Errors::UnparseError if unparsing failed.
     
     def unparse(params_=nil)
-      @format.unparse(self, params_)
+      @_format.unparse(self, params_)
     end
     
     
-    # Return the schema defining the form of this version number
+    # Return the schema defining the structure and semantics of this
+    # version number.
     
     def schema
-      @format.schema
+      @_format.schema
     end
     
     
-    # Return the format defining the form of this version number
+    # Return the format defining the schema and formatting/parsing of
+    # this version number.
     
     def format
-      @format
+      @_format
     end
     
     
@@ -134,15 +217,15 @@ module Versionomy
     # Returns nil if this value was not created using a parser.
     
     def unparse_params
-      @unparse_params ? @unparse_params.dup : nil
+      @_unparse_params ? @_unparse_params.dup : nil
     end
     
     
     # Iterates over each field, in field order, yielding the field name and value.
     
     def each_field
-      @field_path.each do |field_|
-        yield(field_, @values[field_.name])
+      @_field_path.each do |field_|
+        yield(field_, @_values[field_.name])
       end
     end
     
@@ -151,16 +234,18 @@ module Versionomy
     # Versionomy::Schema::Field object and value.
     
     def each_field_object  # :nodoc:
-      @field_path.each do |field_|
-        yield(field_, @values[field_.name])
+      @_field_path.each do |field_|
+        yield(field_, @_values[field_.name])
       end
     end
     
     
     # Returns an array of recognized field names for this value, in field order.
+    # This is the order of the fields actually present in this value, in
+    # order from most to least significant.
     
     def field_names
-      @field_path.map{ |field_| field_.name }
+      @_field_path.map{ |field_| field_.name }
     end
     
     
@@ -170,11 +255,11 @@ module Versionomy
     def has_field?(field_)
       case field_
       when Schema::Field
-        @field_path.include?(field_)
+        @_field_path.include?(field_)
       when ::Integer
-        @field_path.size > field_ && field_ >= 0
+        @_field_path.size > field_ && field_ >= 0
       when ::String, ::Symbol
-        @values.has_key?(field_.to_sym)
+        @_values.has_key?(field_.to_sym)
       else
         raise ::ArgumentError
       end
@@ -186,45 +271,47 @@ module Versionomy
     # or field index.
     
     def [](field_)
-      field_ = @field_path[field_] if field_.kind_of?(::Integer)
+      field_ = @_field_path[field_] if field_.kind_of?(::Integer)
       field_ = field_.name if field_.kind_of?(Schema::Field)
-      field_ ? @values[field_.to_sym] : nil
+      field_ ? @_values[field_.to_sym] : nil
     end
     
     
     # Returns the value as an array of field values, in field order.
+    # This is the order of the fields actually present in this value, in
+    # order from most to least significant.
     
     def values_array
-      @field_path.map{ |field_| @values[field_.name] }
+      @_field_path.map{ |field_| @_values[field_.name] }
     end
     
     
     # Returns the value as a hash of values keyed by field name.
     
     def values_hash
-      @values.dup
+      @_values.dup
     end
     
     
     # Returns a new version number created by bumping the given field. The
     # field may be specified as a field object, field name, or field index.
-    # Returns self if value could not be changed.
-    # Returns nil if the field was not recognized.
+    # Returns self unchanged if the field was not recognized or could not
+    # be modified.
     
     def bump(name_)
-      name_ = @field_path[name_] if name_.kind_of?(::Integer)
+      name_ = @_field_path[name_] if name_.kind_of?(::Integer)
       name_ = name_.name if name_.kind_of?(Schema::Field)
-      return nil unless name_
+      return self unless name_
       name_ = name_.to_sym
-      return nil unless @values.include?(name_)
+      return self unless @_values.include?(name_)
       values_ = []
-      @field_path.each do |field_|
-        oldval_ = @values[field_.name]
+      @_field_path.each do |field_|
+        oldval_ = @_values[field_.name]
         if field_.name == name_
           newval_ = field_.bump_value(oldval_)
           return self if newval_ == oldval_
           values_ << newval_
-          return Value.new(values_, @format, @unparse_params)
+          return Value.new(values_, @_format, @_unparse_params)
         else
           values_ << oldval_
         end
@@ -233,63 +320,109 @@ module Versionomy
     end
     
     
-    # Returns a new version number created by changing the given field values.
+    # Returns a new version number created by cloning this version number
+    # and changing the given field values.
+    # 
+    # You should pass in a hash of field names to values. These are the
+    # fields to modify; any other fields will be left alone, unless they
+    # are implicitly changed by the modifications you are making.
+    # For example, changing the :release_type on a value using the standard
+    # format, may change which fields are present in the resulting value.
+    # 
+    # You may also pass a delta hash to modify the unparse params stored in
+    # the value.
     
     def change(values_={}, unparse_params_={})
-      unparse_params_ = @unparse_params.merge(unparse_params_) if @unparse_params
-      Value.new(@values.merge(values_), @format, unparse_params_)
+      unparse_params_ = @_unparse_params.merge(unparse_params_) if @_unparse_params
+      Value.new(@_values.merge(values_), @_format, unparse_params_)
+    end
+    
+    
+    # Attempts to convert this value to the given format, and returns the
+    # resulting value.
+    # 
+    # Raises Versionomy::Errors::ConversionError if the value could not
+    # be converted.
+    
+    def convert(format_, convert_params_=nil)
+      if format_.kind_of?(::String) || format_.kind_of?(::Symbol)
+        format_ = Format.get(format_)
+      end
+      return self if @_format == format_
+      from_schema_ = @_format.schema
+      to_schema_ = format_.schema
+      if from_schema_ == to_schema_
+        return Value.new(@_values, format_, convert_params_)
+      end
+      conversion_ = Conversion.get(from_schema_, to_schema_, true)
+      conversion_.convert_value(self, format_, convert_params_)
     end
     
     
     def hash  # :nodoc:
-      @hash ||= @values.hash
+      @_hash ||= @_values.hash
     end
     
     
-    # Returns true if this version number is equal to the given verison number.
-    # Equality means the schemas and values are the same.
+    # Returns true if this version number is equivalent to the given number.
+    # This type of equality means their schemas are compatible and their
+    # field values are equal.
+    # Note that this is different from the definition of <tt>==</tt>.
     
     def eql?(obj_)
       if obj_.kind_of?(::String)
-        obj_ = @format.parse(obj_) rescue nil
+        obj_ = @_format.parse(obj_) rescue nil
       end
       return false unless obj_.kind_of?(Value)
       index_ = 0
       obj_.each_field_object do |field_, value_|
-        return false if field_ != @field_path[index_] || value_ != @values[field_.name]
+        return false if field_ != @_field_path[index_] || value_ != @_values[field_.name]
         index_ += 1
       end
       true
     end
     
     
-    # Returns true if this version number is equal to the given verison number.
-    # Equality means the schemas and values are the same.
+    # Returns true if this version number is value-equal to the given number.
+    # This type of equality means that they are equivalent, or that it is
+    # possible to convert the RHS to the LHS's format, and that they would
+    # be equivalent after such a conversion has taken place.
+    # Note that this is different from the definition of <tt>eql?</tt>.
     
     def ==(obj_)
-      eql?(obj_)
+      (self <=> obj_) == 0
     end
     
     
-    # Compare this version number with the given version number.
+    # Compare this version number with the given version number,
+    # returning 0 if the two are value-equal, a negative number if the RHS
+    # is greater, or a positive number if the LHS is greater.
+    # The comparison may succeed even if the two have different schemas,
+    # if the RHS can be converted to the LHS's format.
     
     def <=>(obj_)
       if obj_.kind_of?(::String)
-        obj_ = @format.parse(obj_)
+        obj_ = @_format.parse(obj_)
       end
       return nil unless obj_.kind_of?(Value)
-      index_ = 0
+      if obj_.schema != @_format.schema
+        begin
+          obj_ = obj_.convert(@_format)
+        rescue
+          return nil
+        end
+      end
       obj_.each_field_object do |field_, value_|
-        return nil unless field_ == @field_path[index_]
-        val_ = field_.compare_values(@values[field_.name], value_)
+        val_ = field_.compare_values(@_values[field_.name], value_)
         return val_ if val_ != 0
-        index_ += 1
       end
       0
     end
     
     
     # Compare this version number with the given version number.
+    # The comparison may succeed even if the two have different schemas,
+    # if the RHS can be converted to the LHS's format.
     
     def <(obj_)
       val_ = (self <=> obj_)
@@ -301,6 +434,8 @@ module Versionomy
     
     
     # Compare this version number with the given version number.
+    # The comparison may succeed even if the two have different schemas,
+    # if the RHS can be converted to the LHS's format.
     
     def >(obj_)
       val_ = (self <=> obj_)
@@ -311,6 +446,9 @@ module Versionomy
     end
     
     
+    include ::Comparable
+    
+    
     # Field values may be retrieved by calling them as methods.
     
     def method_missing(symbol_)

data/lib/versionomy/version.rb

@@ -37,7 +37,7 @@
 module Versionomy
   
   # Current gem version, as a frozen string.
-  VERSION_STRING = '0.1.3'.freeze
+  VERSION_STRING = '0.2.0'.freeze
   
   # Current gem version, as a Versionomy::Value.
   VERSION = ::Versionomy.parse(VERSION_STRING, :standard)

data/lib/versionomy.rb

@@ -52,9 +52,13 @@ includes_ = [
  'format',
  'format/base',
  'format/delimiter',
- 'formats',
- 'formats/standard',
+ 'format/standard',
+ 'format/rubygems',
  'value',
+ 'conversion',
+ 'conversion/base',
+ 'conversion/parsing',
+ 'conversion/rubygems',
  'interface',
  'version',
 ]

data/tests/tc_custom_format.rb

@@ -36,24 +36,24 @@
 
 
 require 'test/unit'
-require File.expand_path("#{File.dirname(__FILE__)}/../lib/versionomy.rb")
+require ::File.expand_path("#{::File.dirname(__FILE__)}/../lib/versionomy.rb")
 
 
 module Versionomy
   module Tests  # :nodoc:
     
-    class TestCustomFormat < Test::Unit::TestCase  # :nodoc:
+    class TestCustomFormat < ::Test::Unit::TestCase  # :nodoc:
       
       
       # Test parsing with custom format for patchlevel
       
       def test_parsing_custom_patchlevel_format
-        format_ = Versionomy.default_format.modified_copy do
+        format_ = ::Versionomy.default_format.modified_copy do
           field(:patchlevel, :requires_previous_field => false) do
             recognize_number(:delimiter_regexp => '\s?sp', :default_delimiter => ' SP')
           end
         end
-        value1_ = Versionomy.parse('2008 SP2', format_)
+        value1_ = ::Versionomy.parse('2008 SP2', format_)
         assert_equal(2, value1_.patchlevel)
         value2_ = value1_.format.parse('2008 sp3')
         assert_equal(3, value2_.patchlevel)