versionomy 0.1.3 → 0.2.0

data/lib/versionomy/format/standard.rb

@@ -0,0 +1,382 @@
+# -----------------------------------------------------------------------------
+# 
+# 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 standard format.
+    # This is identical to calling <tt>get('standard')</tt>.
+    # 
+    # The standard format is designed to handle most commonly-used version
+    # number forms, and allow parsing and comparison between them.
+    # 
+    # The standard schema is the heart of this format, providing a
+    # common structure for most version numbers.
+    # 
+    # It begins with four numeric fields:
+    # "<tt>major.minor.tiny.tiny2</tt>".
+    # 
+    # The next field, <tt>:release_type</tt>, defines the remaining
+    # structure. The release type can be one of these symbolic values:
+    # <tt>:development</tt>, <tt>:alpha</tt>, <tt>:beta</tt>,
+    # <tt>:preview</tt>, <tt>:release_candidate</tt>, <tt>:release</tt>.
+    # 
+    # Depending on that value, additional fields become available. For
+    # example, the <tt>:alpha</tt> value enables the fields
+    # <tt>:alpha_version</tt> and <tt>:alpha_minor</tt>, which represent
+    # version number fields after the "a" alpha specifier. i.e. "2.1a30"
+    # has an alpha_version of 30. "2.1a30.2" also has an alpha_minor of 2.
+    # Similarly, the <tt>:beta</tt> release_type value enables the fields
+    # <tt>:beta_version</tt> and <tt>:beta_minor</tt>. A release_type
+    # of <tt>:release</tt> enables <tt>:patchlevel</tt> and
+    # <tt>:patchlevel_minor</tt>, to support versions like "1.8.7p72".
+    # 
+    # The format itself is a delimiter-based format that understands a
+    # wide variety of string representations of this version schema.
+    # Examples of supported syntax include:
+    # 
+    #  2.0
+    #  2.0.42.10
+    #  2.0b2
+    #  2.0rc15
+    #  2.0-5
+    #  2.0p5
+    #  2.0 Alpha 1
+    #  2.0a5.3
+    #  2.1.42.10-4.3
+    # 
+    # Because the standard format is based on Versionomy::Format::Delimiter,
+    # a number of parameters are available for parsing and unparsing. See
+    # the documentation for the delimiter class for more information.
+    # 
+    # Two of the fields have styles that can be set when unparsing.
+    # The <tt>:release_type</tt> field can be unparsed as either
+    # <tt>:long</tt> style (e.g. "1.0alpha2") or <tt>:short</tt> style
+    # (e.g. "1.0a2"). The patchlevel field can be unparsed as either
+    # <tt>:number</tt> style (e.g. "2.1-1") or <tt>:letter</tt> style
+    # (e.g. "2.1a"). Most fields can have their delimiter specified during
+    # unparsing as well.
+    # 
+    # For the exact annotated definition of the standard schema and format,
+    # see the source code for Versionomy::Format::Standard#create.
+    
+    def self.standard
+      get('standard')
+    end
+    
+    
+    # This is a namespace for the implementation of the Standard schema
+    # and format.
+    
+    module Standard
+      
+      
+      # Extra methods added to version values that use the standard schema.
+      
+      module ExtraMethods
+        
+        
+        # Returns true if the version is a prerelease version
+        
+        def prerelease?
+          self.release_type != :final
+        end
+        
+        
+        # Returns the release for this version.
+        # For example, converts "1.2.0a1" to "1.2.0".
+        # Non-prerelease versions return themselves.
+        
+        def release
+          self.change(:release_type => :final)
+        end
+        
+        
+      end
+      
+      
+      # Create the 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 schema and format
+      # definition DSLs.
+      
+      def self.create
+        
+        # The following is the definition of the standard schema
+        schema_ = Schema.create do
+          
+          # The major field has the default value of 1. Most other fields
+          # have a default value of 0. Thus, the default version number
+          # overall is "1.0".
+          # We first create the core version fields "major.minor.tiny.tiny2".
+          field(:major, :default_value => 1) do
+            field(:minor) do
+              field(:tiny) do
+                field(:tiny2) do
+                  
+                  # The next field is a symbolic field that specifies the
+                  # release type: e.g. beta, release candidate, release, etc.
+                  field(:release_type, :type => :symbol) do
+                    
+                    # Development releases are typically expressed like
+                    # "1.0d3" and are intended for unstable development
+                    # progress. Bumping the release type will change it to
+                    # alpha.
+                    symbol(:development, :bump => :alpha)
+                    
+                    # Alpha releases are typically expressed like "1.0a2" and
+                    # are intended for internal testing.
+                    # Bumping the release type advances to beta.
+                    symbol(:alpha, :bump => :beta)
+                    
+                    # Beta releases are typically expressed like "1.0b2" and
+                    # are intended for external or public testing.
+                    # Bumping the release type advances to release candidate.
+                    symbol(:beta, :bump => :release_candidate)
+                    
+                    # Release candidate releases are typically expressed like
+                    # "1.0rc2" and are intended for final public testing
+                    # prior to release.
+                    # Bumping the release type advances to final release.
+                    symbol(:release_candidate, :bump => :final)
+                    
+                    # Preview releases represent an alternative release type
+                    # progression, and are typically used for public testing
+                    # similar to beta or release candidate.
+                    # Bumping the release type advances to final release.
+                    symbol(:preview, :bump => :final)
+                    
+                    # This type represents a final release. This is the
+                    # default value for the release_type field if no value is
+                    # explicitly provided.
+                    # Bumping the release type has no effect.
+                    symbol(:final, :bump => :final)
+                    default_value(:final)
+                    
+                    # If the release type is development, these fields are
+                    # made available to indicate which development release
+                    # is being represented.
+                    field(:development_version, :only => :development,
+                          :default_value => 1) do
+                      field(:development_minor)
+                    end
+                    
+                    # If the release type is alpha, these fields are made
+                    # available to indicate which alpha release is being
+                    # represented.
+                    field(:alpha_version, :only => :alpha, :default_value => 1) do
+                      field(:alpha_minor)
+                    end
+                    
+                    # If the release type is beta, these fields are made
+                    # available to indicate which beta release is being
+                    # represented.
+                    field(:beta_version, :only => :beta, :default_value => 1) do
+                      field(:beta_minor)
+                    end
+                    
+                    # If the release type is release candidate, these fields
+                    # are made available to indicate which release candidate
+                    # is being represented.
+                    field(:release_candidate_version, :only => :release_candidate,
+                          :default_value => 1) do
+                      field(:release_candidate_minor)
+                    end
+                    
+                    # If the release type is preview, these fields are made
+                    # available to indicate which preview release is being
+                    # represented.
+                    field(:preview_version, :only => :preview, :default_value => 1) do
+                      field(:preview_minor)
+                    end
+                    
+                    # If the release type is final, these fields are made
+                    # available to indicate an optional patchlevel.
+                    field(:patchlevel, :only => :final) do
+                      field(:patchlevel_minor)
+                    end
+                  end
+                end
+              end
+            end
+          end
+          
+          # Add the methods in this module to each value
+          add_module(Format::Standard::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(:major) do
+            recognize_number(:delimiter_regexp => '', :default_delimiter => '')
+          end
+          
+          # The remainder of the core version number are represented as
+          # 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(:minor) do
+            recognize_number(:default_value_optional => true)
+          end
+          field(:tiny) do
+            recognize_number(:default_value_optional => true)
+          end
+          field(:tiny2) do
+            recognize_number(:default_value_optional => true)
+          end
+          
+          # The release type field is the most complex field because of the
+          # variety of syntaxes we support. The basic strategy is to map
+          # a few specific sets of characters as signaling particular release
+          # types. For example, the "a" in "1.0a5" signals an alpha release.
+          # If no such release type marker is found, it defaults to the final
+          # release type.
+          # We set up two styles, a short style and a long style. Short style
+          # syntax looks like "1.0a5". Long syntax looks more like
+          # "1.0 Alpha 5". The parsed value retains knowledge of which style
+          # it came from so it can be reconstructed when the value is unparsed.
+          # Finally, we turn requires_previous_field off because the release
+          # type syntax markers don't require any particular set of the core
+          # version number fields to be present. "1.0a5" and "1.0.0.0a5" are
+          # both valid version numbers.
+          field(:release_type, :requires_previous_field => false,
+                :default_style => :short) do
+            # First check for "short form" syntax. Not that we support post-
+            # delimiters; that is, we recognize "1.0 pre-2" where the hyphen
+            # is a post-delimiter. Also notice that we expect prerelease types
+            # to be followed by a numeric prerelease version number.
+            recognize_regexp_map(:style => :short, :default_delimiter => '',
+                                 :delimiter_regexp => '-|\.|\s?',
+                                 :post_delimiter_regexp => '-|\.|\s?',
+                                 :expected_follower_regexp => '\d') do
+              map(:development, 'd')
+              map(:alpha, 'a')
+              map(:beta, 'b')
+              map(:release_candidate, 'rc')
+              map(:preview, 'pre')
+              # Note that we omit the value <tt>:final</tt>. This is because
+              # that value is signaled by the absence of any syntax in the
+              # version string, including the absence of any delimiters. So we
+              # just allow it to fall through to the default.
+            end
+            # Check for "long form" syntax. Note again that we omit :final.
+            recognize_regexp_map(:style => :long, :default_delimiter => '',
+                                 :delimiter_regexp => '-|\.|\s?',
+                                 :post_delimiter_regexp => '-|\.|\s?',
+                                 :expected_follower_regexp => '\d') do
+              map(:development, 'dev')
+              map(:alpha, 'alpha')
+              map(:beta, 'beta')
+              map(:release_candidate, 'rc')
+              map(:preview, 'preview')
+            end
+          end
+          
+          # The development version must appear in the string if it is present
+          # in the value, even if the value is 0. Similar for all the other
+          # prerelease version numbers: alpha, beta, release candidate, and
+          # preview. However, the minor fields are optional.
+          field(:development_version) do
+            recognize_number(:delimiter_regexp => '', :default_delimiter => '')
+          end
+          field(:development_minor) do
+            recognize_number(:default_value_optional => true)
+          end
+          field(:alpha_version) do
+            recognize_number(:delimiter_regexp => '', :default_delimiter => '')
+          end
+          field(:alpha_minor) do
+            recognize_number(:default_value_optional => true)
+          end
+          field(:beta_version) do
+            recognize_number(:delimiter_regexp => '', :default_delimiter => '')
+          end
+          field(:beta_minor) do
+            recognize_number(:default_value_optional => true)
+          end
+          field(:release_candidate_version) do
+            recognize_number(:delimiter_regexp => '', :default_delimiter => '')
+          end
+          field(:release_candidate_minor) do
+            recognize_number(:default_value_optional => true)
+          end
+          field(:preview_version) do
+            recognize_number(:delimiter_regexp => '', :default_delimiter => '')
+          end
+          field(:preview_minor) do
+            recognize_number(:default_value_optional => true)
+          end
+          
+          # The patchlevel field does not require the previous field (which is
+          # release_type). Here we also set up two styles: a numeric style and
+          # a letter style. So "1.0a" and "1.0-1" are equivalent.
+          field(:patchlevel, :requires_previous_field => false,
+                :default_value_optional => true, :default_style => :number) do
+            recognize_number(:style => :number, :default_delimiter => '-',
+                             :delimiter_regexp => '(-|\.|\s?)p|-')
+            recognize_letter(:style => :letter, :default_delimiter => '',
+                             :delimiter_regexp => '-|\.|\s?',
+                             :expected_follower_regexp => '\z')
+          end
+          field(:patchlevel_minor) do
+            recognize_number(:default_value_optional => true)
+          end
+          
+          # By default, we require that at least the major and minor fields
+          # appear in an unparsed version string.
+          default_unparse_params(:required_fields => [:minor])
+        end
+      end
+      
+      
+    end
+    
+    
+    register('standard', Format::Standard.create) unless get('standard')
+    
+    
+  end
+  
+end

data/lib/versionomy/format.rb

@@ -48,21 +48,90 @@ module Versionomy
   # only that schema's version numbers.
   # 
   # Under many circumstances, you should use the standard format, which
-  # can be retrieved by calling Versionomy::Formats#standard. This format
+  # can be retrieved by calling Versionomy::Format#standard. This format
   # understands most common version numbers, including prerelease
   # (e.g. alpha, beta, release candidate, etc.) forms and patchlevels.
   # 
   # You may also create your own formats, either by implementing the
-  # format contract (see Versionomy::Format::Base) or by using the
+  # format contract (see Versionomy::Format::Base), or by using the
   # Versionomy::Format::Delimiter tool, which can be used to construct
   # parsers for many version number formats.
   # 
   # Formats may be registered with Versionomy and given a name using the
-  # methods of this Versionomy::Formats. This allows version numbers to be
-  # serialized with their format.
+  # methods of this module. This allows version numbers to be serialized
+  # with their format.
+  # 
+  # Finally, this module serves as a namespace for format implementations.
   
   module Format
+    
+    @names_to_formats = ::Hash.new
+    @formats_to_names = ::Hash.new
+    
+    class << self
+      
+      
+      # 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.
+      
+      def get(name_, strict_=false)
+        format_ = @names_to_formats[name_.to_s]
+        if format_.nil? && strict_
+          raise Errors::UnknownFormatError, name_
+        end
+        format_
+      end
+      
+      
+      # Register the given format under the given name.
+      # 
+      # Valid names may contain only letters, digits, underscores, dashes,
+      # and periods.
+      # 
+      # 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_
+        end
+        @names_to_formats[name_] = format_
+        @formats_to_names[format_.object_id] = name_
+      end
+      
+      
+      # Get the canonical name for the given format, as a string.
+      # This is the first name the format was registered under.
+      # 
+      # If the given format was never registered, and strict is set to true,
+      # raises Versionomy::Errors::UnknownFormatError. If strict is set to
+      # false, returns nil if the given format was never registered.
+      
+      def canonical_name_for(format_, strict_=false)
+        name_ = @formats_to_names[format_.object_id]
+        if name_.nil? && strict_
+          raise Errors::UnknownFormatError
+        end
+        name_
+      end
+      
+      
+    end
+    
   end
   
   
+  # Versionomy::Formats is an alias for Versionomy::Format, for backward
+  # compatibility with version 0.1.0 code. It is deprecated; use
+  # Versionomy::Format instead.
+  Formats = Format
+  
+  
 end

data/lib/versionomy/interface.rb

@@ -48,27 +48,27 @@ module Versionomy
     
     
     # Gets the current default format. Usually this is the "standard"
-    # format returned by Versionomy::Formats.standard.
+    # format returned by Versionomy::Format.standard.
     
     def default_format
-      @default_format ||= Formats.standard
+      @default_format ||= Format.standard
     end
     
     
     # Sets the default format used by other methods of this convenience
     # interface. Usually, this is set to the "standard" format returned by
-    # Versionomy::Formats.standard and should not be changed.
+    # Versionomy::Format.standard and should not be changed.
     # 
     # The format can be specified as a format object or the name of a format
-    # registered with Versionomy::Formats. If the format is set to nil, the
+    # registered with Versionomy::Format. If the format is set to nil, the
     # default_format will be reset to the "standard" format.
     # 
     # Raises Versionomy::Errors::UnknownFormatError if a name is given that
     # is not registered.
     
     def default_format=(format_)
-      if format_.kind_of?(String) || format_.kind_of?(Symbol)
-        format_ = Formats.get(format_, true)
+      if format_.kind_of?(::String) || format_.kind_of?(::Symbol)
+        format_ = Format.get(format_, true)
       end
       @default_format = format_
     end
@@ -81,7 +81,7 @@ module Versionomy
     # array of values that will be interpreted in field order.
     # 
     # The format can be specified as a format object or the name of a format
-    # registered with Versionomy::Formats. If the format is omitted or set
+    # registered with Versionomy::Format. If the format is omitted or set
     # to nil, the default_format will be used.
     # 
     # You can also optionally provide default parameters to be used when
@@ -90,12 +90,16 @@ module Versionomy
     # Raises Versionomy::Errors::UnknownFormatError if a name is given that
     # is not registered.
     
-    def create(values_=[], format_=nil, unparse_params_=nil)
-      if format_.kind_of?(String) || format_.kind_of?(Symbol)
-        format_ = Formats.get(format_, true)
+    def create(values_=nil, format_=nil, unparse_params_=nil)
+      if format_.kind_of?(::Hash) && unparse_params_.nil?
+        unparse_params_ = format_
+        format_ = nil
+      end
+      if format_.kind_of?(::String) || format_.kind_of?(::Symbol)
+        format_ = Format.get(format_, true)
       end
       format_ ||= default_format
-      Value.new(values_, format_, unparse_params_)
+      Value.new(values_ || [], format_, unparse_params_)
     end
     
     
@@ -103,7 +107,7 @@ module Versionomy
     # format.
     # 
     # The format can be specified as a format object or the name of a format
-    # registered with Versionomy::Formats. If the format is omitted or set
+    # registered with Versionomy::Format. If the format is omitted or set
     # to nil, the default_format will be used.
     # 
     # The parameter hash, if present, will be passed as parsing parameters
@@ -115,8 +119,12 @@ module Versionomy
     # May raise Versionomy::Errors::ParseError if parsing failed.
     
     def parse(str_, format_=nil, parse_params_=nil)
-      if format_.kind_of?(String) || format_.kind_of?(Symbol)
-        format_ = Formats.get(format_, true)
+      if format_.kind_of?(::Hash) && parse_params_.nil?
+        parse_params_ = format_
+        format_ = nil
+      end
+      if format_.kind_of?(::String) || format_.kind_of?(::Symbol)
+        format_ = Format.get(format_, true)
       end
       format_ ||= default_format
       format_.parse(str_, parse_params_)

data/lib/versionomy/schema/field.rb

@@ -69,7 +69,6 @@ module Versionomy
       def initialize(name_, opts_={}, &block_)
         @name = name_.to_sym
         @type = opts_[:type] || :integer
-        @default_value = opts_[:default_value]
         if @type == :symbol
           @symbol_info = ::Hash.new
           @symbol_order = ::Array.new
@@ -77,13 +76,21 @@ module Versionomy
           @symbol_info = nil
           @symbol_order = nil
         end
+        @default_value = opts_[:default_value]
         @bump_proc = nil
         @compare_proc = nil
         @canonicalize_proc = nil
+        master_builder_ = opts_[:master_builder]
+        if master_builder_
+          @bump_proc = master_builder_._get_default_setting(@type, :bump)
+          @compare_proc = master_builder_._get_default_setting(@type, :compare)
+          @canonicalize_proc = master_builder_._get_default_setting(@type, :canonicalize)
+          @default_value ||= master_builder_._get_default_setting(@type, :value)
+        end
         @ranges = nil
         @default_child = nil
         @children = []
-        ::Blockenspiel.invoke(block_, Schema::FieldBuilder.new(self)) if block_
+        ::Blockenspiel.invoke(block_, Schema::FieldBuilder.new(self, master_builder_)) if block_
         @default_value = canonicalize_value(@default_value)
       end
       
@@ -120,11 +127,11 @@ module Versionomy
       
       
       def inspect   # :nodoc:
-        to_s
+        "#<#{self.class}:0x#{object_id.to_s(16)} name=#{@name}>"
       end
       
       def to_s   # :nodoc:
-        "#<#{self.class}:0x#{object_id.to_s(16)} name=#{@name}>"
+        inspect
       end
       
       
@@ -371,8 +378,9 @@ module Versionomy
       
       include ::Blockenspiel::DSL
       
-      def initialize(field_)  # :nodoc:
+      def initialize(field_, master_builder_)  # :nodoc:
         @field = field_
+        @master_builder = master_builder_
       end
       
       
@@ -474,6 +482,7 @@ module Versionomy
       
       def field(name_, opts_={}, &block_)
         only_ = opts_.delete(:only)
+        opts_.merge!(:master_builder => @master_builder)
         @field.add_child(Schema::Field.new(name_, opts_, &block_), only_)
       end