good 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in good.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Rafer Hazen
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,234 @@
+# Good 
+
+2 little things that make writing good Ruby programs a little easier.
+
+1. `Good::Value` is a class generator for simple, pleasant [Value objects](http://en.wikipedia.org/wiki/Value_object).
+
+2. `Good::Record` is a class generator for simple, pleasant [Record objects](http://en.wikipedia.org/wiki/Record_(computer_science) "Record Objects"). They're a lot like `Struct`.
+
+Both are used the same way same way, like this:
+
+```ruby
+class Person < Good::Value.new(:name, :age)
+end
+```
+
+or like this if you prefer:
+
+```ruby
+Person = Good::Value.new(:name, :age)
+end
+```
+
+Now, we can create a `Person`:
+
+```ruby
+person = Person.new(:name => "Mrs. Betty Slocombe", :age => 46)
+```
+
+and ask it about itself:
+
+```ruby
+person.name # => "Mrs. Betty Slocombe"
+person.age  # => 46 
+```
+
+`Good::Value` objects are immutable:
+
+```ruby
+person.name = "Captain Stephen Peacock" #=> NoMethodError: undefined method `name=' for ...
+```
+
+But don't worry, you can still get what you want:
+
+```ruby
+person = person.merge(:name => "Captain Stephen Peacock")
+person.name # => "Captain Stephen Peacock"
+```
+
+Most of the time immutable is good. If you don't want that though, try
+`Good::Record`:
+
+```ruby
+class Person < Good::Record.new(:name, :age)
+end
+```
+
+Now we can mutate the object:
+
+```ruby
+person = Person.new(:name => "Mrs. Betty Slocombe", :age => 46)
+person.age = 30
+person.age # => 30
+```
+
+Except for mutability `Good::Value` and `Good::Record` have the same interface.
+
+Don't forget, `Good::Value` and `Good::Record` are just regular Ruby objects,
+so they get to have methods just like everybody else:
+
+```ruby
+Person < Good::Value.new(:name, :age)
+  def introduction 
+    "My name is #{name} and I'm #{age} years old"
+  end
+end
+```
+
+Also, classes created with `Good::Value` and `Good::Record` have reasonable
+implmentations of `#==`, `#eql?` and `#hash`.
+
+## Bonus Features
+
+You can ask `Good::Value` and `Good::Record` a little about their structure:
+
+```ruby
+person.new(:name => "Miss Brahms", :age => 30)
+
+Person::MEMBERS   # => [:name, :age]
+person.members    # => [:name, :age]
+person.values     # => ["Miss Brahms", 30]
+person.attributes # => {:name => "Miss Mrahms", :age => 30}
+```
+
+You can call `Person.coerce` to coerce input to a `Person` in the follwoing
+ways:
+
+```ruby
+# from a Hash (creates a new Person)
+Person.coerce(:name => "Mr. Ernest Grainge") # => #<Person:0x007fbe9121d048 @name="Mr. Ernest Grainge"> 
+
+# from a Person (returns the input unmodified)
+person = Person.new(:name => "Mr. Cuthbert Rumbold") 
+Person.coerce(person) # => #<Person:0x007fbe920270f8 @name="Mr. Cuthbert Rumbold">
+
+# from something wrong  
+Person.coerce("WRONG") # => TypeError: Unable to coerce String into Person
+```
+
+`.coerce` is particularly useful at code boundaries. It allows clients to pass
+options as a hash if they want to, while allowing you to use the type you
+expected confidently (because blatantly incorrect values raise a `TypeError`). 
+
+## Motivation
+
+Why does the world need this?
+
+### `Good` vs Regular Ruby Objects 
+
+Creating value classes is a good idea. Properly used, they make testing easier,
+help with separation of concerns and make interfaces more apparent. In Ruby, we
+like to do stuff with as little ceremony as possible. So what's wrong with a
+regular class:
+
+```ruby
+class Person
+  attr_accessor :age, :name
+end 
+```
+
+Nothing, really. The only problem is that, in order to get an object that's
+easy to work with, you'll probably want to implement `#initialize`, `#==`,
+`#eql?` and `#hash`. This isn't really so bad, but if you want to quickly create
+a number of these classes, the boilerplate code gets heavy pretty quickly. Plus
+you'll probably do it wrong the first time (I certainly did).
+
+It's worth noting that `Good` in no way seeks to become the foundation of your
+domain model. The second a class outgrows it's `Good::Value` or `Good::Record`
+roots, by all means you should remove `Good` from the picture and rely on pure
+Ruby classes instead. `Good` helps you get started quickly by making a
+particular pattern easy, but when your classes get more mature, it's time for
+`Good` to go.
+
+### `Good` vs `Hash`
+
+In general, passing hashes around in your application is a bad idea, unless the
+data they contain is truly unstructured. Since you can't add methods to hashes
+(unless you subclass them, which is perhaps its own variety of bad idea), a
+little bit of the logic to deal with these "structured" hashes gets spread
+around a lot of places.
+
+With a hash it can also be hard to figure out exactly what it is expected to
+contain. In many cases the passing of a hash with specific expectations about
+its contents is an indication that you're missing a class.  Hopefully, prudent
+application of `Good::Value` and `Good::Record` will allow you extract that
+class more quickly, with minimal extra work.
+
+However, this is not to say that you should not use a hash at the boundary
+between client and library, or between various modules in your system. For
+example, say we've got an `Authenticator` class that takes a user's credentials:
+
+```ruby
+class Authenticator
+  def initialize(credentials)
+    username = credentials[:username]
+    password = credentials[:password]
+  end
+
+  def authentic?
+    ...
+  end
+end
+```
+
+This is a perfectly reasonable interface for a client to use:
+
+```ruby
+authenticator = Authenticator.new({
+  :username => "m.grace@gracebrothers.com",
+  :password => "rUbngS3rvd"
+})
+
+login if authenticator.authentic?
+```
+
+The following implementation maintains the same interface for the client and
+adds very little code: 
+
+```ruby
+class Authenticator
+  Credentials = Good::Value.new(:username, :password)
+
+  def initialize(credentials)
+    @credentials = Credentials.coerce(credentials)
+  end
+
+  def authentic?
+    ...
+  end
+end
+```
+
+Say now that the the Authenticator needs to pass the user's credentials to
+another component (to log the attempt, for example), we are now in the enviable
+position of having an object, with a well defined interface to pass around -
+not a hash with implicit assumptions about its contents. Further, because of
+the `.coerce` method we can now accept a hash at the boundary or a fully formed
+`Credentials` object, it makes no difference to the `Authenticator`.
+
+This evolulution seems fairly common. To solve an immediate problem, a new
+`Good::Value` class is created inside the namespace of an existing class, which
+is at first desirable because it does not inflict this abstraction externally.
+Then, as the class begins to interact with other compontents in the system,
+this previously internal class can be made external and evolved into it's own
+fully fledged domain object (perhaps shedding `Good` in the process). When you
+start with a hash, it can be harder to spot the "missing" class.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'good'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install good
+
+## Tests 
+
+    bundle && bundle exec rake
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/good.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'good'
+
+Gem::Specification.new do |spec|
+  spec.name          = "good"
+  spec.version       = Good::VERSION
+  spec.authors       = ["Rafer Hazen"]
+  spec.email         = ["rafer@ralua.com"]
+  spec.summary       = %q{Good::Value and Good::Record}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rspec", "~> 2.0 "
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+end

data/lib/good.rb

@@ -0,0 +1,71 @@
+class Good 
+  VERSION = "0.1.0"
+
+  class Value 
+    def self.new(*members, &block)
+      Good.generate(false, *members, &block)
+    end 
+  end
+
+  class Record 
+    def self.new(*members, &block)
+      Good.generate(true, *members, &block)
+    end 
+  end
+
+  def self.generate(mutable, *members, &block)
+    Class.new do
+      
+      mutable ? attr_accessor(*members) : attr_reader(*members)
+
+      const_set(:MEMBERS, members.dup.freeze)
+
+      def self.coerce(coercable)
+        case coercable
+        when self then coercable
+        when Hash then new(coercable)
+        else raise TypeError, "Unable to coerce #{coercable.class} into #{self}"
+        end
+      end
+      
+      define_method(:initialize) do |attributes={}|
+        if mutable
+          attributes.each { |k, v| send("#{k}=", v) }
+        else
+          attributes.each { |k, v| instance_variable_set(:"@#{k}", v) }  
+        end
+      end
+
+      def attributes 
+        {}.tap { |h| self.class::MEMBERS.each { |m| h[m] = send(m) } }
+      end
+
+      def members
+        self.class::MEMBERS.dup
+      end
+
+      def values
+        self.class::MEMBERS.map { |m| send(m) }
+      end
+
+      def merge(attributes={})
+        self.class.new(self.attributes.merge(attributes))
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && attributes == other.attributes
+      end
+
+      def eql?(other)
+        self == other
+      end
+      
+      def hash
+        attributes.hash
+      end
+
+      class_eval(&block) if block
+    end
+  end
+end
+

data/spec/good_spec.rb

@@ -0,0 +1,199 @@
+require "bundler/setup"
+
+shared_examples :good do
+  before do
+    class Person < described_class.new(:name, :age)
+    end
+  end
+
+  after do
+    Object.send(:remove_const, :Person)
+  end
+
+  describe "#initialize" do
+    it "accepts values via hash in the constructor" do
+      person = Person.new(:name => "Bob")
+      expect(person.name).to eq("Bob")
+    end
+
+    it "accepts string keys" do
+      person = Person.new("name" => "Bob")
+      expect(person.name).to eq("Bob")
+    end
+
+    it "allows 0 argument construction" do
+      person = Person.new
+    end
+  end
+
+  describe "#==" do
+    it "is true if all the parameters are ==" do
+      bob_1 = Person.new(:name => "Bob", :age => 50)
+      bob_2 = Person.new(:name => "Bob", :age => 50)
+      
+      expect(bob_1).to eq(bob_2)
+    end
+    
+    it "is false if any attributes are not #==" do
+      bob = Person.new(:name => "Bob", :age => 50)
+      ted = Person.new(:name => "Ted", :age => 50)
+      
+      expect(bob).not_to eq(ted)
+    end
+    
+    it "is false if the other object is not of the same class" do
+      bob = Person.new(:name => "Bob", :age => 50)
+      alien_bob = described_class.new(:name, :age).new(:name => "Bob", :age => 50)
+      
+      expect(bob).not_to eq(alien_bob)
+    end
+  end
+
+  describe "#eql" do
+    it "is true if all the parameters are ==" do
+      bob_1 = Person.new(:name => "Bob", :age => 50)
+      bob_2 = Person.new(:name => "Bob", :age => 50)
+      
+      expect(bob_1).to eql(bob_2)
+    end
+    
+    it "is false if any attributes are not #==" do
+      bob = Person.new(:name => "Bob", :age => 50)
+      ted = Person.new(:name => "Ted", :age => 50)
+      
+      expect(bob).not_to eql(ted)
+    end
+    
+    it "is false if the other object is not of the same class" do
+      bob = Person.new(:name => "Bob", :age => 50)
+      alien_bob = Struct.new(:name, :age).new("Bob", 50)
+      
+      expect(bob).not_to eql(alien_bob)
+    end
+  end
+  
+  describe "#hash" do
+    it "is stable" do
+      bob_1 = Person.new(:name => "Bob")
+      bob_2 = Person.new(:name => "Bob")
+      
+      expect(bob_1.hash).to eq(bob_2.hash)
+    end
+    
+    it "varies with the parameters" do
+      bob = Person.new(:name => "Bob", :age => 50)
+      ted = Person.new(:name => "Ted", :age => 50)
+      
+      expect(bob.hash).not_to eql(ted.hash)
+    end
+  end
+  
+  describe "::MEMBERS" do
+    it "is the list of member variables" do
+      expect(Person::MEMBERS).to eq([:name, :age])
+    end
+    
+    it "is frozen" do
+      expect { Person::MEMBERS << :height }.to raise_error(/can't modify frozen/)
+    end
+  end
+ 
+  describe "#members" do
+    it "is the list of member variables" do
+      person = Person.new
+      expect(person.members).to eq([:name, :age])
+    end
+
+    it "is modifiable without affecting the original members" do
+      person = Person.new
+      person.members << :height
+      expect(person.members).to eq([:name, :age])
+    end
+  end
+
+  describe "#values" do
+    it "is the list of values (in the same order as the #members)" do
+      person = Person.new(:age => 50, :name => "BOB")
+      expect(person.values).to eq(["BOB", 50])
+    end
+  end
+
+  describe "#attributes" do
+    it "is a hash of the attributes (with symbol keys)" do
+      person = Person.new(:name => "Bob", :age => 50)
+      expect(person.attributes).to eq(:name => "Bob", :age => 50)
+    end
+  end
+
+  describe "#merge" do
+    it "returns an object with the given properties modified" do
+      young = Person.new(:name => "Bob", :age => 50)
+      old = young.merge(:age => 51)
+
+      expect(old.name).to eq("Bob")
+      expect(old.age).to eq(51)
+    end
+
+    it "does not mutate the old object" do
+      person = Person.new(:name => "Bob", :age => 50)
+      person.merge(:age => 51)
+
+      expect(person.age).to eq(50)
+    end
+
+    it "accepts 0 arguments" do
+      person = Person.new
+      expect(person.merge).not_to be(person)
+    end
+  end
+
+  describe ".coerce" do
+    it "returns the input unmodified if it is already an instance of the struct" do
+      person = Person.new
+      expect(Person.coerce(person)).to be(person)
+    end
+    
+    it "initializes a new instance if the input is a hash" do
+      person = Person.coerce({:name => "Bob"})
+      expect(person).to eq(Person.new(:name => "Bob"))
+    end
+    
+    it "raises a TypeError otherwise" do
+      expect { Person.coerce("15 lbs of squirrel fur") }.to raise_error(TypeError)
+    end
+  end
+  
+  describe "block construction" do
+    let(:car_klass) do
+      described_class.new(:wheels) do
+        def drive
+          "Driving with all #{wheels} wheels!"
+        end
+      end
+    end
+    
+    it "allows definition of methods" do
+      car = car_klass.new(:wheels => 4)
+      expect(car.drive).to eq("Driving with all 4 wheels!")
+    end
+  end
+end
+
+describe Good::Value do
+  include_examples(:good)
+
+  it "is immutable" do
+    person = Person.new
+    expect { person.name = "Bob" }.to raise_error(NoMethodError) 
+  end
+end
+
+describe Good::Record do
+  include_examples(:good)
+
+  it "is mutable" do
+    person = Person.new
+    expect { person.name = "Bob" }.to change { person.name }.to("Bob")
+  end
+end
+

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: good
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Rafer Hazen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- rafer@ralua.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- good.gemspec
+- lib/good.rb
+- spec/good_spec.rb
+homepage: ''
+licenses:
+- MIT
+post_install_message: 
+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.23
+signing_key: 
+specification_version: 3
+summary: Good::Value and Good::Record
+test_files:
+- spec/good_spec.rb