versionomy 0.0.4 → 0.1.0

data/lib/versionomy/format.rb

@@ -1,9 +1,9 @@
 # -----------------------------------------------------------------------------
 # 
-# Versionomy format
+# Versionomy format module
 # 
 # -----------------------------------------------------------------------------
-# Copyright 2008 Daniel Azuma
+# Copyright 2008-2009 Daniel Azuma
 # 
 # All rights reserved.
 # 
@@ -37,118 +37,32 @@
 module Versionomy
   
   
-  # This module is a namespace for tools that may be used to build formatters.
+  # === Version number format.
+  # 
+  # A format controls the parsing and unparsing of a version number.
+  # Any time a version number is parsed from a string, a format is provided
+  # to parse it. Similarly, every version number value references a format
+  # that is used to unparse it back into a string.
+  # 
+  # A format is always tied to a particular schema and knows how to parse
+  # 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
+  # understands most of the 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
+  # 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.
   
   module Format
-    
-    
-    # A simple base formatter.
-    # 
-    # Formats need not extend this base class, as long as they duck-type the
-    # required methods name, parse, and unparse.
-    
-    class Base
-      
-      # Create the formatter.
-      # If a block is provided, you may call methods of Versionomy::Format::Builder
-      # within the block, to specify ways to parse and unparse.
-      
-      def initialize(name_, &block_)
-        @name = name_.to_sym
-        @parser = @unparser = nil
-        Blockenspiel.invoke(block_, Versionomy::Format::Builder.new(self))
-      end
-      
-      
-      def _set_parser(block_)  # :nodoc:
-        @parser = block_
-      end
-      
-      def _set_unparser(block_)  # :nodoc:
-        @unparser = block_
-      end
-      
-      def _set_name(name_)  # :nodoc:
-        @name = name_
-      end
-      
-      
-      # The format name
-      
-      def name
-        @name
-      end
-      
-      
-      # A simple parse algorithm.
-      # If a parser block was provided during initialization, calls that block.
-      # Otherwise, attempts to parse using "." as a delimiter.
-      
-      def parse(schema_, string_, params_)
-        if @parser
-          @parser.call(schema_, string_, params_)
-        else
-          array_ = string_.split('.')
-          Versionomy::Value.new(schema_, array_)
-        end
-      end
-      
-      
-      # A simple parse algorithm.
-      # If an unparser block was provided during initialization, calls that block.
-      # Otherwise, attempts to unparse using "." as a delimiter.
-      
-      def unparse(schema_, value_, params_)
-        if @unparser
-          @unparser.call(schema_, value_, params_)
-        else
-          value_.values.join('.')
-        end
-      end
-      
-    end
-    
-    
-    # These methods are available in an initializer block for Versionomy::Format::Base.
-    
-    class Builder < Blockenspiel::Base
-      
-      def initialize(format_)  # :nodoc:
-        @format = format_
-      end
-      
-      
-      # Specify how to parse a string into a version value.
-      # 
-      # The block should take three parameters: a schema, a string, and a parameters hash.
-      # The block should return an object of type Versionomy::Value.
-      # You may raise Versionomy::Errors::ParseError if parsing failed.
-      
-      def to_parse(&block_)
-        @format._set_parser(block_)
-      end
-      
-      
-      # Specify how to represent a version value as a string.
-      # 
-      # The block should take three parameters: a schema, a Versionomy::Value, and a parameters hash.
-      # The block should return a string.
-      # You may raise Versionomy::Errors::ParseError if unparsing failed.
-      
-      def to_unparse(&block_)
-        @format._set_unparser(block_)
-      end
-      
-      
-      # Specify the format name
-      
-      def set_name(name_)
-        @format._set_name(name_)
-      end
-      
-    end
-    
-    
   end
   
+  
 end

data/lib/versionomy/formats/standard.rb

@@ -0,0 +1,346 @@
+# -----------------------------------------------------------------------------
+# 
+# Versionomy format 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
+  
+  module Formats
+    
+    
+    # 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 the _create_standard method.
+    
+    def self.standard
+      get('standard')
+    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_standard
+      
+      # 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
+      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 => '$')
+        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
+    
+    
+    register('standard', _create_standard) unless get('standard')
+    
+    
+  end
+  
+end

data/lib/versionomy/formats.rb

@@ -0,0 +1,79 @@
+# -----------------------------------------------------------------------------
+# 
+# Versionomy format module
+# 
+# -----------------------------------------------------------------------------
+# 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
+  
+  
+  # === Version number format regsitry.
+  # 
+  # Use the methods of this module to register formats with a name. This
+  # allows version numbers to be serialized with their format.
+  # 
+  # You may also access predefined formats such as the standard format from
+  # this module. It also contains the implementations of these formats as
+  # examples.
+  
+  module Formats
+    
+    
+    @names = ::Hash.new
+    
+    
+    # Get the format with the given name.
+    
+    def self.get(name_)
+      @names[name_.to_s]
+    end
+    
+    
+    # Register the given format under the given name.
+    # 
+    # Raises Versionomy::Errors::FormatRedefinedError if the name has
+    # already been defined.
+    
+    def self.register(name_, format_)
+      name_ = name_.to_s
+      if @names.include?(name_)
+        raise Errors::FormatRedefinedError, name_
+      end
+      @names[name_] = format_
+    end
+    
+    
+  end
+  
+  
+end

data/lib/versionomy/interface.rb

@@ -3,7 +3,7 @@
 # Versionomy convenience interface
 # 
 # -----------------------------------------------------------------------------
-# Copyright 2008 Daniel Azuma
+# Copyright 2008-2009 Daniel Azuma
 # 
 # All rights reserved.
 # 
@@ -41,46 +41,52 @@
 
 module Versionomy
   
-  @default_schema = Versionomy::Standard.schema
+  @default_format = nil
   
   
   class << self
     
     
-    # Gets the current default schema. Usually this is Versionomy::Standard.schema.
+    # Gets the current default format. Usually this is the "standard"
+    # format returned by Versionomy::Formats.standard.
     
-    def default_schema
-      @default_schema
+    def default_format
+      @default_format ||= Formats.standard
     end
     
     
-    # Sets the default schema. Usually this should be left as Versionomy::Standard.schema.
+    # Sets the default format.
+    # Usually this should be left as the "standard" format returned by
+    # Versionomy::Formats.standard. To reset to that value, pass nil.
     
-    def default_schema=(schema_)
-      @default_schema = schema_
+    def default_format=(format_)
+      @default_format = format_
     end
     
     
     # Create a new version number given a hash or array of values, and an
-    # optional schema.
+    # optional format.
     # 
     # The values should either be a hash of field names and values, or an array
     # of values that will be interpreted in field order.
     # 
-    # If schema is omitted, the default_schema will be used.
+    # If the format is omitted or set to nil, the default_format will be used.
+    # 
+    # You can also optionally provide default unparsing parameters for the value.
     
-    def create(values_=nil, schema_=nil)
-      (schema_ || @default_schema).create(values_)
+    def create(values_=[], format_=nil, unparse_params_=nil)
+      Value.new(values_, format_ || default_format, unparse_params_)
     end
     
     
-    # Create a new version number given a string to parse, and optional parse
-    # parameters and schema.
+    # Create a new version number given a string to parse, and an optional format.
+    # 
+    # If the format is omitted or set to nil, the default_format will be used.
     # 
-    # If schema is omitted, the default_schema will be used.
+    # The params, if present, will be passed as parsing parameters to the format.
     
-    def parse(str_, params_={}, schema_=nil)
-      (schema_ || @default_schema).parse(str_, params_)
+    def parse(str_, format_=nil, parse_params_=nil)
+      (format_ || default_format).parse(str_, parse_params_)
     end
     
   end