valuable 0.9.2 → 0.9.3

data/.gitignore

@@ -7,3 +7,4 @@
 pkg
 vendor
 Gemfile.lock
+*.gem

data/Gemfile

@@ -3,6 +3,8 @@ source 'http://rubygems.org'
 # Specify your gem's dependencies in sketch.gemspec
 gemspec
 
+gem 'rake'
+
 group :test do
   gem 'test-unit'
   gem 'mocha'

data/README.markdown

@@ -1,9 +1,14 @@
 Introducing Valuable
 ====================
 
-Valuable enables quick modeling... it's attr_accessor on steroids.  For all those times you wanted to use OO to model something but it seemed like too much of a pain, try Valuable. Its simple interface allows you to model without hassles, so you can get on with the logic specific to your application.
+Valuable enables quick modeling... it's attr_accessor on steroids.  Its simple interface allows you to build, change and discard models without hassles, so you can get on with the logic specific to your application.
 
-Frequent Uses:
+Valuable provides DRY decoration like attr_accessor, but includes default values and other formatting (like, "2" => 2), and a constructor that accepts an attributes hash. It provides a class-level list of attributes, an instance-level attributes hash, and more.
+
+Tested with "Rubinius":http://www.rubini.us, 1.8.7, 1.9.1, 1.9.2, 1.9.3
+
+Frequent Uses
+-------------
 
 **pre-refactor modeling** to model a class you want to abstract but know would be a pain... as in, "I would love to pull Appointment out of this WorkOrder class, but since that isn't going to happen soon, let me quickly create WorkOrder.appointments... I can then create Appointment\#to\_s, appointment.end_time, appointment.duration, etc. I can use that to facilitate emitting XML or doing something with views, rather than polluting WorkOrder with appointment-related logic." 
 
@@ -11,10 +16,8 @@ Frequent Uses:
 
 **creating models from non-standard data sources** to keep data from non-standard data sources in memory during an import or to render data from an API call.
 
-Valuable provides DRY decoration like attr_accessor, but includes default values and other formatting (like, "2" => 2), and a constructor that accepts an attributes hash. It provides a class-level list of attributes, an instance-level attributes hash, and more.
-
 Type Casting in Ruby? You must be crazy...
--------------------------------------------------------------
+------------------------------------------
 Yeah, I get that alot. I mean, about type casting. I'm not writing
 C# over here. Rails does it, they just don't call it type casting,
 so no one complains when they pass in "2" as a parameter and mysteriously
@@ -48,23 +51,11 @@ you'll end up with this:
       >> p.phone_number.class
       => PhoneNumber
 
-      "Yeah, I could have just done that myself."
-      "Right, but now you don't have to."
-
-Default Values
---------------
-Default values are used when no value is provided to the constructor. If the value nil is provided, nil will be used instead of the default.
-
-When a default value and a klass are specified, the default value will NOT be cast to type klass -- you must do it.
-
-If a value having a default is set to null after it is constructed, it will NOT be set to the default.
-
-If there is no default value, the result will be nil, EVEN if type casting is provided. Thus, a field typically cast as an Integer can be nil. See calculation of average.
-
-Examples
--------
+"Yeah, I could have just done that myself."
+"Right, but now you don't have to."
 
-_basic syntax_
+Basic Syntax
+------------
 
       class Fruit < Valuable
         has_value :name
@@ -83,6 +74,16 @@ _constructor accepts an attributes hash_
 
 _default values_
 
+Default values are used when no value is provided to the constructor. If the value nil is provided, nil will be used instead of the default. Default values are populated on instanciation.
+
+When a default value and a klass are specified, the default value will NOT be cast to type klass -- you must do it.
+
+If a value having a default is set to null after it is constructed, it will NOT be set to the default.
+
+If there is no default value, the result will be nil, EVEN if type casting is provided. Thus, a field typically cast as an Integer can be nil. See calculation of average.
+
+The :default option will accept a lambda and call it on instanciation.
+
       class Developer
         has_value :name
         has_value :nickname, :default => 'mort'
@@ -101,7 +102,25 @@ _setting a value to nil overrides the default._
       >> Developer.new(:name => 'KDD', :nickname => nil).nickname
       => nil
 
-_formatting aka light-weight type-casting_
+_aliases_
+
+      # This example requires active_support because of Hash.from_xml
+
+      class Software < Valuable
+        has_value :name, :alias => 'Title'
+      end
+
+      >> xml = '<software><Title>Windows XP</Title></software>'
+
+      >> xp = Software.new(Hash.from_xml(xml)['software'])
+
+      >> xp.name
+      => "Windows XP"
+
+
+Formatting Input
+----------------
+_aka light-weight type-casting_
 
       class BaseballPlayer < Valuable
 
@@ -125,11 +144,11 @@ _formatting aka light-weight type-casting_
       # - integer
       # - decimal ( casts to BigDecimal... NOTE: nil remains nil, not 0 as in nil.to_i )
       # - string
-      # - boolean ( NOTE: '0' casts to FALSE... I would be fascinated to know when this is not the correct behavior. )
+      # - boolean ( NOTE: '0' casts to FALSE... This isn't intuitive, but I would be fascinated to know when this is not the correct behavior. )
       # - or any class ( formats as SomeClass.new( ) unless value.is_a?( SomeClass ) )
 
-
-_collections_
+Collections
+-----------
 
       class MailingList < Valuable
         has_collection :emails
@@ -174,78 +193,93 @@ _formatting collections_
       >> t.players.last
       => #<Player:0x7fa51ea6a9f8 @attributes={:salary=>"435800", :first_name=>"Travis", :last_name=>"Snider"}>
 
-_aliases_
-
-      # This example requires active_support because of Hash.from_xml
+parse_with parses each item in a collection...
 
-      class Software < Valuable
-        has_value :name, :alias => 'Title'
+      class Roster < Valuable
+        has_collection :players, :klass => Player, :parse_with => :find_by_name
       end
 
-      >> xml = '<software><Title>Windows XP</Title></software>'
+Advanced Defaults
+-----------------
 
-      >> xp = Software.new(Hash.from_xml(xml)['software'])
+      class Borg < Valuable
+        cattr_accessor :count
+        has_value :position, :default => lambda { Borg.count += 1 }
+      
+        def designation
+          "#{self.position} of #{Borg.count}"
+        end
+      end
 
-      >> xp.name
-      => "Windows XP"
+      >> Borg.count = 6
+      >> seven = Borg.new
+      >> Borg.count = 9
+      >> seven.designation
+      => '7 of 9'
 
+Advanced Input Parsing
+----------------------
 
-_as a presenter in Rails_
+Sometimes, .to_s isn't enough... the architypical example being Date.parse(value). In these cases, you can specify what class-level method should be used to process the input.
 
-      class CalenderPresenter < Valuable
-        has_value :month, :klass => Integer, :default => Time.now.month
-        has_value :year, :klass => Integer, :default => Time.now.year
+      require 'date'
 
-        def start_date
-          Date.civil( year, month, 1)
-        end
+      class Person < Valuable
+        has_value :date_of_birth, :alias => :dob, :klass => Date, :parse_with => :parse
 
-        def end_date
-          Date.civil( year, month, -1) #strange I know
+        def age_in_days
+          Date.today - dob
         end
+      end
 
-        def events
-          Event.find(:all, :conditions => event_conditions)
-        end
+      >> sammy = Person.new(:dob => '2012-02-17')
+      >> sammy.age_in_days
+      => Rational(8, 1)
 
-        def event_conditions
-          ['starts_at between ? and ?', start_date, end_date]
-        end
-      end
+use it to load associated data from an exising set...
 
-this class might appear in a controller like this:
+      class Planet < Valuable
+        has_value :name
+        has_value :spaceport
 
-      class CalendarController < ApplicationController
-        def show
-          @presenter = CalendarPresenter.new(params[:calendar])
+        def Planet.list
+          @list ||= []
         end
-      end
 
-but it's easier to understand like this:
+        def Planet.find_by_name( needle )
+          list.find{|i| i.name == needle }
+        end
+      end
 
-      >> @presenter = CalendarPresenter.new({}) # first pageload
+      class Spaceship < Valuable
+        has_value :name
+        has_value :home, :klass => Planet, :parse_with => :find_by_name
+      end
 
-      >> @presenter.start_date
-      => Tue, 01 Dec 2009
+      Planet.list << Planet.new(:name => 'Earth', :spaceport => 'KSC')
+      Planet.list << Planet.new(:name => 'Mars', :spaceport => 'Olympus Mons')
 
-      >> @presenter.end_date
-      => Thu, 31 Dec 2009
+      >> vger = Spaceship.new( :name => "V'ger", :home => 'Earth')
+      >> vger.home.spaceport
+      => 'KSC'
 
-      >> # User selects some other month and year; the next request looks like...
+Parse via lambda:
 
-      >> @presenter = CalendarPresenter.new({:month => '2', :year => '2002'})
+      require 'active_support'
 
-      >> @presenter.start_date
-      => Fri, 01 Feb 2002
+      class Movie < Valuable
+        has_value :title, :parse_with => lambda{|x| x.titleize}
+      end
 
-      >> @presenter.end_date
-      => Thu, 28 Feb 2002
+      >> best_movie_ever = Movie.new(:title => 'the usual suspects')
 
-      ...
+      >> best_movie_ever.title
+      => "The Usual Suspects"
 
-So, if you're reading this, you're probably thinking, "I could have done that!" Yes, it's true. I'll happily agree that it's a relatively simple tool if you'll agree that it lets you model a calendar with an intuitive syntax, prevents you from writing yet another obvious constructor, and allows you to keep your brain focused on your app.
+More about Attributes
+---------------------
 
-_you can access the attributes via the attributes hash. Only default and specified attributes will have entries here._
+Access the attributes via the attributes hash. Only default and specified attributes will have entries here.
 
       class Person < Valuable
         has_value :name
@@ -264,9 +298,10 @@ _you can access the attributes via the attributes hash. Only default and specifi
       >> elvis.ssn
       => nil
 
-_also, you can get a list of all the defined attributes from the class_
+Get a list of all the defined attributes from the class:
 
       >> Person.attributes
       => [:name, :is_developer, :ssn]
 
+It's a relatively simple tool that lets you create models with a (hopefully) intuitive syntax, prevents you from writing yet another obvious constructor, and allows you to keep your brain focused on your app.
 

data/examples/person.rb

@@ -0,0 +1,8 @@
+require File.dirname(__FILE__) + '/phone_number'
+
+class Person < Valuable
+  has_value :name
+  has_value :age, :klass => :integer
+  has_value :phone_number, :klass => PhoneNumber
+end
+

data/examples/rails_presenter.rb

@@ -0,0 +1,51 @@
+#  This class might appear in a controller like this:
+#  
+#  class CalendarController < ApplicationController
+#    def show
+#      @presenter = CalendarPresenter.new(params[:calendar])
+#    end
+#  end
+#
+#  but in documentation, makes more sense this way :)  
+#  
+#  >> @presenter = CalendarPresenter.new # first pageload
+#  
+#  >> @presenter.start_date
+#  => Tue, 01 Dec 2009
+#  
+#  >> @presenter.end_date
+#  => Thu, 31 Dec 2009
+#  
+#  >> # User selects some other month and year; the next request looks like...
+#  
+#  >> @presenter = CalendarPresenter.new({:month => '2', :year => '2002'})
+#  
+#  >> @presenter.start_date
+#  => Fri, 01 Feb 2002
+#  
+#  >> @presenter.end_date
+#  => Thu, 28 Feb 2002
+#  
+#  ...
+#  
+class CalenderPresenter < Valuable
+  has_value :month, :klass => Integer, :default => Time.now.month
+  has_value :year, :klass => Integer, :default => Time.now.year
+
+  def start_date
+    Date.civil( year, month, 1)
+  end
+
+  def end_date
+    Date.civil( year, month, -1) #strange I know
+  end
+
+  def events
+    Event.find(:all, :conditions => event_conditions)
+  end
+
+  def event_conditions
+    ['starts_at between ? and ?', start_date, end_date]
+  end
+end
+

data/lib/valuable.rb

@@ -19,29 +19,39 @@
 #   
 class Valuable
 
-  # Returns a Hash representing all known values. Values are set three ways:
+  # Returns a Hash representing all known values. Values are set four ways:
   # 
-  #   (1) a default value
+  #   (1) Default values are set on instanciation, ie Person.new
   #   (2) they were passed to the constructor
   #          Bus.new(:color => 'green')
   #   (3) they were set via their namesake setter or alias setter
   #          bus.color = 'green'
   #          bus.Passengers = ['bill', 'steve']
-  #          
+  #   (4) the write_attributes(key, value) method
+  # 
   # Values that have not been set and have no default not appear in this
   # collection. Their namesake attribute methods will respond with nil.
-  # Always use symbols to access these values.
-  # 
+  # Always use symbols to access these values, ie:
+  #   Person.attributes[:color]
+  # not
+  #   Person.attributes['color']
+  #
+  # basic usage: 
   #   >> bus = Bus.new(:number => 16) # color has default value 'yellow'
   #   >> bus.attributes
   #   => {:color => 'yellow', :number => 16}
   def attributes
-    @attributes ||= Valuable::Utils.deep_duplicate_of(self.class.defaults) 
+    @attributes
+  end
+
+  def initialize_attributes
+    @attributes ||= Valuable::Utils.initial_copy_of_attributes(self.class.defaults) 
   end
 
   # accepts an optional hash that will be used to populate the 
   # predefined attributes for this class.
   def initialize(atts = nil)
+    initialize_attributes
     self.update_attributes(atts || {})
   end
 

data/lib/valuable/utils.rb

@@ -15,6 +15,20 @@ module Valuable::Utils
       end
     end
 
+    def initial_copy_of_attributes(atts)
+      out = {}
+      atts.each do |name, value|
+        case value
+        when Proc
+          out[name] = value.call
+        else
+          out[name] = deep_duplicate_of( value )
+        end
+      end
+
+      out
+    end
+
     def deep_duplicate_of(value)
       Marshal.load(Marshal.dump(value))
     end
@@ -25,7 +39,11 @@ module Valuable::Utils
       case klass
       when NilClass
 
-        value
+        if Proc === attributes[name][:parse_with]
+          attributes[name][:parse_with].call(value)
+        else
+          value
+        end
 
       when :collection
         if( value.kind_of?(Array) )
@@ -77,7 +95,7 @@ module Valuable::Utils
         elsif value.is_a? klass
           value
         else
-          klass.new(value)
+          klass.send( attributes[name][:parse_with] || :new, value)
         end
 
       end
@@ -89,7 +107,7 @@ module Valuable::Utils
     end
 
     def known_options
-     [:klass, :default, :negative, :alias]
+      [:klass, :default, :negative, :alias, :parse_with]
     end
 
     # this helper raises an exception if the options passed to has_value
@@ -101,6 +119,8 @@ module Valuable::Utils
       raise ArgumentError, "has_value did not know how to respond to option(s) #{invalid_options.join(', ')}. Valid (optional) arguments are: #{known_options.join(', ')}" unless invalid_options.empty?    
 
       raise ArgumentError, "#{class_name} doesn't know how to format #{attribute} with :klass => #{options[:klass].inspect}" unless klass_options.any?{|klass| klass === options[:klass]}
+
+      raise( ArgumentError, "#{class_name} can't promise to return a(n) #{options[:klass]} when using :parse_with" ) if options[:klass].is_a?( Symbol ) && options[:parse_with]
     end
   end
 end

data/test/default_values_from_anon_methods.rb

@@ -0,0 +1,29 @@
+$: << File.expand_path(File.dirname(__FILE__) + '/../lib')
+
+require 'rubygems'
+require 'test/unit'
+require 'valuable.rb'
+
+class Borg < Valuable
+  class << self
+    attr_accessor :count
+  end
+  has_value :position, :default => lambda { Borg.count += 1 } 
+  has_value :name
+
+  def designation
+    "#{self.position} of #{Borg.count}"
+  end
+end
+
+class DefaultValueFromAnonMethodsTest < Test::Unit::TestCase
+
+  def test_that_children_inherit_their_parents_attributes
+    Borg.count = 6
+    seven = Borg.new
+    Borg.count = 9
+    assert_equal '7 of 9', seven.designation  
+  end	  
+
+end
+

data/test/parse_with_test.rb

@@ -0,0 +1,47 @@
+$: << File.expand_path(File.dirname(__FILE__) + '/../lib')
+
+require 'test/unit'
+require 'valuable.rb'
+require 'mocha'
+
+class Person < Valuable
+  has_value :first_name
+  has_value :last_name
+
+  def Person.load( name )
+    f, l = name.split(' ') # trivial case
+    new(:first_name => f, :last_name => l)
+  end
+end
+
+class RailsApp < Valuable
+  has_value :tech_lead, :klass => Person, :parse_with => :load
+  has_collection :devs, :klass => Person, :parse_with => :load
+  has_value :name, :parse_with => lambda{|x| x == 'IA' ? 'Information Architecture' : x}
+end
+
+class ParseWithTest < Test::Unit::TestCase
+ 
+  def test_that_parse_with_calls_target_classes_parse_method
+    ia = RailsApp.new(:tech_lead => 'Adam Dalton')
+    assert_equal 'Adam', ia.tech_lead.first_name
+  end
+
+  def test_that_collections_are_parsed
+    ia = RailsApp.new(:devs => ['Dennis Camp', 'Richard Hoblitzell', 'Paul Kuracz', 'Magda Lueiro', 'George Meyer', 'David Moyer', 'Bill Snoddy'])
+    expected = ['Dennis', 'Richard', 'Paul', 'Magda', 'George', 'David', 'Bill']
+    actual = ia.devs.map(&:first_name)
+    assert_equal expected, actual
+  end
+
+  def test_that_lambdas_can_be_used_as_parsers
+    assert_equal 'Information Architecture', RailsApp.new(:name => 'IA').name
+  end
+
+  def test_that_it_raises_an_error_when_passed_a_class_and_a_proc
+    animal = Class.new(Valuable)
+    assert_raises ArgumentError, "Class can't promise to return a(n) :integer when using the option :parse_with" do
+      animal.has_value :invalid, :klass => :integer, :parse_with => :method
+    end
+  end
+end

data/todo.txt

@@ -12,17 +12,6 @@ class SomeSearchThing < Valuable
 
 end
 
-class Datum < Valuable
-  has_index :by_name
-  has_list  :calculations
-end
--or-
-class Datum < Valuable
-  lists :calculations
-  indexes :by_name
-end
-
-
 BEST PRACTICES DOC
 
 When creating a searcher:
@@ -78,6 +67,18 @@ like this:
   end
 
 
-what about has_value :number, :construct => 'Decimal#parse'
+
+:klass => :decimal
+- When is decimal available? Only load then.
+- If calling :decimal and it hasn't loaded, error
+
+
+
+class Change < Decimal
+  extend Valuable::whatever or
+  extend Valuable
+
+  ...
+end
 
 - do a better job with method_missing 

data/valuable.version

@@ -1 +1 @@
-0.9.2
+0.9.3

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: valuable
 version: !ruby/object:Gem::Version 
-  hash: 63
+  hash: 61
   prerelease: 
   segments: 
   - 0
   - 9
-  - 2
-  version: 0.9.2
+  - 3
+  version: 0.9.3
 platform: ruby
 authors: 
 - Johnathon Wright
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-27 00:00:00 -05:00
+date: 2012-02-25 00:00:00 -06:00
 default_executable: 
 dependencies: []
 
@@ -33,13 +33,17 @@ files:
 - README.markdown
 - Rakefile
 - examples/baseball.rb
+- examples/person.rb
 - examples/phone_number.rb
+- examples/rails_presenter.rb
 - lib/valuable.rb
 - lib/valuable/utils.rb
 - test/alias_test.rb
 - test/bad_attributes_test.rb
+- test/default_values_from_anon_methods.rb
 - test/deprecated_test.rb
 - test/inheritance_test.rb
+- test/parse_with_test.rb
 - test/typical_test.rb
 - test/valuable_test.rb
 - test/write_and_read_attribute_test.rb
@@ -76,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.4.2
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: attr_accessor on steroids with defaults, default constructor, and attribute formatting.