maintain 0.1.0

data/.gitignore

@@ -0,0 +1 @@
+coverage/

data/README.markdown

@@ -0,0 +1,168 @@
+Maintain
+===
+
+**Maintain** is a simple state machine mixin for Ruby objects. It supports comparisons, bitmasks,
+and hooks that really work. It can be used for multiple attributes and will always do its best to
+stay out of your way and let your code drive the machine, and not vice versa.
+
+Installation
+-
+
+**Maintain** is provided as a Gem. It's pretty basic, really:
+
+1. Install it with `gem install maintain`
+2. Require it with `require "maintain"`
+
+Basic Usage
+-
+
+**Maintain** is pretty straightforward to use. First, you have to tell a Ruby object to maintain
+state on an attribute:
+
+	class Foo
+	  extend Maintain
+	  maintains :state do
+	    state :new, :default => true
+	    state :old
+	  end
+	end
+
+That's it for basic state maintenance! Check it out:
+
+	foo = Foo.new
+	foo.state			#=> :new
+	foo.new?			#=> true
+	foo.state = :old
+	foo.old?			#=> true
+
+But wait! What if you've already defined "new?" on the Foo class? Not to worry, Maintain won't step on your toes. Just use:
+
+	foo.state.new?
+
+Comparisons
+-
+
+**Maintain** provides quick and easy comparisons between states. You can specify integer values of states to compare on,
+or you can just let it infer what it wants. From our example above:
+
+	foo.state = :new
+	foo.state > :old	#=> false
+	foo.state <= :old	#=> true
+
+You could also do:
+
+	class Foo
+	  extend Maintain
+	  maintains :state do
+	    state :new, 12, :default => true
+	    state :old, 5
+	  end
+	end
+
+	Foo.new.state > old	#=> true
+
+Bitmasking
+-
+
+Sometimes you need to store a simple combination of values. Sure, you could add individual columns for each value to your
+relational database - or you could implement a single bitmask column:
+
+	class Foo
+	  extend Maintain
+	  maintains :state, :bitmask => true do
+	    # NOTE: Maintain will try to infer a bitmask value if you do not provid  an integer here,
+	    # but if you don't -- and you re-order your state calls later -- all stored bitmasks will
+	    # be invalidated. You have been warned.
+	    state :new, 1
+	    state :old, 2
+	    state :borrowed, 3
+	    state :blue, 4
+	  end
+	end
+	
+	foo = Foo.new
+	foo.state 						#=> nil
+	foo.state = [:new, :borrowed]
+	foo.state 						#=> [:new, :borrowed]
+	foo.new? 						#=> true
+	foo.borrowed? 					#=> true
+	foo.blue? 						#=> false
+	foo.blue!
+	foo.blue? 						#=> true
+	
+	# foo.state will boil happily down to an integer when you store it.
+
+Aggregates
+-
+
+What about when a group of states is needed? Yeah, you could write `foo.bar? || foo.baz?`. You could even make that a method!
+But why not just add the following?
+
+	class Foo
+	  extend Maintain
+	  maintains :state do
+	    state :new
+	    state :old
+	    state :borrowed
+	    state :blue
+	
+	    aggregate :starts_with_b, [:borrowed, :blue]
+	  end
+	end
+	
+	foo = Foo.new
+	foo.status = :borrowed
+	foo.starts_with_b?		#=> true
+
+Named Scopes
+-
+
+**Maintain** knows all about ActiveRecord. Adding states and aggregates will automatically create named scopes on ActiveRecord::Base
+subclasses for those states! Check it:
+
+	class Foo < ActiveRecord::Base
+	  extend Maintain
+	  maintains :state do
+	    state :active
+	    state :inactive
+	  end
+	end
+	
+	Foo.active		#=> []
+	Foo.inactive	#=> []
+
+Hooks
+-
+
+**Maintain** can hook into state entry and exit, and provides a number of mechanisms for doing so:
+
+	class Foo < ActiveRecord::Base
+	  maintains :state do
+	    state :active, :enter => :activated
+	    state :inactive, :exit => lambda { self.bar.baz! }
+	  end
+	
+	  def activated
+	    puts "I'm alive!"
+	  end
+	end
+
+Of course, maybe that's not your style. Why not try this?
+
+	class Foo
+	  extend Maintain
+	  maintains :state do
+	    state :active
+	    state :inactive
+
+	    enter :active, :activated
+	    exit :inactive do
+	      bar.baz!
+	    end
+	  end
+
+	  def activated
+	    puts "I'm alive!"
+	  end
+	end
+

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+
+task :default => :spec
+
+begin
+  require 'spec/rake/spectask'
+
+  desc "Run all examples"
+  Spec::Rake::SpecTask.new('spec') do |t|
+    t.spec_files = FileList['spec/**/*.rb']
+  end
+
+  desc "Run all examples with RCov"
+  Spec::Rake::SpecTask.new('spec:rcov') do |t|
+    t.spec_files = FileList['spec/**/*.rb']
+    t.rcov = true
+    t.rcov_opts = ['--exclude', 'spec,gem']
+  end
+rescue LoadError
+  puts "Could not load Rspec. To run tests, use `gem install rspec`"
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "maintain"
+    gemspec.summary = "A Ruby state machine that lets your code do the driving"
+    gemspec.description = %{
+      Maintain is a simple state machine mixin for Ruby objects. It supports comparisons, bitmasks,
+      and hooks that really work. It can be used for multiple attributes and will always do its best to
+      stay out of your way and let your code drive the machine, and not vice versa.
+    }
+    gemspec.email = "flip@x451.com"
+    gemspec.homepage = "http://github.com/flipsasser/maintain"
+    gemspec.authors = ["Flip Sasser"]
+  end
+rescue LoadError
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/maintain/bitmask_value.rb

@@ -0,0 +1,43 @@
+module Maintain
+  class BitmaskValue < Value
+    def set_value(value)
+      @value = bitmask_for(value)
+    end
+
+    protected
+    def bitmask_for(states)
+      Array(states).map{|value| value_for(value) }.sort.inject(0) {|total, mask| total | mask }
+    end
+
+    def compare_value
+      @value ||= 0
+    end
+
+    def compare_value_for(state)
+      bitmask_for(state)
+    end
+
+    def method_missing(method, *args)
+      if (method.to_s =~ /^(.+)(\?|!)$/) && @state.states.has_key?($1.to_sym)
+        compare = value_for($1)
+        if $2 == '?'
+          self.class.class_eval <<-EOC
+            def #{method}
+              @value & #{compare.inspect} != 0
+            end
+          EOC
+          @value & compare != 0
+        else
+          self.class.class_eval <<-EOC
+            def #{method}
+              @value = (@value || 0) | #{compare.inspect}
+            end
+          EOC
+          @value = (@value || 0) | compare
+        end
+      else
+        super
+      end
+    end
+  end
+end

data/lib/maintain/integer_value.rb

@@ -0,0 +1,7 @@
+module Maintain
+  class IntegerValue < Value
+    def value
+      value_for(@value)
+    end
+  end
+end

data/lib/maintain/maintainer.rb

@@ -0,0 +1,171 @@
+module Maintain
+  class Maintainer
+    def aggregate(name, options)
+      if options.is_a?(Hash) && options.has_key?(:as)
+        options = options[:as]
+      end
+      aggregates[name] = options
+      # Now we're going to add proxies to test for state being in this aggregate. Don't create
+      # this method unless it doesn't exist.
+      boolean_method = "#{name}?"
+      if method_free?(boolean_method)
+        # Define it if'n it don't already exit! These are just proxies - so Foo.maintains(:state) { state :awesome }
+        # will now have Foo.new.awesome?. But that's really just a proxy for Foo.new.state.awesome?
+        # So they're just shortcuts for brevity's sake.
+        maintainee.class_eval <<-EOC
+          def #{boolean_method}
+            #{@attribute}.#{boolean_method}
+          end
+        EOC
+      end
+      # Now define the state
+      if @active_record && method_free?(name, true)
+        maintainee.named_scope name, :conditions => {@attribute => options}
+      end
+    end
+
+    def aggregates
+      @aggregates ||= {}
+    end
+
+    def bitmask(value)
+      @bitmask = !!value
+    end
+
+    def bitmask?
+      @bitmask
+    end
+
+    def default(state)
+      @default = state
+    end
+
+    def default?
+      !!@default
+    end
+
+    def hook(event, state, instance)
+      if state && hooks[state.to_sym] && hooks[state.to_sym][event.to_sym]
+        hooks[state.to_sym][event.to_sym].each do |method|
+          if method.is_a?(Proc)
+            instance.instance_eval(&method)
+          else
+            instance.send(method)
+          end
+        end
+      end
+    end
+
+    def initialize(maintainee, attribute, active_record = false, options = {})
+      @maintainee = maintainee.name
+      @attribute = attribute.to_sym
+      @active_record = !!active_record
+      options.each do |key, value|
+        self.send(key, value)
+      end
+    end
+
+    def integer(value)
+      @integer = !!value
+    end
+
+    def on(event, state, method = nil, &block)
+      if block_given?
+        method = block
+      end
+      hooks[state.to_sym] ||= {}
+      hooks[state.to_sym][event.to_sym] ||= []
+      hooks[state.to_sym][event.to_sym].push(method) unless hooks[state.to_sym][event.to_sym].include?(method)
+    end
+
+    def state_name_for(value)
+      if value = states.find {|key, options| options[:compare_value] == value}
+        value[0]
+      end
+    end
+
+    def state(name, value = nil, options = {})
+      if value.is_a?(Hash)
+        options = value
+        value = nil
+      end
+      if options.has_key?(:default)
+        default(name)
+      end
+      @increment ||= 0
+      if @bitmask
+        unless value.is_a?(Integer)
+          value = @increment
+        end
+        value = 2 ** value.to_i
+      elsif value.is_a?(Integer)
+        integer(true)
+      end
+      value ||= name
+      states[name] = {:compare_value => !@bitmask && value.is_a?(Integer) ? value : @increment, :value => value}
+      @increment += 1
+      if @active_record && !maintainee.respond_to?(name)
+        conditions = {}
+        maintainee.named_scope name, :conditions => {@attribute => value.is_a?(Symbol) ? value.to_s : value}
+      end
+
+      # Now we're going to add proxies to test for state. These methods only get added if a
+      # method of their name doesn't already exist.
+      boolean_method = "#{name}?"
+      if method_free?(boolean_method)
+        # Define it if'n it don't already exit! These are just proxies - so Foo.maintains(:state) { state :awesome }
+        # will now have Foo.new.awesome?. But that's really just a proxy for Foo.new.state.awesome?
+        # So they're just shortcuts for brevity's sake.
+        maintainee.class_eval <<-EOC
+          def #{boolean_method}
+            #{@attribute}.#{boolean_method}
+          end
+        EOC
+      end
+    end
+
+    def states
+      @states ||= {}
+    end
+
+    def value(initial = nil)
+      if @bitmask
+        BitmaskValue.new(self, initial || @default || 0)
+      elsif @integer
+        IntegerValue.new(self, initial || @default)
+      else
+        Value.new(self, initial || @default)
+      end
+    end
+
+    protected
+    def hooks
+      @hooks ||= {}
+    end
+
+    def maintainee
+      Object.const_get(@maintainee)
+    end
+
+    def method_free?(method_name, class_method = false)
+      # Ugly hack so we don't fetch it 100 times for no reason
+      maintainee_class = maintainee
+      if class_method
+        respond_to = maintainee_class.respond_to?(method_name)
+        methods = maintainee_class.public_methods + maintainee_class.private_methods + maintainee_class.protected_methods
+      else
+        respond_to = false
+        methods = maintainee_class.public_instance_methods + maintainee_class.private_instance_methods + maintainee_class.protected_instance_methods
+      end
+      !respond_to && !methods.include?(method_name)
+    end
+
+    def method_missing(method, *args)
+      if states.has_key?(method)
+        states[method][:value]
+      else
+        super
+      end
+    end
+  end
+end

data/lib/maintain/value.rb

@@ -0,0 +1,105 @@
+module Maintain
+  class Value
+    def >(value)
+      compare_value > compare_value_for(value)
+    end
+
+    def >=(value)
+      compare_value >= compare_value_for(value)
+    end
+
+    def <(value)
+      compare_value < compare_value_for(value)
+    end
+
+    def <=(value)
+      compare_value <= compare_value_for(value)
+    end
+
+    def ==(value)
+      compare_value == compare_value_for(value)
+    end
+
+    def class
+      value.class
+    end
+
+    def initialize(state, value = nil)
+      @state = state
+      @value = value
+    end
+
+    def inspect
+      value.inspect
+    end
+
+    def nil?
+      value.nil?
+    end
+
+    def set_value(value)
+      @compare_value = nil
+      @value = state_name_for(value)
+    end
+
+    def to_s
+      value.to_s
+    end
+
+    def value
+      @value
+    end
+
+    private
+    def compare_value
+      @compare_value ||= compare_value_for(@value)
+    end
+
+    def compare_value_for(state)
+      state_value_for(state, :compare_value)
+    end
+
+    def method_missing(method, *args)
+      if (method.to_s =~ /^(.+)\?$/)
+        check = $1.to_sym
+        if @state.states.has_key?(check)
+          self.class.class_eval <<-EOC
+            def #{method}
+              self == #{check.inspect}
+            end
+          EOC
+          # Calling `method` on ourselves fails. Something to do w/subclasses. Meh.
+          return self == $1.to_sym
+        elsif aggregates = @state.aggregates[check]
+          self.class.class_eval <<-EOC
+            def #{method}
+              @state.aggregates[#{check.inspect}].include?(@value)
+            end
+          EOC
+          return aggregates.include?(@value)
+        end
+      end
+      super
+    end
+
+    def state_name_for(value)
+      if (value.is_a?(String) || value.is_a?(Symbol))
+        @state.states.has_key?(value.to_sym) ? value.to_sym : nil
+      else
+        @state.state_name_for(value)
+      end
+    end
+
+    def state_value_for(state, value)
+      if (state.is_a?(String) || state.is_a?(Symbol)) && state_hash = @state.states[state.to_sym]
+        state_hash[value]
+      else
+        state
+      end
+    end
+
+    def value_for(state)
+      state_value_for(state, :value)
+    end
+  end
+end

data/lib/maintain.rb

@@ -0,0 +1,119 @@
+module Maintain
+  # We're not really interested in loading anything into memory if we don't need to,
+  # so Maintainer, Value, and the Value subclasses are ignored until they're needed.
+  autoload(:Maintainer, 'lib/maintain/maintainer')
+  autoload(:Value, 'lib/maintain/value')
+  autoload(:BitmaskValue, 'lib/maintain/bitmask_value')
+  autoload(:IntegerValue, 'lib/maintain/integer_value')
+
+  # The core class method of Maintain. Basic usage is:
+  # 
+  #   maintain :state do
+  #     state :new, :default => true
+  #     state :expired, :enter => :expire_children
+  #     state :reopened, :exit => lambda { children.each(&:reopen) }
+  #     aggregate :accessible, :as => [:new, :reopened]
+  #   end
+  # 
+  # It also supports more complex configuration options, like bitmask columns
+  # and integer values (for performance and portability)
+  # 
+  #   maintain :permissions, :bitmask => true do
+  #     state :edit, 1
+  #     state :delete, 2
+  #     state :manage, 3
+  #   end
+  # 
+  # This method is aliased as `maintains` with the intention of allowing developers
+  # to code imperatively ("maintain, damn you!") or descriptively ("it maintains, man")
+  def maintain(attribute, options = {}, &block)
+    # Detect if this is ActiveRecord::Base or a subclass of it
+    # TODO: Make this not suck
+    if defined?(ActiveRecord::Base)
+      active_record = self == ActiveRecord::Base
+      superclass = self
+      while !active_record && superclass.superclass
+        active_record = superclass == ActiveRecord::Base
+        superclass = superclass.superclass
+      end
+    else
+      active_record = false
+    end
+
+    # Create an instance of the maintainer class. It handles all of the state
+    # configuration, hooking, aggregation, named_scoping, etc.
+    maintainer = Maintainer.new(self, attribute, active_record, options)
+    if block_given?
+      maintainer.instance_eval(&block)
+    end
+
+    # Define our getters and setters - these are the only methods Maintain will stomp
+    # on if you've already defined them. This is because they're how Maintain works.
+    class_eval <<-EOC
+      def #{attribute}=(value)
+        # If we can find the maintainer on this attribute, we'll use it to set values.
+        if maintainer = self.class.maintainers[#{attribute.to_sym.inspect}]
+          # First, we instantiate a value on this maintainer if we haven't already
+          @#{attribute} ||= maintainer.value
+
+          # Then run the exit hook if we're changing the value
+          maintainer.hook(:exit, @#{attribute}.value, self)
+
+          # Then set the value itself. Maintainer::State will return the value you set,
+          # so if we're setting to nil we get rid of the attribute entirely - it's not
+          # needed and we want the getter to return nil in that case.
+          unless @#{attribute}.set_value(value)
+            @#{attribute} = nil
+          end#{%{
+
+          # If this is ActiveRecord::Base or a subclass of it, we'll make sure calling the
+          # setter writes a DB-friendly value.
+          if respond_to?(:write_attribute)
+            write_attribute(:#{attribute}, @#{attribute} ? @#{attribute}.value.to_s : nil)
+          end
+          } if active_record}
+
+          # Last but not least, run the enter hooks for the new value - cause that's how we
+          # do.
+          maintainer.hook(:enter, @#{attribute}.value, self) if @#{attribute}
+        else
+          # If we can't find a maintainer for this attribute, make our best effort to do what
+          # attr_accessor does - set the instance variable.
+          @#{attribute} = value#{%{
+
+          # ... and on ActiveRecord::Base, we'll also write the attribute like a normal setter.
+          if respond_to?(:write_attribute)
+            write_attribute(:#{attribute}, @#{attribute})
+          end
+          } if active_record}
+        end
+      end
+
+      def #{attribute}
+        # Start by returning an already-instantiated Maintainer::State if it exists
+        return @#{attribute} if @#{attribute}
+
+        # If'n it doesn't already exist AND this maintained attribute has a default value (and
+        # bitmasks must have at least a 0 value), we'll instantiate a Maintainer::State and return
+        # it.
+        if self.class.maintainers[#{attribute.to_sym.inspect}].default? || self.class.maintainers[#{attribute.to_sym.inspect}].bitmask?
+          @#{attribute} = self.class.maintainers[#{attribute.to_sym.inspect}].value#{"(read_attribute(:#{attribute}))" if active_record}
+        end
+      end
+    EOC
+
+    # Last! Not least! Save our maintainer directly on this class. We'll use it in our setters (as in above)
+    # and we'll also modify it instead of replacing it outright, so subclasses or mixins can extend functionality
+    # without replacing it.
+    maintainers[attribute.to_sym] = maintainer
+  end
+  alias :maintains :maintain
+
+  def maintainers #:nodoc:
+    @maintainers ||= {}
+  end
+end
+
+if defined?(ActiveRecord::Base)
+  ActiveRecord::Base.extend Maintain
+end