charisma 0.2.0 → 0.3.0

data/.document

@@ -1,11 +1,11 @@
-# .document is used by rdoc and yard to know how to generate documentation 
-# for example, it can be used to control how rdoc gets built when you do `gem install foo`
-
-README.rdoc
-lib/**/*.rb
-bin/*
-
-# Files below this - are treated as 'extra files', and aren't parsed for ruby code
-- 
-features/**/*.feature
-LICENSE
+# .document is used by rdoc and yard to know how to generate documentation 
+# for example, it can be used to control how rdoc gets built when you do `gem install foo`
+
+README.rdoc
+lib/**/*.rb
+bin/*
+
+# Files below this - are treated as 'extra files', and aren't parsed for ruby code
+- 
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -1,40 +1,40 @@
-*.gem
-.bundle
-Gemfile.lock
-pkg/*
-# rcov generated
-coverage
-
-# rdoc generated
-rdoc
-
-# yard generated
-doc
-.yardoc
-
-# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
-#
-# * Create a file at ~/.gitignore
-# * Include files you want ignored
-# * Run: git config --global core.excludesfile ~/.gitignore
-#
-# After doing this, these files will be ignored in all your git projects,
-# saving you from having to 'pollute' every project you touch with them
-#
-# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
-#
-# For MacOS:
-#
-#.DS_Store
-#
-# For TextMate
-#*.tmproj
-#tmtags
-#
-# For emacs:
-*~
-#\#*
-#.\#*
-#
-# For vim:
-#*.swp
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+# rcov generated
+coverage
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+#.DS_Store
+#
+# For TextMate
+#*.tmproj
+#tmtags
+#
+# For emacs:
+*~
+#\#*
+#.\#*
+#
+# For vim:
+#*.swp

data/LICENSE

@@ -1,20 +1,20 @@
-Copyright (c) 2011 Andy Rossmeissl
-
-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.
+Copyright (c) 2011 Andy Rossmeissl
+
+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.markdown

@@ -0,0 +1,152 @@
+# Charisma
+
+Charisma provides a *superficiality framework* for Ruby objects. You can use it to:
+
+* Provide a *curation strategy* for your class that defines which of its attributes are *superfically important.*
+* Define *metadata* on these characteristics, such as measurements and units.
+* Facilitate *appropriate presentation* of these characteristics (i.e., intelligent `#to_s`).
+
+Charisma is all about how your objects look to the outside world. We use it within [CM1](http://carbon.brighterplanet.com) to facilitate the characterization of the flights, cars, etc. that we're performing carbon calculations on.
+
+See also: [RDocs](http://rubydoc.info/github/brighterplanet/charisma/master/frames).
+
+## Example
+
+``` ruby
+class Spaceship < SuperModel::Base # or ActiveRecord, or whatever
+  attributes :window_count, :name, :size, :weight
+  belongs_to :make, :class_name => 'SpaceshipMake', :primary_key => 'name'
+  belongs_to :fuel, :class_name => 'SpaceshipFuel', :primary_key => 'name'
+  belongs_to :destination, :class_name => 'Planet', :primary_key => 'name'
+  
+  include Charisma
+  characterize do
+    has :make, :display_with => :name
+    has :fuel
+    has :window_count do |window_count|
+      "#{window_count} windows"
+    end
+    has :size, :measures => :length # uses Charisma::Measurements::Length
+    has :weight, :measures => RelativeAstronomicMass
+    has :name
+    has :destination
+  end
+end
+```
+``` irb
+irb(main):001:0> amaroq = Spaceship.new :size => 100, :window_count => 3, :make => SpaceshipMake.create(:name => 'Ford')
+ => #<Spaceship:0xacd9ac4 ...>
+irb(main):002:0> amaroq.characteristics[:size].to_s
+ => "100 m"
+irb(main):003:0> amaroq.characteristics[:size].feet
+ => 328.08399000000003
+irb(main):004:0> amaroq.characteristics[:window_count].to_s
+ => "3 windows"
+irb(main):005:0> amaroq.characteristics[:make].to_s
+ => "Ford"
+```
+
+## Characterizing your class
+
+Charisma uses a DSL within a `characterize` block to define your class's attribute curation strategy:
+
+``` ruby
+class Foo
+  # ...
+  include Charisma
+  characterize do
+    # Characteristics go here
+  end
+end
+```
+
+### Simple (scalar) characteristics
+
+How do you define characteristics? The simplest way looks like this:
+
+``` ruby
+characterize do
+  has :color
+end
+```
+
+Charisma will obtain the `color` characteristic for an instance by calling its `#color` method.
+
+``` irb
+irb(main):001:0> Foo.new(:color => 'Blue').characteristics[:color].to_s
+ => Blue
+```
+
+### Fancy characteristics
+
+Of course, this isn't extremely useful. Things get more interesting when you want the characteristic to present itself usefully:
+
+``` ruby
+characterize do
+  has :color do |color|
+    "##{Color.find_by_name(color).hex}"
+  end
+end
+```
+``` irb
+irb(main):001:0> Foo.new(:color => 'black').characteristics[:color].to_s
+ => #000000
+```
+
+Or perhaps you're using an association:
+
+``` ruby
+characterize do
+  has :color, :display_with => :hex # If unspecified, Charisma will try #as_characteristic and #to_s on the associated object, in that order 
+end
+```
+``` irb
+irb(main):001:0> Foo.new(:color => Color.find_by_name('black')).characteristics[:color].to_s
+ => #000000
+```
+
+### Measured characteristics
+
+Some characteristics represent measured values like *length*. You can specify that like so:
+
+``` ruby
+characterize do
+  has :size, :measures => Length 
+end
+```
+``` ruby
+class Length < Charisma::Measurement # Don't need to inherit if you want to DIY
+  units :meters => 'm' 
+end
+```
+``` irb
+irb(main):001:0> Foo.new(:size => 10).characteristics[:size].to_s
+ => 10 m
+```
+
+Charisma has some [convenient measurements](https://github.com/brighterplanet/charisma/tree/master/lib/charisma/measurement) baked in:
+
+``` ruby
+characterize do
+  has :size, :measures => Charisma::Measurement::Length 
+end
+```
+
+Built-in measurements can be referenced with a shortcut:
+
+``` ruby
+characterize do
+  has :size, :measures => :length 
+end
+```
+
+Charisma uses [Conversions](https://github.com/seamusabshere/conversions) to provide useful unit conversion methods:
+
+``` irb
+irb(main):001:0> Foo.new(:size => 10).characteristics[:size].feet
+ => 32.808399000000003
+```
+
+## Copyright
+
+Copyright (c) 2011 Andy Rossmeissl. See LICENSE for details.

data/Rakefile

@@ -1,46 +1,46 @@
-require 'rubygems'
-
-begin
-  require 'bundler'
-rescue LoadError
-  $stderr.puts "You must install bundler - run `gem install bundler`"
-end
-
-begin
-  Bundler.setup
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
-
-require 'bueller'
-Bueller::Tasks.new
-
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-end
-
-require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-end
-
-task :default => :test
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.main = 'README.rdoc'
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "charisma #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'rubygems'
+
+begin
+  require 'bundler'
+rescue LoadError
+  $stderr.puts "You must install bundler - run `gem install bundler`"
+end
+
+begin
+  Bundler.setup
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'bueller'
+Bueller::Tasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.main = 'README.rdoc'
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "charisma #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/charisma.gemspec

@@ -1,38 +1,38 @@
-$:.push File.expand_path("../lib", __FILE__)
-require 'charisma/version'
-
-Gem::Specification.new do |s|
-  s.name = 'charisma'
-  s.version = Charisma::VERSION
-  s.platform = Gem::Platform::RUBY
-  s.date = "2011-05-11"
-  s.authors = ['Andy Rossmeissl', 'Seamus Abshere']
-  s.email = 'andy@rossmeissl.net'
-  s.homepage = 'http://github.com/brighterplanet/charisma'
-  s.summary = %Q{Curate your rich Ruby objects' attributes}
-  s.description = %Q{Define strategies for accessing and displaying a subset of your classes' attributes}
-  s.extra_rdoc_files = [
-    'LICENSE',
-    'README.rdoc',
-  ]
-
-  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.7')
-  s.rubygems_version = '1.3.7'
-  s.specification_version = 3
-
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ['lib']
-  
-  s.add_dependency 'activesupport'
-  s.add_dependency 'blockenspiel'
-  s.add_dependency 'conversions'
-
-  s.add_development_dependency 'bundler'
-  s.add_development_dependency 'bueller'
-  s.add_development_dependency 'rake'
-  s.add_development_dependency 'rcov'
-  s.add_development_dependency 'supermodel'
-end
-
+$:.push File.expand_path("../lib", __FILE__)
+require 'charisma/version'
+
+Gem::Specification.new do |s|
+  s.name = 'charisma'
+  s.version = Charisma::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.date = "2011-06-02"
+  s.authors = ['Andy Rossmeissl', 'Seamus Abshere']
+  s.email = 'andy@rossmeissl.net'
+  s.homepage = 'http://github.com/brighterplanet/charisma'
+  s.summary = %Q{Curate your rich Ruby objects' attributes}
+  s.description = %Q{Define strategies for accessing and displaying a subset of your classes' attributes}
+  s.extra_rdoc_files = [
+    'LICENSE',
+    'README.markdown',
+  ]
+
+  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.7')
+  s.rubygems_version = '1.3.7'
+  s.specification_version = 3
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+  
+  s.add_dependency 'activesupport'
+  s.add_dependency 'blockenspiel'
+  s.add_dependency 'conversions'
+
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'bueller'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rcov'
+  s.add_development_dependency 'supermodel'
+end
+

data/lib/charisma.rb

@@ -21,9 +21,19 @@ require 'charisma/curator'
 require 'charisma/curator/curation'
 require 'charisma/number_helper'
 
+# Charisma provides a <em>superficiality framework</em> for Ruby objects.
+#
+# You can use it to:
+#
+#  * Provide a <em>curation strategy</em> for your class that defines which of its attributes are <em>superfically important.</em>
+#  * Define <em>metadata</em> on these characteristics, such as measurements and units.
+#  * Facilitate <em>appropriate presentation</em> of these characteristics (i.e., intelligent <tt>#to_s</tt>).
 module Charisma
+  # Prepare a class for characterization with <tt>include Charisma</tt>.
   def self.included(base)
     base.send :include, Base
     base.extend Base::ClassMethods
   end
 end
+
+Conversions.register :meters, :feet, 3.2808399

data/lib/charisma/base.rb

@@ -1,9 +1,12 @@
 module Charisma
+  # This module is included in characterized objects (via <tt>include Charisma</tt> on the class)
   module Base
+    # The accessor for the object's characteristics, which can be treated more or less like a Hash.'
     def characteristics
       @curator ||= Curator.new(self)
     end
   end
   
+  # Poorly-defined measurements raise this error.
   class InvalidMeasurementError < StandardError; end
 end

data/lib/charisma/base/class_methods.rb

@@ -1,10 +1,19 @@
 module Charisma
   module Base
+    # Methods included on the characterized class
     module ClassMethods
+      # Establishes a <tt>@@characterization</tt> class variable along with a <tt>#characterization</tt> accessor on the class.
+      #
+      # @see Charisma::Characterizaion
       def self.extended(base)
         base.send :class_variable_set, :@@characterization, Characterization.new
         base.send :cattr_reader, :characterization, :instance_reader => false
       end
+      
+      # Define a characterization on the class.
+      #
+      # The definition occurs within the block, using <tt>Charisma::Characterization#has</tt> as a DSL.
+      # @see Charisma::Characterization#has
       def characterize(&blk)
         Blockenspiel.invoke(blk, characterization) if block_given?
       end

data/lib/charisma/characteristic.rb

@@ -1,7 +1,33 @@
 module Charisma
+  # Stores information about a characteristic.
+  #
+  # Typically these are defined with <tt>Charisma::Characterization#has</tt> in a <tt>characterize do . . . end</tt> block.
+  # @see Charisma::Base::ClassMethods#characterize
+  # @see Charisma::Characterization#has
   class Characteristic
-    attr_reader :name, :proc, :accessor, :measurement
+    # The characteristic's name
+    attr_reader :name
     
+    # A proc, if defined, that specifies how the characteristic should be displayed
+    attr_reader :proc
+    
+    # A method that should be called on the characteristic in order to display it properly
+    attr_reader :accessor
+    
+    # Specifies that the characteristic should be treated as a measured quantity
+    attr_reader :measurement
+    
+    # Create a characteristic.
+    #
+    # Typically this is done via <tt>Charisma::Characterization#has</tt> within a <tt>characterize do . . . end</tt> block.
+    # @param [Symbol] name The name of the characteristic. The method with this name will be called on the characterized object to retrieve its raw value.
+    # @param [Hash] options The options hash.
+    # @option [Symbol] display_with A symbol that gets sent as a method on the characteristic to retrieve its display value.
+    # @option [Class, Symbol] measures Specifies a measurement for the characteristic. Either provide a class constant that conforms to the Charisma::Measurement API, or use a symbol to specify a built-in Charisma measurement.
+    # @option [Proc] blk A proc that defines how the characteristic should be displayed.
+    # @see Charisma::Base::ClassMethods#characterize
+    # @see Charisma::Characterization#has
+    # @see Charisma::Measurement
     def initialize(name, options, &blk)
       @name = name
       @proc = blk if block_given?

data/lib/charisma/characterization.rb

@@ -1,6 +1,21 @@
 module Charisma
-  class Characterization < Hash    
+  # Stores the set of characteristics defined on a class.
+  #
+  # Typically this is created with <tt>Charisma::Base::ClassMethods#characterize</tt>, and characteristics defined within it by the ensuing block.
+  class Characterization < Hash
     include Blockenspiel::DSL
+    # Define a characteristic.
+    #
+    # This is used within <tt>Charisma::Base::ClassMethods#characterize</tt> blocks to curate attributes on a class. Internally, a <tt>Charisma::Characteristic</tt> is created to store the definition.
+    # @param [Symbol] 
+    # @param [Symbol] name The name of the characteristic. The method with this name will be called on the characterized object to retrieve its raw value.
+    # @param [Hash] options The options hash.
+    # @option [Symbol] display_with A symbol that gets sent as a method on the characteristic to retrieve its display value.
+    # @option [Class, Symbol] measures Specifies a measurement for the characteristic. Either provide a class constant that conforms to the Charisma::Measurement API, or use a symbol to specify a built-in Charisma measurement.
+    # @option [Proc] blk A proc that defines how the characteristic should be displayed.
+    # @see Charisma::Base::ClassMethods#characterize
+    # @see Charisma::Characteristic
+    # @see Charisma::Measurement
     def has(name, options = {}, &blk)
       name = name.to_sym
       self[name] = Characteristic.new(name, options, &blk)

data/lib/charisma/curator.rb

@@ -1,32 +1,58 @@
 require 'forwardable'
 module Charisma
+  # A Hash-like object that stores computed characteristics about an instance of a characterized class.
+  #
+  # Every instance of a characterized class gets a Curator, accessed via <tt>#characteristics</tt>.
+  # @see Charisma::Base#characteristics
   class Curator
-    attr_reader :subject, :characteristics
+    # The curator's subject--the instance itself' 
+    attr_reader :subject
     
+    # The hashed wrapped by the curator that actually stores the computed characteristics'
+    attr_reader :characteristics
+    
+    # Create a Curator.
+    #
+    # Typically this is done automatically when <tt>#characteristics</tt> is called on an instance of a characterized class for the first time.
+    # @param [Object] The subject of the curation -- an instance of a characterized class
+    # @see Charisma::Base#characteristics
     def initialize(subject)
       @characteristics = {}.extend LooseEquality
       @subject = subject
       subject.class.characterization.keys.each do |key|
-        if value = subject.send(key)
+        if subject.respond_to?(key) and value = subject.send(key)
           self[key] = value
         end
       end
     end
     
+    # Store a late-defined characteristic, with a Charisma wrapper.
+    # @param [Symbol] key The name of the characteristic, which must match one defined in the class's characterization
+    # @param value The value of the characteristic
     def []=(key, value)
       characteristics[key] = Curation.new value, subject.class.characterization[key]
     end
     
+    # A custom inspection method to enhance IRB and log readability
     def inspect
       "<Charisma:Curator #{keys.length} known characteristic(s)>"
     end
     
+    # (see #inpsect)
     def to_s; inspect end
     
     extend Forwardable
-    delegate [:[], :keys, :slice, :==] => :characteristics
+    delegate [:[], :keys, :slice, :==, :each] => :characteristics
     
+    # Loose equality for Hashlike objects
+    #
+    # <tt>Hash#==</tt> as defined in Ruby core is very, very strict: it uses <tt>Object#==</tt> on each of its values to determine equality.
+    # This module overrides <tt>#==</tt> to loosen this evaluation.
     module LooseEquality
+      # Determine equality with another Hashlike object, loosely.
+      #
+      # Unlike Ruby's own <tt>Hash#==</tt>, this method uses the values' native <tt>#==</tt> methods, where available, to determine equality.
+      # @param [Hash] other The other hash
       def ==(other)
         return false unless keys.sort == other.keys.sort
         keys.all? do |k|

data/lib/charisma/curator/curation.rb

@@ -1,11 +1,25 @@
 require 'delegate'
 module Charisma
   class Curator
+    # A wrapper around computed characteristic values that intervenes when the value is asked to present itself.
+    #
+    # Implements the Delegator pattern, with uncaught methods delegated to the characteristic's computed value.
+    # (Undocumented below is that <tt>#to_s</tt> is specifically delegated to <tt>#render</tt>.)
     class Curation < Delegator
       extend Forwardable
+      
+      # The computed value of the characteristic
       attr_accessor :value
+      
+      # The characteristic, as defined in the class's characterization
+      # @return [Charisma::Characteristic]
       attr_reader :characteristic
       
+      # Create new Curation wrapper.
+      #
+      # This is typically done by the instance's <tt>Charisma::Curator</tt>
+      # @param value The computed value of the characteristic for the instance
+      # @param [Charisma::Characteristic, optional] characteristic The associated characteristic definition
       def initialize(value, characteristic = nil)
         @characteristic = characteristic
         establish_units_methods if characteristic && characteristic.measurement
@@ -14,16 +28,24 @@ module Charisma
       
       delegate [:to_s] => :render
 
+      # An inspection method for more readable IRB sessions and logs.
       def inspect
-        "<Charisma::Curator::Curation for :#{characteristic.name} (use #to_s to render value of #{value.class})>"
+        if characteristic
+          "<Charisma::Curator::Curation for :#{characteristic.name} (use #to_s to render value of #{value.class})>"
+        else
+          "<Charisma::Curator::Curation for undefined characteristic (use #to_s to render value of #{value.class})>"
+        end          
       end
       
-      # Delegator methods
+      # Delegator method
       def __getobj__; value end
+
+      # Delegator method
       def __setobj__(obj); self.value = obj end
       
       private
       
+      # If this curation deals with a measured characteristic, this method will delegate <tt>#u</tt>, <tt>#units</tt>, and appropriate unit-name methods to <tt>#render</tt>.
       def establish_units_methods
         self.class.delegate [:u, :units] => :render
         if conversions = Conversions.conversions[units.to_sym]
@@ -31,6 +53,8 @@ module Charisma
         end
       end
       
+      # Provide a display-friendly presentation of the computed characteristic's value.
+      # @return [String]
       def render
         return value unless characteristic
         if characteristic.proc
@@ -46,18 +70,23 @@ module Charisma
         end
       end
       
+      # Render the value using the characteristic's proc.
       def render_proc
         characteristic.proc.call(value)
       end
       
+      # Render the value using an accessor on the characteristic's association.
       def use_accessor
         value.send(characteristic.accessor)
       end
       
+      # Render the value using its specified measurement.
       def defer_to_measurement
         measurement_class.new(value)
       end
       
+      # The subclass of <tt>Charisma::Measurement</tt> with which this curation's characteristic is measured.
+      # @return [Class]
       def measurement_class
         case characteristic.measurement
         when Class
@@ -69,10 +98,12 @@ module Charisma
         end
       end
       
+      # Render the value using its <tt>#as_characteristic</tt> method.
       def defer_to_value
         value.as_characteristic
       end
       
+      # Render the value using its <tt>#to_s</tt> method.
       def render_value
         value
       end

data/lib/charisma/measurement.rb

@@ -1,27 +1,45 @@
 module Charisma
+  # An abstract class that implements an API for Charisma to deal with measured characteristics.
+  #
+  # @abstract An actual measurement class should inherit from this and use <tt>#units</tt> to define units.
   class Measurement
+    # The quantity of the measured value
     attr_reader :value
     
+    # Create a new instance of this measurement.
+    #
+    # Typically this will be done automatically by <tt>Charisma::Curator::Curation</tt>.
+    # @param [Fixnum] value The quantity of the measured value
+    # @see Charisma::Curator::Curation
     def initialize(value)
       @value = value
     end
 
+    # Show the measured value, along with units
+    # @return [String]
     def to_s
       "#{NumberHelper.delimit value} #{u}"
     end
     
+    # Return just the quantity of the measurement
+    # @return [Fixnum]
     def to_f
       value.to_f
     end
     
+    # The measurement's units
+    # @return [Symbol]'
     def units
       self.class.unit
     end
     
+    # The standard abbreviation for the measurement's units
+    # @return [String]
     def u
       self.class.unit_abbreviation
     end
     
+    # Handle conversion methods
     def method_missing(*args)
       if Conversions.conversions[units.to_sym][args.first]
         to_f.send(units.to_sym).to(args.first)
@@ -31,14 +49,22 @@ module Charisma
     end
     
     class << self
+      # Define the units used with this measurement.
+      #
+      # Used by conforming subclasses.
+      # @param [Hash] units The units, given in the form <tt>:plural_unit_name => 'abbrev'</tt>
       def units(units)
         @units, @units_abbreviation = units.to_a.flatten
       end
       
+      # Retrive the units used by the measurement
+      # @return [Symbol]
       def unit
         @units
       end
       
+      # Retrieve the abbreviation of the units used by the measurement
+      # @return [String]
       def unit_abbreviation
         @units_abbreviation
       end

data/lib/charisma/measurement/length.rb

@@ -1,5 +1,6 @@
 module Charisma
   class Measurement
+    # Length, in meters.
     class Length < Measurement
       units :meters => 'm'
     end

data/lib/charisma/measurement/mass.rb

@@ -0,0 +1,8 @@
+module Charisma
+  class Measurement
+    # Mass, in kilograms
+    class Mass < Measurement
+      units :kilograms => 'kg'
+    end
+  end
+end

data/lib/charisma/measurement/speed.rb

@@ -0,0 +1,10 @@
+module Charisma
+  class Measurement
+    # Speed, in meters per second
+    class Speed < Measurement
+      units :meters_per_second => 'm/s'
+    end
+    # Velocity is an SI-accepted alias for speed
+    Velocity = Speed
+  end
+end

data/lib/charisma/measurement/time.rb

@@ -0,0 +1,8 @@
+module Charisma
+  class Measurement
+    # Time, in seconds
+    class Time < Measurement
+      units :seconds => 's'
+    end
+  end
+end

data/lib/charisma/number_helper.rb

@@ -1,5 +1,11 @@
 module Charisma
+  # Various methods for dealing with numbers
   class NumberHelper
+    # Delimit a number with commas and return as a string.
+    #
+    # Adapted from ActionView.
+    # @param [Fixnum] number The number to delimit
+    # @return [String]
     def self.delimit(number)
       parts = number.to_s.split('.')
       parts[0].gsub!(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1,")

data/lib/charisma/version.rb

@@ -1,3 +1,4 @@
-module Charisma
-  VERSION = "0.2.0"
-end
+module Charisma
+  # Charisma's version
+  VERSION = "0.3.0"
+end

data/test/helper.rb

@@ -28,10 +28,14 @@ class Spaceship < SuperModel::Base
     has :window_count do |window_count|
       "#{window_count} windows"
     end
+  end
+  
+  characterize do
     has :size, :measures => :length # uses Charisma::Measurements::Length
     has :weight, :measures => RelativeAstronomicMass
     has :name
     has :destination
+    has :color
   end
 end
 

data/test/test_charisma.rb

@@ -66,11 +66,33 @@ class TestCharisma < Test::Unit::TestCase
     assert_equal [:name].sort_by { |k| k.to_s }, spaceship.characteristics.keys.sort_by { |k| k.to_s }
   end
   def test_014_characterization_keys
-    assert_equal [:destination, :fuel, :make, :name, :size, :weight, :window_count].sort_by { |k| k.to_s }, Spaceship.characterization.keys.sort_by { |k| k.to_s }
+    assert_equal [:color, :destination, :fuel, :make, :name, :size, :weight, :window_count].sort_by { |k| k.to_s }, Spaceship.characterization.keys.sort_by { |k| k.to_s }
   end
   def test_015_characteristic_equality
     amaroq = Spaceship.new :window_count => 8
     buster = Spaceship.new :window_count => 8
     assert_equal amaroq.characteristics, buster.characteristics
   end
+  def test_016_inspection_of_undefined_characteristic
+    muktruk = Spaceship.new
+    muktruk.characteristics[:bumper_sticker] = 'LT'
+    assert_nothing_raised do
+      muktruk.characteristics[:bumper_sticker].inspect
+    end
+  end
+  def test_017_each
+    spaceship = Spaceship.new :name => 'Amaroq'
+    catch :blam do
+      spaceship.characteristics.each do |k, v|
+        throw :blam if k == :name
+      end
+      flunk
+    end
+  end
+  def test_018_double_bag
+    geo = SpaceshipMake.create :name => 'Geo'
+    g = Spaceship.new :make => geo
+    g.characteristics[:name] = g.characteristics[:make]
+    assert_equal 'Geo', g.characteristics[:name].to_s
+  end
 end

metadata

@@ -1,13 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: charisma
 version: !ruby/object:Gem::Version 
-  hash: 23
   prerelease: 
-  segments: 
-  - 0
-  - 2
-  - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Andy Rossmeissl
@@ -16,121 +11,97 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-11 00:00:00 -04:00
+date: 2011-06-02 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  prerelease: false
   name: activesupport
-  type: :runtime
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
-  requirement: *id001
-- !ruby/object:Gem::Dependency 
+  type: :runtime
   prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
   name: blockenspiel
-  type: :runtime
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
-  requirement: *id002
-- !ruby/object:Gem::Dependency 
+  type: :runtime
   prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
   name: conversions
-  type: :runtime
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
-  requirement: *id003
-- !ruby/object:Gem::Dependency 
+  type: :runtime
   prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
   name: bundler
-  type: :development
-  version_requirements: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
-  requirement: *id004
-- !ruby/object:Gem::Dependency 
+  type: :development
   prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
   name: bueller
-  type: :development
-  version_requirements: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
-  requirement: *id005
-- !ruby/object:Gem::Dependency 
+  type: :development
   prerelease: false
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
   name: rake
-  type: :development
-  version_requirements: &id006 !ruby/object:Gem::Requirement 
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
-  requirement: *id006
-- !ruby/object:Gem::Dependency 
+  type: :development
   prerelease: false
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
   name: rcov
-  type: :development
-  version_requirements: &id007 !ruby/object:Gem::Requirement 
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
-  requirement: *id007
-- !ruby/object:Gem::Dependency 
+  type: :development
   prerelease: false
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
   name: supermodel
-  type: :development
-  version_requirements: &id008 !ruby/object:Gem::Requirement 
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
-  requirement: *id008
+  type: :development
+  prerelease: false
+  version_requirements: *id008
 description: Define strategies for accessing and displaying a subset of your classes' attributes
 email: andy@rossmeissl.net
 executables: []
@@ -139,13 +110,13 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.rdoc
+- README.markdown
 files: 
 - .document
 - .gitignore
 - Gemfile
 - LICENSE
-- README.rdoc
+- README.markdown
 - Rakefile
 - charisma.gemspec
 - lib/charisma.rb
@@ -157,6 +128,9 @@ files:
 - lib/charisma/curator/curation.rb
 - lib/charisma/measurement.rb
 - lib/charisma/measurement/length.rb
+- lib/charisma/measurement/mass.rb
+- lib/charisma/measurement/speed.rb
+- lib/charisma/measurement/time.rb
 - lib/charisma/number_helper.rb
 - lib/charisma/version.rb
 - test/helper.rb
@@ -175,7 +149,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
+      hash: -405120809897582198
       segments: 
       - 0
       version: "0"
@@ -184,11 +158,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 21
-      segments: 
-      - 1
-      - 3
-      - 7
       version: 1.3.7
 requirements: []
 
@@ -197,5 +166,6 @@ rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Curate your rich Ruby objects' attributes
-test_files: []
-
+test_files: 
+- test/helper.rb
+- test/test_charisma.rb

data/README.rdoc

@@ -1,17 +0,0 @@
-= charisma
-
-Description goes here.
-
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-== Copyright
-
-Copyright (c) 2011 Andy Rossmeissl. See LICENSE for details.