value 1.1.1 → 1.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 668d28c3bd798b898afcc5b782521df80f2a9e5b
+  data.tar.gz: 745278ed7c2d47b1629f7d50cc0fbade7ab424ea
+SHA512:
+  metadata.gz: 5784be59177957109238bdc88aa732d1917e8d633e20cebddba6fe873466b49a92a405a0d5f052d1e3b170722a4c2773d590f9a755f71fde2b3caec142346939
+  data.tar.gz: 8331cbb10dff97c705408169cae3dcf938a6bb52642ca1baa02fb4f7477765a8b5f4b60bc1dffe5033921681138c3672aa0d4c4b964e97a2662794ff1964c825

data/README

@@ -1,3 +1,165 @@
                                      Value
 
-  Value is a library for defining value objects in Ruby.
+  Value is a library for defining immutable value objects in Ruby.  A value
+  object is an object whose equality to other objects is determined by its
+  value, not its identity, think dates and amounts of money.  A value object
+  should also be immutable, as you don’t want the date “2013-04-22” itself to
+  change but the current date to change from “2013-04-22” to “2013-04-23”.
+  That is, you don’t want entries in a calendar for 2013-04-22 to move to
+  2013-04-23 simply because the current date changes from 2013-04-22 to
+  2013-04-23.
+
+  A value object consists of one or more attributes stored in instance
+  variables.  Value sets up an #initialize method for you that let’s you set
+  these attributes, as, value objects being immutable, this’ll be your only
+  chance to do so.  Value also adds equality checks ‹#==› and ‹#eql?› (which
+  are themselves equivalent), a ‹#hash› method, a nice ‹#inspect› method, and a
+  protected attribute reader for each attribute.  You may of course add any
+  additional methods that your value object will benefit from.
+
+  That’s basically all there’s too it.  Let’s now look at using the Value
+  library.
+
+§ Usage
+
+    You create value object class by invoking ‹#Value› inside the class
+    (module) you wish to make into a value object class.  Let’s create a class
+    that represent points on a plane:
+
+      class Point
+        Value :x, :y
+      end
+
+    A ‹Point› is thus a value object consisting of two sub-values ‹x› and ‹y›
+    (the coordinates).  Just from invoking ‹#Value›, a ‹Point› object will have
+    a constructor that takes two arguments to set instance variables ‹@x› and
+    ‹@y›, equality checks ‹#==› and ‹#eql?› (which are the same), a ‹#hash›
+    method, a nice ‹#inspect› method, and two protected attribute readers ‹#x›
+    and ‹#y›.  We can thus already creat ‹Point›s:
+
+      origo = Point.new(0, 0)
+
+    The default of making the attribute readers protected is often good
+    practice, but for a ‹Point› it probably makes sense to be able to access
+    its coordinates:
+
+      class Point
+        public(*attributes)
+      end
+
+    This’ll make all attributes of ‹Point› public.  You can of course choose to
+    only make certain attributes public:
+
+      class Point
+        public :x
+      end
+
+    Note that this public is standard Ruby functionality.  Adding a method to
+    ‹Point› is of course also possible and very much Rubyish:
+
+      class Point
+        def distance(other)
+          Math.sqrt((other.x - x)**2 + (other.y - y)**2)
+        end
+      end
+
+    For some value object classes you might want to support optional
+    attributes.  This is done by providing a default value for the attribute,
+    like so:
+
+      class Money
+        Value :amount, [:currency, :USD]
+      end
+
+    Here, the ‹currency› attribute will default to ‹:USD›.  You can create
+    ‹Money› via
+
+      dollars = Money.new(2)
+
+    but also
+
+      kronor = Money.new(2, :SEK)
+
+    All required attributes must come before any optional attributes.
+
+    Splat attributes are also supported:
+
+      class List
+        Value :'*elements'
+      end
+
+      empty = List.new
+      suits = List.new(:spades, :hearts, :diamonds, :clubs)
+
+    Splat attributes are optional.
+
+    Finally, block attributes are also available:
+
+      class Block
+        Value :'&block'
+      end
+
+      block = Block.new{ |e| e * 2 }
+
+    Block attributes are optional.
+
+    Comparison beyond ‹#==› is possible by specifingy the ‹:comparable› option
+    to ‹#Value›, listing one or more attributes that should be included in the
+    comparison:
+
+      class Vector
+        Value :a, :b, :comparable => :a
+      end
+
+    Note that equality (‹#==› and ‹#eql?›) is always defined based on all
+    attributes, regardless of arguments to ‹:comparable›.
+
+    Here we say that comparisons between ‹Vector›s should be made between the
+    values of the ‹a› attribute only.  We can also make comparisons between all
+    attributes of a value object:
+
+      class Vector
+        Value :a, :b, :comparable => true
+      end
+
+    To sum things up, let’s use all possible arguments to ‹#Value› at once:
+
+      class Method
+        Value :file, :line, [:name, 'unnamed'], :'*args', :'&block',
+              :comparable => [:file, :line]
+      end
+
+    A ‹Method› consists of file and line information, a possible name, some
+    arguments, possibly a block, and is comparable on the file and line on
+    which they appear.
+
+    Check out the {full API documentation}¹ for a more explicit description,
+    should you need it or should you want to extend it.
+
+¹ http://disu.se/software/value/api/
+
+§ Financing
+
+    Currently, most of my time is spent at my day job and in my rather busy
+    private life.  Please motivate me to spend time on this piece of software
+    by donating some of your money to this project.  Yeah, I realize that
+    requesting money to develop software is a bit, well, capitalistic of me.
+    But please realize that I live in a capitalistic society and I need money
+    to have other people give me the things that I need to continue living
+    under the rules of said society.  So, if you feel that this piece of
+    software has helped you out enough to warrant a reward, please PayPal a
+    donation to now@disu.se¹.  Thanks!  Your support won’t go unnoticed!
+
+¹ Send a donation:
+  https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=now%40disu%2ese&item_name=Nikolai%20Weibull%20Software%20Services
+
+§ Reporting Bugs
+
+    Please report any bugs that you encounter to the {issue tracker}¹.
+
+  ¹ See https://github.com/now/value/issues
+
+§ Authors
+
+    Nikolai Weibull wrote the code, the tests, the manual pages, and this
+    README.

data/Rakefile

@@ -1,13 +1,22 @@
 # -*- coding: utf-8 -*-
 
-require 'inventory/rake-1.0'
-require 'lookout/rake-3.0'
+require 'inventory-rake-1.0'
 
-load File.expand_path('../lib/value/version.rb', __FILE__)
+load File.expand_path('../lib/value-1.0/version.rb', __FILE__)
 
 Inventory::Rake::Tasks.define Value::Version, :gem => proc{ |_, s|
   s.author = 'Nikolai Weibull'
   s.email = 'now@bitwi.se'
   s.homepage = 'https://github.com/now/value'
 }
-Lookout::Rake::Tasks::Test.new
+
+Inventory::Rake::Tasks.unless_installing_dependencies do
+  require 'lookout-rake-3.0'
+  Lookout::Rake::Tasks::Test.new
+
+  require 'inventory-rake-tasks-yard-1.0'
+  Inventory::Rake::Tasks::YARD.new do |t|
+    t.options += %w'--plugin yard-heuristics-1.0'
+    t.globals[:source_code_url] = 'https://github.com/now/%s/blob/v%s/%%s#L%%d' % [t.inventory.package, t.inventory]
+  end
+end

data/lib/value-1.0.rb

@@ -1,71 +1,134 @@
 # -*- coding: utf-8 -*-
 
+# Represents an immutable [value
+# object](http://en.wikipedia.org/wiki/Value_object) with an {#initialize}
+# method, equality checks {#==} and {#eql?}, a {#hash} function, and an
+# {#inspect} method.
+#
+# @example A Point Value Object
+#   class Point
+#     Value :x, :y
+#   end
+#
+# @example A Point Value Object with Public Accessors
+#   class Point
+#     Value :x, :y
+#     public(*attributes)
+#   end
+#
+# @example A Value Object with Optional Attributes
+#   class Money
+#     Value :amount, [:currency, :USD]
+#   end
+#
+# @example A Value Object with a Comparable Attribute
+#   class Vector
+#     Value :a, :b, :comparable => :a
+#   end
 module Value
+  # Creates a new value object, using ARGUMENTS to set up the value’s
+  # {Attributes#required required}, {Attributes#optional optional}, and
+  # {Attributes#splat splat} attributes, and the given block, if given,
+  # if a {Attributes#block block} is desired.
+  #
+  # @param [Object, …] arguments
+  # @raise [ArgumentError] If ARGUMENTS#length is less than the number of
+  #   {Attributes#required required} attributes
+  # @raise [ArgumentError] If ARGUMENTS#length is greater than the number of
+  #   {Attributes#required required} and {Attributes#optional optional}
+  #   attributes
+  # @yield [?]
   def initialize(*arguments)
     raise ArgumentError,
       'wrong number of arguments (%d for %d)' %
-        [arguments.length, values.required.length] if
-          arguments.length < values.required.length
+        [arguments.length, attributes.required.length] if
+          arguments.length < attributes.required.length
     raise ArgumentError,
       'wrong number of arguments (%d for %d)' %
         [arguments.length,
-         values.required.length + values.optional.length] if
-          arguments.length > values.required.length +
-            values.optional.length and not values.splat
-    instance_variable_set :"@#{values.block}",
-      block_given? ? Proc.new : nil if values.block
-    instance_variable_set :"@#{values.splat}",
-      arguments[values.required.length +
-                values.optional.length..-1] if values.splat
-    values.required.each_with_index do |value, index|
+         attributes.required.length + attributes.optional.length] if
+          arguments.length > attributes.required.length +
+            attributes.optional.length and not attributes.splat
+    instance_variable_set :"@#{attributes.block}",
+      block_given? ? Proc.new : nil if attributes.block
+    instance_variable_set :"@#{attributes.splat}",
+      arguments[attributes.required.length +
+                attributes.optional.length..-1] if attributes.splat
+    attributes.required.each_with_index do |value, index|
       instance_variable_set :"@#{value}", arguments[index]
     end
-    values.optional.each_with_index do |(value, default), index|
-      offset = values.required.length + index
+    attributes.optional.each_with_index do |(value, default), index|
+      offset = attributes.required.length + index
       instance_variable_set :"@#{value}",
         offset >= arguments.length ? default : arguments[offset]
     end
   end
 
+  # @return [Boolean] True if the receiver’s class and all of its {Attributes}
+  #   `#==` those of OTHER
   def ==(other)
-    self.class == other.class and
-      values.all?{ |value| send(value) == other.send(value) }
+    self.class == other.class and attributes.all?{ |e| send(e) == other.send(e) }
   end
 
+  # (see #==)
   alias eql? ==
 
+  # @return [Fixnum] The hash value of the receiver’s class XORed with the hash
+  #   value of the Array of the values of the {Attributes} of the receiver
   def hash
-    self.class.hash ^ values.map{ |value| send(value) }.hash
+    self.class.hash ^ attributes.map{ |e| send(e) }.hash
   end
 
+  # @return [String] The inspection of the receiver
   def inspect
     '%s.new(%s)' %
       [self.class,
-       [values.required.map{ |name| send(name).inspect },
-        values.optional.
+       [attributes.required.map{ |name| send(name).inspect },
+        attributes.optional.
           map{ |name, default| [send(name), default] }.
-          select{ |value, default| value != default or values.splat }.
+          select{ |value, default| value != default or attributes.splat }.
           map{ |value, _| value },
-        values.splat ? send(values.splat).map{ |value| value.inspect } : [],
-        values.block ? ['&%s' % [send(values.block).inspect]] : []].
+        attributes.splat ? send(attributes.splat).map{ |value| value.inspect } : [],
+        attributes.block ? ['&%s' % [send(attributes.block).inspect]] : []].
           flatten.join(', ')]
   end
 
-  load File.expand_path('../value/version.rb', __FILE__)
+  private
+
+  def values
+    warn "%s#%s: deprecated, use #attributes" % [self.class, __method__]
+    attributes
+  end
+
+  load File.expand_path('../value-1.0/version.rb', __FILE__)
   Version.load
 end
 
+# Ruby’s Module class, extended to add {Module#Value #Value}, a way of creating
+# value object classes.
 class Module
+  # @overload Value(first, *rest, options = {})
+  #
+  #   Marks the module as a {::Value} object with attributes FIRST and REST.
+  #   This’ll add protected attribute readers for each of these attributes and
+  #   a private method #attributes that returns the {Value::Attributes}
+  #   themselves, include {Value::Comparable} if COMPARABLE isn’t falsy, and
+  #   finally include {::Value}.
+  #
+  #   @param (see ::Value::Attributes#initialize)
+  #   @option (see ::Value::Attributes#initialize)
+  #   @raise (see ::Value::Attributes#initialize)
   def Value(first, *rest)
     options = Hash === rest.last ? rest.pop : {}
-    values = Value::Values.new(*([first] + rest).push({:comparable => options[:comparable]}))
-    attr_reader(*values)
-    protected(*values)
-    define_method :values do
-      values
+    attributes = Value::Attributes.new(first, *rest.dup.push({:comparable => options[:comparable]}))
+    attr_reader(*attributes)
+    protected(*attributes)
+    define_method :attributes do
+      attributes
     end
-    private :values
+    private :attributes
     include Value::Comparable if options[:comparable]
     include Value
+    self
   end
 end

data/lib/value-1.0/attributes.rb

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+
+# Keeps track of the structure of the attributes associated with a {Value}
+# object.  This is an ordered set of {#required}, {#optional}, {#splat}, and
+# {#block} arguments to the value object’s {Value#initialize initialize}
+# method, some or all of which may be {#comparable}.
+class Value::Attributes
+  include Enumerable
+
+  # @overload initialize(first, *rest, options = {})
+  #
+  #   Sets up a {Value} objects attributes FIRST and REST.  If the last
+  #   attribute starts with ‘&’, then the value object’s {Value#initialize
+  #   initialize} method may take an optional block.  If the last or second to
+  #   last, depending on the previous sentence, attribute starts with ‘*’, then
+  #   the value object’s {Value#initialize initialize} method may take a splat
+  #   argument.  The rest of the attributes are split at the first element
+  #   that’s an Array.  All attributes before this element are required
+  #   arguments to the value object’s {Value#initialize initialize} method.
+  #   The first element that’s an Array and all following elements, which
+  #   should also be Arrays, are optional arguments to the value object’s
+  #   {Value#initialize initialize} method, where the first element of these
+  #   Arrays is the attribute and the last element is its default value.
+  #
+  #   @param [Symbol, Array<Symbol, Object>] first
+  #   @param [Array<Symbol, Array<Symbol, Object>>] rest
+  #   @param [Hash] options
+  #   @option options [Array<Symbol>, Boolean, nil] :comparable (nil) The
+  #     subset of first and rest that should be used for comparing instances of
+  #     this value object class, or a truthy value to use the whole set, or a
+  #     falsy value to use an empty set
+  #   @raise [ArgumentError] If any element of COMPARABLE isn’t an element of
+  #     first and rest
+  def initialize(first, *rest)
+    options = Hash === rest.last ? rest.pop : {}
+    names = [first] + rest
+    names.pop if @block = names.last.to_s.start_with?('&') ?
+      names.last.to_s[1..-1].to_sym : nil
+    names.pop if @splat = (names.last and names.last.to_s.start_with?('*')) ?
+      names.last.to_s[1..-1].to_sym : nil
+    @required = names.take_while{ |e| not(Array === e) }.map(&:to_sym)
+    @optional = names[required.length..-1].map{ |e| [e.first.to_sym, e.last] }
+    all = to_a
+    @comparable =
+      case options[:comparable]
+      when Array
+        options[:comparable].each{ |e|
+          raise ArgumentError, '%p is not among comparable members %s' %
+            [e, all.map(&:inspect).join(', ')] unless all.include?(e)
+        }
+      when false, nil
+        []
+      else
+        all
+      end
+  end
+
+  # @overload
+  #   Enumerates the attributes.
+  #
+  #   @yieldparam [Symbol] attribute
+  # @overload
+  #   @return [Enumerator<Symbol>] An Enumerator over the attributes
+  def each
+    return enum_for(__method__) unless block_given?
+    required.each do |name|
+      yield name
+    end
+    optional.each do |name, _|
+      yield name
+    end
+    yield splat if splat
+    yield block if block
+    self
+  end
+
+  # @return [Boolean] True if the receiver’s class and its required, optional,
+  #   splat, and block attributes `#==` those of OTHER
+  def ==(other)
+    self.class == other.class and
+      required == other.required and
+      optional == other.optional and
+      splat == other.splat and
+      block == other.block
+  end
+
+  # @return [Array<Symbol>] The required attributes
+  attr_reader :required
+
+  # @return [Array<Array<Symbol, Object>>] The optional attributes and their
+  #   defaults
+  attr_reader :optional
+
+  # @return [Symbol, nil] The splat attribute
+  attr_reader :splat
+
+  # @return [Symbol, nil] The block attribute
+  attr_reader :block
+
+  # @return [Array<Symbol>] The comparable attributes
+  attr_reader :comparable
+end

data/lib/value-1.0/comparable.rb

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+
+# Module included by {Module#Value} when passed the :comparable option.
+module Value::Comparable
+  include ::Comparable
+
+  # @return [Integer, nil] The first non-zero comparison of the
+  #   {Attributes#comparable} values of the receiver with those of OTHER (zero
+  #   if they’re all equal), or nil if the #class of the receiver doesn’t `#==`
+  #   that of OTHER
+  def <=>(other)
+    return nil unless self.class == other.class
+    v = nil
+    (attributes.comparable.any?{ |e| v = (send(e) <=> other.send(e)).nonzero? } and v) or 0
+  end
+
+  # (see #==)
+  alias eql? ==
+end

data/lib/{value → value-1.0}/version.rb

@@ -3,21 +3,20 @@
 require 'inventory-1.0'
 
 module Value
-  Version = Inventory.new(1, 1, 1){
+  Version = Inventory.new(1, 1, 2){
     def dependencies
       super + Inventory::Dependencies.new{
-        development 'inventory-rake', 1, 2, 0
+        development 'inventory-rake', 1, 4, 0
         development 'lookout', 3, 0, 0
         development 'lookout-rake', 3, 0, 0
-        development 'yard', 0, 7, 0
+        development 'yard', 0, 8, 0
+        development 'yard-heuristics', 1, 1, 0
       }
     end
 
-    def libs
-      %w'
-        value/comparable.rb
-        value/values.rb
-      '
+    def package_libs
+      %w[attributes.rb
+         comparable.rb]
     end
   }
 end

metadata

@@ -1,86 +1,278 @@
 --- !ruby/object:Gem::Specification
 name: value
 version: !ruby/object:Gem::Version
-  version: 1.1.1
-  prerelease: 
+  version: 1.1.2
 platform: ruby
 authors:
 - Nikolai Weibull
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-04 00:00:00.000000000 Z
+date: 2013-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inventory
-  requirement: &16034964 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.4'
   type: :runtime
   prerelease: false
-  version_requirements: *16034964
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: inventory-rake
-  requirement: &16034472 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.4'
   type: :development
   prerelease: false
-  version_requirements: *16034472
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: lookout
-  requirement: &16034004 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
-  version_requirements: *16034004
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: lookout-rake
-  requirement: &16049868 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
-  version_requirements: *16049868
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &16049400 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 0.8.0
   type: :development
   prerelease: false
-  version_requirements: *16049400
-description: ! "                                     Value\n\n  Value is a library
-  for defining value objects in Ruby.\n"
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: yard-heuristics
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: |2
+                                       Value
+
+    Value is a library for defining immutable value objects in Ruby.  A value
+    object is an object whose equality to other objects is determined by its
+    value, not its identity, think dates and amounts of money.  A value object
+    should also be immutable, as you don’t want the date “2013-04-22” itself to
+    change but the current date to change from “2013-04-22” to “2013-04-23”.
+    That is, you don’t want entries in a calendar for 2013-04-22 to move to
+    2013-04-23 simply because the current date changes from 2013-04-22 to
+    2013-04-23.
+
+    A value object consists of one or more attributes stored in instance
+    variables.  Value sets up an #initialize method for you that let’s you set
+    these attributes, as, value objects being immutable, this’ll be your only
+    chance to do so.  Value also adds equality checks ‹#==› and ‹#eql?› (which
+    are themselves equivalent), a ‹#hash› method, a nice ‹#inspect› method, and a
+    protected attribute reader for each attribute.  You may of course add any
+    additional methods that your value object will benefit from.
+
+    That’s basically all there’s too it.  Let’s now look at using the Value
+    library.
+
+  § Usage
+
+      You create value object class by invoking ‹#Value› inside the class
+      (module) you wish to make into a value object class.  Let’s create a class
+      that represent points on a plane:
+
+        class Point
+          Value :x, :y
+        end
+
+      A ‹Point› is thus a value object consisting of two sub-values ‹x› and ‹y›
+      (the coordinates).  Just from invoking ‹#Value›, a ‹Point› object will have
+      a constructor that takes two arguments to set instance variables ‹@x› and
+      ‹@y›, equality checks ‹#==› and ‹#eql?› (which are the same), a ‹#hash›
+      method, a nice ‹#inspect› method, and two protected attribute readers ‹#x›
+      and ‹#y›.  We can thus already creat ‹Point›s:
+
+        origo = Point.new(0, 0)
+
+      The default of making the attribute readers protected is often good
+      practice, but for a ‹Point› it probably makes sense to be able to access
+      its coordinates:
+
+        class Point
+          public(*attributes)
+        end
+
+      This’ll make all attributes of ‹Point› public.  You can of course choose to
+      only make certain attributes public:
+
+        class Point
+          public :x
+        end
+
+      Note that this public is standard Ruby functionality.  Adding a method to
+      ‹Point› is of course also possible and very much Rubyish:
+
+        class Point
+          def distance(other)
+            Math.sqrt((other.x - x)**2 + (other.y - y)**2)
+          end
+        end
+
+      For some value object classes you might want to support optional
+      attributes.  This is done by providing a default value for the attribute,
+      like so:
+
+        class Money
+          Value :amount, [:currency, :USD]
+        end
+
+      Here, the ‹currency› attribute will default to ‹:USD›.  You can create
+      ‹Money› via
+
+        dollars = Money.new(2)
+
+      but also
+
+        kronor = Money.new(2, :SEK)
+
+      All required attributes must come before any optional attributes.
+
+      Splat attributes are also supported:
+
+        class List
+          Value :'*elements'
+        end
+
+        empty = List.new
+        suits = List.new(:spades, :hearts, :diamonds, :clubs)
+
+      Splat attributes are optional.
+
+      Finally, block attributes are also available:
+
+        class Block
+          Value :'&block'
+        end
+
+        block = Block.new{ |e| e * 2 }
+
+      Block attributes are optional.
+
+      Comparison beyond ‹#==› is possible by specifingy the ‹:comparable› option
+      to ‹#Value›, listing one or more attributes that should be included in the
+      comparison:
+
+        class Vector
+          Value :a, :b, :comparable => :a
+        end
+
+      Note that equality (‹#==› and ‹#eql?›) is always defined based on all
+      attributes, regardless of arguments to ‹:comparable›.
+
+      Here we say that comparisons between ‹Vector›s should be made between the
+      values of the ‹a› attribute only.  We can also make comparisons between all
+      attributes of a value object:
+
+        class Vector
+          Value :a, :b, :comparable => true
+        end
+
+      To sum things up, let’s use all possible arguments to ‹#Value› at once:
+
+        class Method
+          Value :file, :line, [:name, 'unnamed'], :'*args', :'&block',
+                :comparable => [:file, :line]
+        end
+
+      A ‹Method› consists of file and line information, a possible name, some
+      arguments, possibly a block, and is comparable on the file and line on
+      which they appear.
+
+      Check out the {full API documentation}¹ for a more explicit description,
+      should you need it or should you want to extend it.
+
+  ¹ http://disu.se/software/value/api/
+
+  § Financing
+
+      Currently, most of my time is spent at my day job and in my rather busy
+      private life.  Please motivate me to spend time on this piece of software
+      by donating some of your money to this project.  Yeah, I realize that
+      requesting money to develop software is a bit, well, capitalistic of me.
+      But please realize that I live in a capitalistic society and I need money
+      to have other people give me the things that I need to continue living
+      under the rules of said society.  So, if you feel that this piece of
+      software has helped you out enough to warrant a reward, please PayPal a
+      donation to now@disu.se¹.  Thanks!  Your support won’t go unnoticed!
+
+  ¹ Send a donation:
+    https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=now%40disu%2ese&item_name=Nikolai%20Weibull%20Software%20Services
+
+  § Reporting Bugs
+
+      Please report any bugs that you encounter to the {issue tracker}¹.
+
+    ¹ See https://github.com/now/value/issues
+
+  § Authors
+
+      Nikolai Weibull wrote the code, the tests, the manual pages, and this
+      README.
 email: now@bitwi.se
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/value/comparable.rb
-- lib/value/values.rb
+- lib/value-1.0/attributes.rb
+- lib/value-1.0/comparable.rb
 - lib/value-1.0.rb
-- lib/value/version.rb
-- test/unit/value/comparable.rb
-- test/unit/value/values.rb
+- lib/value-1.0/version.rb
+- test/unit/value-1.0/attributes.rb
+- test/unit/value-1.0/comparable.rb
 - test/unit/value-1.0.rb
-- test/unit/value/version.rb
+- test/unit/value-1.0/version.rb
 - README
 - Rakefile
 homepage: https://github.com/now/value
@@ -91,21 +283,19 @@ rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 2.0.0
 signing_key: 
 specification_version: 4
-summary: Value is a library for defining value objects in Ruby.
+summary: Value is a library for defining immutable value objects in Ruby.
 test_files: []

data/lib/value/comparable.rb

@@ -1,13 +0,0 @@
-# -*- coding: utf-8 -*-
-
-module Value::Comparable
-  include Comparable
-
-  def <=>(other)
-    return nil unless self.class == other.class
-    v = nil
-    (values.comparable.any?{ |e| v = (send(e) <=> other.send(e)).nonzero? } and v) or 0
-  end
-
-  alias eql? ==
-end

data/lib/value/values.rb

@@ -1,44 +0,0 @@
-# -*- coding: utf-8 -*-
-
-class Value::Values
-  include Enumerable
-
-  def initialize(*values)
-    options = Hash === values.last ? values.pop : {}
-    values.pop if @block = values.last.to_s.start_with?('&') ? values.last.to_s[1..-1].to_sym : nil
-    values.pop if @splat = (values.last and values.last.to_s.start_with?('*')) ?
-    values.last.to_s[1..-1].to_sym : nil
-    required, optional = values.partition{ |e| not(Array === e) }
-    @required = required.map(&:to_sym)
-    @optional = optional.map{ |e| [e.first.to_sym, e.last] }
-    all = to_a
-    @comparable = Array === options[:comparable] ?
-      options[:comparable].each{ |e|
-        raise ArgumentError, '%p is not among comparable members %s' % [e, all.map(&:inspect).join(', ')] unless all.include?(e)
-      } :
-      all
-  end
-
-  def each
-    return enum_for(__method__) unless block_given?
-    required.each do |value|
-      yield value
-    end
-    optional.each do |value, _|
-      yield value
-    end
-    yield splat if splat
-    yield block if block
-    self
-  end
-
-  def ==(other)
-    self.class == other.class and
-      required == other.required and
-      optional == other.optional and
-      splat == other.splat and
-      block == other.block
-  end
-
-  attr_reader :required, :optional, :splat, :block, :comparable
-end