versionomy 0.4.1 → 0.4.2

data/lib/versionomy/schema.rb

@@ -1,15 +1,15 @@
 # -----------------------------------------------------------------------------
-# 
+#
 # Versionomy schema namespace
-# 
+#
 # -----------------------------------------------------------------------------
 # 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,
@@ -18,7 +18,7 @@
 # * 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
@@ -35,10 +35,10 @@
 
 
 module Versionomy
-  
-  
+
+
   # === Version number schema.
-  # 
+  #
   # A schema defines the structure and semantics of a version number.
   # The schema controls what fields are present in the version, how
   # version numbers are compared, what the default values are, and how
@@ -46,50 +46,50 @@ module Versionomy
   # 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 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 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)
-  # 
+  #
   # More generally, fields are actually organized into a DAG (directed
   # acyclic graph) in which the "most significant" field is the root, the
   # next most significant is a child of that root, and so forth down the
   # line. The simple schema above, then, is actually represented as a
   # linked list (a graph with one path), like this:
-  # 
+  #
   #  ("major": integer) ->
   #      ("minor": integer) ->
   #          ("tiny": integer) ->
   #              nil
-  # 
+  #
   # It is, however, possible for the form of a field to depend on the value
   # of the previous field. For example, suppose we wanted a schema in which
   # if the value of the "minor" field is 0, then the "tiny" field doesn't
   # exist. e.g.
-  # 
+  #
   #  ("major": integer) ->
   #      ("minor": integer) ->
   #          [value == 0] : nil
   #          [otherwise]  : ("tiny": integer) ->
   #              nil
-  # 
+  #
   # The Versionomy::Schema::Field class represents a field in this graph.
   # The Versionomy::Schema::Wrapper class represents a full schema object.
-  # 
+  #
   # Generally, you should create schemas using Versionomy::Schema#create.
   # That method provides a DSL that lets you quickly create the fields.
-  
+
   module Schema
   end
-  
-  
+
+
 end

data/lib/versionomy/schema/field.rb

@@ -1,15 +1,15 @@
 # -----------------------------------------------------------------------------
-# 
+#
 # Versionomy schema field class
-# 
+#
 # -----------------------------------------------------------------------------
 # 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,
@@ -18,7 +18,7 @@
 # * 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
@@ -38,19 +38,19 @@ require 'set'
 
 
 module Versionomy
-  
+
   module Schema
-    
-    
+
+
     # Objects of this class represent fields in a schema.
-    
+
     class Field
-      
-      
+
+
       # Create a field with the given name.
-      # 
+      #
       # Recognized options include:
-      # 
+      #
       # <tt>:type</tt>::
       #   Type of field. This should be <tt>:integer</tt>, <tt>:string</tt>,
       #   or <tt>:symbol</tt>. Default is <tt>:integer</tt>.
@@ -58,14 +58,14 @@ module Versionomy
       #   Default value for the field if no value is explicitly set. Default
       #   is 0 for an integer field, the empty string for a string field, or
       #   the first symbol added for a symbol field.
-      # 
+      #
       # You may provide an optional block. Within the block, you may call
       # methods of Versionomy::Schema::FieldBuilder to further customize the
       # field, or add child fields.
-      # 
+      #
       # Raises Versionomy::Errors::IllegalValueError if the given default
       # value is not legal.
-      
+
       def initialize(name_, opts_={}, &block_)
         @name = name_.to_sym
         @type = opts_[:type] || :integer
@@ -93,12 +93,12 @@ module Versionomy
         ::Blockenspiel.invoke(block_, Schema::FieldBuilder.new(self, master_builder_)) if block_
         @default_value = canonicalize_value(@default_value)
       end
-      
-      
+
+
       def _set_default_value(value_)  # :nodoc:
         @default_value = value_
       end
-      
+
       def _add_symbol(symbol_, opts_={})  # :nodoc:
         if @type != :symbol
           raise Errors::TypeMismatchError
@@ -112,64 +112,64 @@ module Versionomy
           @default_value = symbol_
         end
       end
-      
+
       def _set_bump_proc(block_)  # :nodoc:
         @bump_proc = block_
       end
-      
+
       def _set_canonicalize_proc(block_)  # :nodoc:
         @canonicalize_proc = block_
       end
-      
+
       def _set_compare_proc(block_)  # :nodoc:
         @compare_proc = block_
       end
-      
-      
+
+
       def inspect   # :nodoc:
         "#<#{self.class}:0x#{object_id.to_s(16)} name=#{@name}>"
       end
-      
+
       def to_s   # :nodoc:
         inspect
       end
-      
-      
+
+
       # The name of the field.
-      
+
       def name
         @name
       end
-      
-      
+
+
       # The type of the field.
       # Possible values are <tt>:integer</tt>, <tt>:string</tt>, or
       # <tt>:symbol</tt>.
-      
+
       def type
         @type
       end
-      
-      
+
+
       # The default value of the field
-      
+
       def default_value
         @default_value
       end
-      
-      
+
+
       # Returns a list of possible values for this field, if the type is
       # <tt>:symbol</tt>. Returns nil for any other type
-      
+
       def possible_values
         @symbol_order ? @symbol_order.dup : nil
       end
-      
-      
+
+
       # Given a value, bump it to the "next" value.
       # Utilizes a bump procedure if given;
       # otherwise uses default behavior depending on the type.
-      
+
       def bump_value(value_)
         if @bump_proc
           nvalue_ = @bump_proc.call(value_)
@@ -181,13 +181,13 @@ module Versionomy
           info_ ? info_[1] || value_ : nil
         end
       end
-      
-      
+
+
       # Perform a standard comparison on two values.
       # Returns an integer that may be positive, negative, or 0.
       # Utilizes a comparison procedure if given;
       # otherwise uses default behavior depending on the type.
-      
+
       def compare_values(val1_, val2_)
         if @compare_proc
           @compare_proc.call(val1_, val2_)
@@ -199,15 +199,15 @@ module Versionomy
           info1_ && info2_ ? info1_[0] <=> info2_[0] : nil
         end
       end
-      
-      
+
+
       # Given a value, return a "canonical" value for this field.
       # Utilizes a canonicalization procedure if given;
       # otherwise uses default behavior depending on the type.
-      # 
+      #
       # Raises Versionomy::Errors::IllegalValueError if the given value is
       # not legal.
-      
+
       def canonicalize_value(value_)
         orig_value_ = value_
         if @canonicalize_proc
@@ -227,11 +227,11 @@ module Versionomy
         end
         value_
       end
-      
-      
+
+
       # Returns the child field associated with the given value.
       # Returns nil if this field has no child for the given value.
-      
+
       def child(value_)  # :nodoc:
         if @ranges
           @ranges.each do |r_|
@@ -248,30 +248,30 @@ module Versionomy
         end
         @default_child
       end
-      
-      
+
+
       # Adds the given child field for the given range.
-      # 
+      #
       # If you provide a range of nil, adds the given child field as the
       # default child for values that do not fall into any other
       # explicitly specified range.
-      # 
+      #
       # Otherwise, the ranges parameter must be an array of "range" objects.
       # Each of these range objects must be either a single String, Symbol,
       # or Integer to specify a single value; or a two-element array or a
       # Range object (only inclusive ends are supported) to specify a range
       # of values.
-      # 
+      #
       # Raises Versionomy::Errors::RangeOverlapError if the specified
       # range overlaps another previously specified range, or if more than
       # one default child has been set.
-      # 
+      #
       # Raises Versionomy::Errors::RangeSpecificationError if the range
       # is incorrectly specified.
-      # 
+      #
       # Raises Versionomy::Errors::CircularDescendantError if adding this
       # child will result in a circular reference.
-      
+
       def add_child(child_, ranges_=nil)
         if child_._descendant_fields.include?(self)
           raise Errors::CircularDescendantError
@@ -348,101 +348,101 @@ module Versionomy
           @ranges.insert(insert_index_, normalized_range_)
         end
       end
-      
-      
+
+
       # Compute descendants as a hash of names to fields, including this field.
-      
+
       def _descendants_by_name  # :nodoc:
         hash_ = {@name => self}
         @children.each{ |child_| hash_.merge!(child_._descendants_by_name) }
         hash_
       end
-      
-      
+
+
       # Return a set of all descendant fields, including this field.
-      
+
       def _descendant_fields(set_=nil)  # :nodoc:
         set_ ||= Set.new
         set_ << self
         @children.each{ |child_| child_._descendant_fields(set_) }
         set_
       end
-      
-      
+
+
     end
-    
-    
+
+
     # These methods are available in a schema field definition block.
-    
+
     class FieldBuilder
-      
+
       include ::Blockenspiel::DSL
-      
+
       def initialize(field_, master_builder_)  # :nodoc:
         @field = field_
         @master_builder = master_builder_
       end
-      
-      
+
+
       # Define the given symbol.
-      # 
+      #
       # Recognized options include:
-      # 
+      #
       # <tt>:bump</tt>::
       #   The symbol to transition to when "bump" is called.
       #   Default is to remain on the same value.
-      # 
+      #
       # Raises Versionomy::Errors::TypeMismatchError if called when the current field
       # is not of type <tt>:symbol</tt>.
-      # 
+      #
       # Raises Versionomy::Errors::SymbolRedefinedError if the given symbol name is
       # already defined.
-      
+
       def symbol(symbol_, opts_={})
         @field._add_symbol(symbol_, opts_)
       end
-      
-      
+
+
       # Provide a default value.
-      
+
       def default_value(value_)
         @field._set_default_value(value_)
       end
-      
-      
+
+
       # Provide a "bump" procedure.
       # The given block should take a value, and return the value to transition to.
       # If you return nil, the value will remain the same.
-      
+
       def to_bump(&block_)
         @field._set_bump_proc(block_)
       end
-      
-      
+
+
       # Provide a "compare" procedure.
       # The given block should take two values and compare them.
       # It should return a negative integer if the first is less than the second,
       # a positive integer if the first is greater than the second, or 0 if the
       # two values are equal. If the values cannot be compared, return nil.
-      
+
       def to_compare(&block_)
         @field._set_compare_proc(block_)
       end
-      
-      
+
+
       # Provide a "canonicalize" procedure.
       # The given block should take a value and return a canonicalized value.
       # Return nil if the given value is illegal.
-      
+
       def to_canonicalize(&block_)
         @field._set_canonicalize_proc(block_)
       end
-      
-      
+
+
       # Add a child field.
-      # 
+      #
       # Recognized options include:
-      # 
+      #
       # <tt>:only</tt>::
       #   The child should be available only for the given values of this
       #   field. See below for ways to specify this constraint.
@@ -453,16 +453,16 @@ module Versionomy
       #   Default value for the field if no value is explicitly set. Default
       #   is 0 for an integer field, the empty string for a string field, or
       #   the first symbol added for a symbol field.
-      # 
+      #
       # You may provide an optional block. Within the block, you may call
       # methods of this class again to customize the child.
-      # 
+      #
       # Raises Versionomy::Errors::IllegalValueError if the given default
       # value is not legal.
-      # 
+      #
       # The <tt>:only</tt> constraint may be specified in one of the
       # following ways:
-      # 
+      #
       # * A single value (integer, string, or symbol)
       # * The result of calling range() to define an inclusive range of
       #   integers, strings, or symbols. In this case, either element may be
@@ -472,38 +472,38 @@ module Versionomy
       # * A Range object defining a range of integers or strings.
       #   Only inclusive, not exclusive, ranges are supported.
       # * An array of the above.
-      # 
+      #
       # Raises Versionomy::Errors::RangeSpecificationError if the given
       # ranges are not legal.
-      # 
+      #
       # Raises Versionomy::Errors::RangeOverlapError if the given ranges
       # overlap previously specified ranges, or more than one default schema
       # is specified.
-      
+
       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
-      
-      
+
+
       # Define a range for the <tt>:only</tt> parameter to +child+.
-      # 
+      #
       # This creates an object that +child+ interprets like a standard ruby Range. However, it
       # is customized for the use of +child+ in the following ways:
-      # 
+      #
       # * It supports only inclusive, not exclusive ranges.
       # * It supports open-ended ranges by setting either endpoint to nil.
       # * It supports symbol ranges under Ruby 1.8.
-      
+
       def range(first_, last_)
         [first_, last_]
       end
-      
-      
+
+
     end
-    
-    
+
+
   end
-  
+
 end