versionomy 0.2.5 → 0.3.0

data/lib/versionomy/format.rb

@@ -34,6 +34,10 @@
 ;
 
 
+require 'thread'
+require 'monitor'
+
+
 module Versionomy
   
   
@@ -57,28 +61,96 @@ module Versionomy
   # Versionomy::Format::Delimiter tool, which can be used to construct
   # parsers for many version number formats.
   # 
+  # === Format registry
+  # 
   # Formats may be registered with Versionomy and given a name using the
   # methods of this module. This allows version numbers to be serialized
-  # with their format.
+  # with their format. When a version number is serialized, its format
+  # name is written to the stream, along with the version number's string
+  # representation. When the version number is reconstructed, its format
+  # is looked up by name so versionomy can determine how to parse the
+  # string.
+  # 
+  # Format names are strings that may include letters, numerals, dashes,
+  # underscores, and periods. By convention, periods are used as namespace
+  # delimiters. Format names without a namespace (that is, with no periods)
+  # are considered reserved for standard versionomy formats. If you define
+  # your own format, you should use a name that includes a namespace (e.g.
+  # "mycompany.LibraryVersion") to reduce the chance of name collisions.
   # 
-  # Finally, this module serves as a namespace for format implementations.
+  # You may register formats directly using the register method, or set it
+  # up to be autoloaded on demand. When a format is requested, if it has
+  # not been registered explicitly, Versionomy looks for a format definition
+  # file for that format. Such a file has the name of the format, with the
+  # ".rb" extension for ruby (e.g. "mycompany.LibraryVersion.rb") and must
+  # be located in a directory in versionomy's format lookup path. By
+  # default, the directory containing versionomy's predefined formats
+  # (such as "standard") is in this path. However, you may add your own
+  # directories using the add_directory method. This lets you autoload your
+  # own formats. A format definition file itself must contain ruby code
+  # that defines the format and registers it using the correct name. See
+  # the files in the "lib/versionomy/format_definitions/" directory for
+  # examples.
   
   module Format
     
-    @names_to_formats = ::Hash.new
-    @formats_to_names = ::Hash.new
+    @mutex = ::Mutex.new
+    @load_mutex = ::Monitor.new
+    @directories = [::File.expand_path(::File.dirname(__FILE__)+'/format_definitions')]
+    @names_to_formats = {}
+    @formats_to_names = {}
     
     class << self
       
       
+      # Add a directory to the format path.
+      # 
+      # The format path is an array of directory paths. These directories
+      # are searched for format definitions if a format name that has not
+      # been registered is requested.
+      # 
+      # If high_priority_ is set to true, the directory is added to the
+      # front of the lookup path; otherwise it is added to the back.
+      
+      def add_directory(path_, high_priority_=false)
+        path_ = ::File.expand_path(path_)
+        @mutex.synchronize do
+          unless @directories.include?(path_)
+            if high_priority_
+              @directories.unshift(path_)
+            else
+              @directories.push(path_)
+            end
+          end
+        end
+      end
+      
+      
       # Get the format with the given name.
       # 
-      # 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.
+      # If the given name has not been defined, attempts to autoload it from
+      # a format definition file. See the description of the Format module
+      # for details on this procedure.
+      # 
+      # If the given name still cannot be resolved, and strict is set to
+      # true, raises Versionomy::Errors::UnknownFormatError. If strict is
+      # set to false, returns nil if the given name cannot be resolved.
       
       def get(name_, strict_=false)
-        format_ = @names_to_formats[name_.to_s]
+        name_ = _check_name(name_)
+        format_ = @mutex.synchronize{ @names_to_formats[name_] }
+        if format_.nil?
+          # Attempt to find the format in the directory path
+          dirs_ = @mutex.synchronize{ @directories.dup }
+          dirs_.each do |dir_|
+            path_ = "#{dir_}/#{name_}.rb"
+            if ::File.readable?(path_)
+              @load_mutex.synchronize{ ::Kernel.load(path_) }
+            end
+            format_ = @mutex.synchronize{ @names_to_formats[name_] }
+            break unless format_.nil?
+          end
+        end
         if format_.nil? && strict_
           raise Errors::UnknownFormatError, name_
         end
@@ -86,6 +158,15 @@ module Versionomy
       end
       
       
+      # Determines whether a format with the given name has been registered
+      # explicitly. Does not attempt to autoload the format.
+      
+      def registered?(name_)
+        name_ = _check_name(name_)
+        @mutex.synchronize{ @names_to_formats.include?(name_) }
+      end
+      
+      
       # Register the given format under the given name.
       # 
       # Valid names may contain only letters, digits, underscores, dashes,
@@ -94,16 +175,18 @@ module Versionomy
       # Raises Versionomy::Errors::FormatRedefinedError if the name has
       # already been defined.
       
-      def register(name_, format_)
-        name_ = name_.to_s
-        unless name_ =~ /\A[\w.-]+\z/
-          raise ::ArgumentError, "Illegal name: #{name_.inspect}"
-        end
-        if @names_to_formats.include?(name_)
-          raise Errors::FormatRedefinedError, name_
+      def register(name_, format_, silent_=false)
+        name_ = _check_name(name_)
+        @mutex.synchronize do
+          if @names_to_formats.include?(name_)
+            unless silent_
+              raise Errors::FormatRedefinedError, name_
+            end
+          else
+            @names_to_formats[name_] = format_
+            @formats_to_names[format_.object_id] = name_
+          end
         end
-        @names_to_formats[name_] = format_
-        @formats_to_names[format_.object_id] = name_
       end
       
       
@@ -115,7 +198,7 @@ module Versionomy
       # false, returns nil if the given format was never registered.
       
       def canonical_name_for(format_, strict_=false)
-        name_ = @formats_to_names[format_.object_id]
+        name_ = @mutex.synchronize{ @formats_to_names[format_.object_id] }
         if name_.nil? && strict_
           raise Errors::UnknownFormatError
         end
@@ -123,6 +206,17 @@ module Versionomy
       end
       
       
+      private
+      
+      def _check_name(name_)  # :nodoc:
+        name_ = name_.to_s
+        unless name_ =~ /\A[\w.-]+\z/
+          raise ::ArgumentError, "Illegal name: #{name_.inspect}"
+        end
+        name_
+      end
+      
+      
     end
     
   end

data/lib/versionomy/{format → format_definitions}/rubygems.rb

@@ -128,7 +128,7 @@ module Versionomy
           to_compare_type(:string) do |a_, b_|
             if a_.kind_of?(::Integer)
               if b_.kind_of?(::Integer)
-                a_ - b_
+                a_ <=> b_
               else
                 1
               end
@@ -174,6 +174,10 @@ module Versionomy
             end
           end
           
+          # Some field aliases providing alternate names for major fields
+          alias_field(:major, :field0)
+          alias_field(:minor, :field1)
+          
           # Add the methods in this module to each value
           add_module(Format::Rubygems::ExtraMethods)
         end
@@ -226,9 +230,114 @@ module Versionomy
     end
     
     
-    register('rubygems', Format::Rubygems.create) unless get('rubygems')
+    register('rubygems', Format::Rubygems.create, true)
     
     
   end
   
+  
+  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 recognize. So instead of "1.0b2", we force the
+            # unparsing to generate "1.0.b.2".
+            params_[:release_type_delim] = '.'
+            params_[:development_version_delim] = '.'
+            params_[:alpha_version_delim] = '.'
+            params_[:beta_version_delim] = '.'
+            params_[:release_candidate_version_delim] = '.'
+            params_[:preview_version_delim] = '.'
+            
+            # 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
+            
+            # If the standard format version includes a "v" prefix, strip
+            # it because rubygems doesn't like it.
+            params_[:major_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
+      
+      
+    end
+    
+    
+    register(:standard, :rubygems, Conversion::Rubygems.create_standard_to_rubygems, true)
+    register(:rubygems, :standard, Conversion::Rubygems.create_rubygems_to_standard, true)
+    
+    
+  end
+  
+  
 end

data/lib/versionomy/{format → format_definitions}/standard.rb

@@ -390,7 +390,7 @@ module Versionomy
     end
     
     
-    register('standard', Format::Standard.create) unless get('standard')
+    register('standard', Format::Standard.create, true)
     
     
   end

data/lib/versionomy/interface.rb

@@ -158,14 +158,14 @@ module Versionomy
     # constants RUBY_VERSION and RUBY_PATCHLEVEL.
     
     def ruby_version
-      unless @ruby_version
-        @ruby_version = parse(::RUBY_VERSION, :standard)
-        if @ruby_version.release_type == :final
-          @ruby_version = @ruby_version.change({:patchlevel => ::RUBY_PATCHLEVEL},
+      @ruby_version ||= begin
+        version_ = parse(::RUBY_VERSION, :standard)
+        if version_.release_type == :final
+          version_ = version_.change({:patchlevel => ::RUBY_PATCHLEVEL},
             :patchlevel_required => true, :patchlevel_delim => '-p')
         end
+        version_
       end
-      @ruby_version
     end
     
     

data/lib/versionomy/schema/wrapper.rb

@@ -55,10 +55,11 @@ module Versionomy
         ::Blockenspiel.invoke(block_, builder_)
         field_ = builder_._get_field
         modules_ = builder_._get_modules
+        aliases_ = builder_._get_aliases
       else
         modules_ = opts_[:modules] || []
       end
-      Schema::Wrapper.new(field_, modules_)
+      Schema::Wrapper.new(field_, modules_, aliases_)
     end
     
     
@@ -71,10 +72,18 @@ module Versionomy
       # This is a low-level method. Usually you should call
       # Versionomy::Schema#create instead.
       
-      def initialize(field_, modules_=[])
+      def initialize(field_, modules_=[], aliases_={})
         @root_field = field_
         @names = @root_field._descendants_by_name
         @modules = modules_
+        @aliases = {}
+        aliases_.each do |k_,v_|
+          k_ = k_.to_sym
+          v_ = v_.to_sym
+          if @names.include?(v_) && !@names.include?(k_)
+            @aliases[k_] = v_
+          end
+        end
       end
       
       
@@ -95,7 +104,7 @@ module Versionomy
       
       def eql?(obj_)
         return false unless obj_.kind_of?(Schema::Wrapper)
-        return @root_field == obj_.root_field && @modules == obj_.modules
+        return @root_field == obj_.root_field && @modules == obj_.modules && @aliases == obj_.aliases
       end
       
       
@@ -134,16 +143,29 @@ module Versionomy
       end
       
       
+      # Return the canonical field name given a name, or nil if the name
+      # is not recognized.
+      
+      def canonical_name(name_)
+        name_ = name_.to_sym
+        name_ = @aliases[name_] || name_
+        @names.include?(name_) ? name_ : nil
+      end
+      
+      
       # Return the field with the given name, or nil if the given name
-      # is not found in this schema.
+      # is not found in this schema. If include_aliases_ is set to true,
+      # this also supports lookup by alias.
       
-      def field_named(name_)
-        @names[name_.to_sym]
+      def field_named(name_, include_aliases_=false)
+        name_ = name_.to_sym
+        name_ = @aliases[name_] || name_ if include_aliases_
+        field_ = @names[name_]
       end
       
       
       # Returns an array of names present in this schema, in no particular
-      # order.
+      # order. Does not include aliases.
       
       def names
         @names.keys
@@ -158,6 +180,13 @@ module Versionomy
       end
       
       
+      # Returns a hash of field name aliases.
+      
+      def aliases
+        @aliases.dup
+      end
+      
+      
     end
     
     
@@ -171,6 +200,7 @@ module Versionomy
       def initialize()  # :nodoc:
         @field = nil
         @modules = []
+        @aliases = {}
         @defaults = { :integer => {}, :string => {}, :symbol => {} }
       end
       
@@ -204,28 +234,64 @@ module Versionomy
       end
       
       
-      # Add a module to values that use this schema.
+      # Create a field alias.
+      
+      def alias_field(alias_name_, field_name_)
+        @aliases[alias_name_.to_sym] = field_name_.to_sym
+      end
+      
+      
+      # Add a module to the schema. All values that use this schema will
+      # include this module. This provides a way to add schema-specific
+      # capabilities to version numbers.
       
       def add_module(mod_)
         @modules << mod_
       end
       
       
+      # Provide a default bump procedure for the given type.
+      # The type should be <tt>:integer</tt>, <tt>:string</tt>, or
+      # <tt>:symbol</tt>. You must provide a block that takes a field value
+      # and returns the "bumped" value. This procedure will be used for
+      # all fields of this type, unless explicitly overridden by the field.
+      
       def to_bump_type(type_, &block_)
         @defaults[type_][:bump] = block_
       end
       
       
+      # Provide a default compare procedure for the given type.
+      # The type should be <tt>:integer</tt>, <tt>:string</tt>, or
+      # <tt>:symbol</tt>. You must provide a block that takes two values
+      # and returns a standard comparison result-- that is, a negative
+      # integer if the first value is less, 0 if the values are equal, or a
+      # positive integer if the first value is greater. This procedure will
+      # be used for all fields of this type, unless explicitly overridden
+      # by the field.
+      
       def to_compare_type(type_, &block_)
         @defaults[type_][:compare] = block_
       end
       
       
+      # Provide a default canonicalization procedure for the given type.
+      # The type should be <tt>:integer</tt>, <tt>:string</tt>, or
+      # <tt>:symbol</tt>. You must provide a block that takes a field value
+      # and returns the canonical value. This procedure will be used for
+      # all fields of this type, unless explicitly overridden by the field.
+      
       def to_canonicalize_type(type_, &block_)
         @defaults[type_][:canonicalize] = block_
       end
       
       
+      # Provide a default value for the given type.
+      # The type should be <tt>:integer</tt>, <tt>:string</tt>, or
+      # <tt>:symbol</tt>. You must provide a default value that will be
+      # used for all fields of this type, unless explicitly overridden by
+      # the field.
+      
       def default_value_for_type(type_, value_)
         @defaults[type_][:value] = value_
       end
@@ -239,6 +305,10 @@ module Versionomy
         @modules
       end
       
+      def _get_aliases  # :nodoc:
+        @aliases
+      end
+      
       def _get_default_setting(type_, setting_)  # :nodoc:
         @defaults[type_][setting_]
       end