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 Points:

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 Vectors 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.

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!

Reporting Bugs

Please report any bugs that you encounter to the issue tracker.

Authors

Nikolai Weibull wrote the code, the tests, the manual pages, and this README.

Licensing

Value is free software: you may redistribute it and/or modify it under the terms of the GNU Lesser General Public License, version 3 or later, as published by the Free Software Foundation.