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 to facilitate the characterization of the flights, cars, etc. that we're performing carbon calculations on.

See also: RDocs.


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"
    has :size, :measures => :length # uses Charisma::Measurements::Length
    has :weight, :measures => RelativeAstronomicMass
    has :name
    has :destination
irb(main):001:0> amaroq = :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:

class Foo
  # ...
  include Charisma
  characterize do
    # Characteristics go here

Simple (scalar) characteristics

How do you define characteristics? The simplest way looks like this:

characterize do
  has :color

Charisma will obtain the color characteristic for an instance by calling its #color method.

irb(main):001:0> => '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:

characterize do
  has :color do |color|
irb(main):001:0> => 'black').characteristics[:color].to_s
 => #000000

Or perhaps you're using an association:

characterize do
  has :color, :display_with => :hex # If unspecified, Charisma will try #as_characteristic and #to_s on the associated object, in that order 
irb(main):001:0> => 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:

characterize do
  has :size, :measures => Length 
class Length < Charisma::Measurement # Don't need to inherit if you want to DIY
  units :metres => 'm' 
irb(main):001:0> => 10).characteristics[:size].to_s
 => 10 m

Charisma has some convenient measurements baked in:

characterize do
  has :size, :measures => Charisma::Measurement::Length 

Built-in measurements can be referenced with a shortcut:

characterize do
  has :size, :measures => :length 

Charisma uses Conversions to provide useful unit conversion methods:

irb(main):001:0> => 10).characteristics[:size].feet
 => 32.808399000000003


Charisma now provides #as_json for characteristics---convert to actual JSON with your favorite JSON library's #to_json.


Copyright (c) 2011 Andy Rossmeissl. See LICENSE for details.