state-fu 0.11.1

data/lib/support/active_support_lite/keys.rb

@@ -0,0 +1,57 @@
+module ActiveSupport #:nodoc:all:
+  module CoreExtensions #:nodoc
+    module Hash #:nodoc
+      module Keys
+        # Return a new hash with all keys converted to strings.
+         #:nodoc
+        def stringify_keys
+          inject({}) do |options, (key, value)|
+            options[key.to_s] = value
+            options
+          end
+        end
+
+        # Destructively convert all keys to strings.
+         #:nodoc
+        def stringify_keys!
+          keys.each do |key|
+            self[key.to_s] = delete(key)
+          end
+          self
+        end
+
+        # Return a new hash with all keys converted to symbols.
+         #:nodoc
+        def symbolize_keys
+          inject({}) do |options, (key, value)|
+            options[(key.to_sym rescue key) || key] = value
+            options
+          end
+        end
+
+        # Destructively convert all keys to symbols.
+         #:nodoc
+        def symbolize_keys!
+          self.replace(self.symbolize_keys)
+        end
+
+        alias_method :to_options,  :symbolize_keys
+        alias_method :to_options!, :symbolize_keys!
+
+        # Validate all keys in a hash match *valid keys, raising ArgumentError on a mismatch.
+        # Note that keys are NOT treated indifferently, meaning if you use strings for keys but assert symbols
+        # as keys, this will fail.
+        #
+        # ==== Examples
+        #   { :name => "Rob", :years => "28" }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key(s): years"
+        #   { :name => "Rob", :age => "28" }.assert_valid_keys("name", "age") # => raises "ArgumentError: Unknown key(s): name, age"
+        #   { :name => "Rob", :age => "28" }.assert_valid_keys(:name, :age) # => passes, raises nothing
+        #:nodoc
+        def assert_valid_keys(*valid_keys)
+          unknown_keys = keys - [valid_keys].flatten
+          raise(ArgumentError, "Unknown key(s): #{unknown_keys.join(", ")}") unless unknown_keys.empty?
+        end
+      end
+    end
+  end
+end

data/lib/support/active_support_lite/misc.rb

@@ -0,0 +1,59 @@
+class Object  #:nodoc:all
+  # Returns +value+ after yielding +value+ to the block. This simplifies the
+  # process of constructing an object, performing work on the object, and then
+  # returning the object from a method. It is a Ruby-ized realization of the K
+  # combinator, courtesy of Mikael Brockman.
+  #
+  # ==== Examples
+  #
+  #  # Without returning
+  #  def foo
+  #    values = []
+  #    values << "bar"
+  #    values << "baz"
+  #    return values
+  #  end
+  #
+  #  foo # => ['bar', 'baz']
+  #
+  #  # returning with a local variable
+  #  def foo
+  #    returning values = [] do
+  #      values << 'bar'
+  #      values << 'baz'
+  #    end
+  #  end
+  #
+  #  foo # => ['bar', 'baz']
+  #
+  #  # returning with a block argument
+  #  def foo
+  #    returning [] do |values|
+  #      values << 'bar'
+  #      values << 'baz'
+  #    end
+  #  end
+  #
+  #  foo # => ['bar', 'baz']
+   #:nodoc
+  def returning(value)
+    yield(value)
+    value
+  end
+
+  # Yields <code>x</code> to the block, and then returns <code>x</code>.
+  # The primary purpose of this method is to "tap into" a method chain,
+  # in order to perform operations on intermediate results within the chain.
+  #
+  #   (1..10).tap { |x| puts "original: #{x.inspect}" }.to_a.
+  #     tap    { |x| puts "array: #{x.inspect}" }.
+  #     select { |x| x%2 == 0 }.
+  #     tap    { |x| puts "evens: #{x.inspect}" }.
+  #     map    { |x| x*x }.
+  #     tap    { |x| puts "squares: #{x.inspect}" }
+   #:nodoc
+  def tap
+    yield self
+    self
+  end unless Object.respond_to?(:tap)
+end

data/lib/support/active_support_lite/module.rb

@@ -0,0 +1 @@
+require File.join( File.dirname( __FILE__),'module/delegation')

data/lib/support/active_support_lite/module/delegation.rb

@@ -0,0 +1,130 @@
+class Module
+  # Provides a delegate class method to easily expose contained objects' methods
+  # as your own. Pass one or more methods (specified as symbols or strings)
+  # and the name of the target object as the final <tt>:to</tt> option (also a symbol
+  # or string).  At least one method and the <tt>:to</tt> option are required.
+  #
+  # Delegation is particularly useful with Active Record associations:
+  #
+  #   class Greeter < ActiveRecord::Base
+  #     def hello()   "hello"   end
+  #     def goodbye() "goodbye" end
+  #   end
+  #
+  #   class Foo < ActiveRecord::Base
+  #     belongs_to :greeter
+  #     delegate :hello, :to => :greeter
+  #   end
+  #
+  #   Foo.new.hello   # => "hello"
+  #   Foo.new.goodbye # => NoMethodError: undefined method `goodbye' for #<Foo:0x1af30c>
+  #
+  # Multiple delegates to the same target are allowed:
+  #
+  #   class Foo < ActiveRecord::Base
+  #     belongs_to :greeter
+  #     delegate :hello, :goodbye, :to => :greeter
+  #   end
+  #
+  #   Foo.new.goodbye # => "goodbye"
+  #
+  # Methods can be delegated to instance variables, class variables, or constants
+  # by providing them as a symbols:
+  #
+  #   class Foo
+  #     CONSTANT_ARRAY = [0,1,2,3]
+  #     @@class_array  = [4,5,6,7]
+  #     
+  #     def initialize
+  #       @instance_array = [8,9,10,11]
+  #     end
+  #     delegate :sum, :to => :CONSTANT_ARRAY
+  #     delegate :min, :to => :@@class_array
+  #     delegate :max, :to => :@instance_array
+  #   end
+  #
+  #   Foo.new.sum # => 6
+  #   Foo.new.min # => 4
+  #   Foo.new.max # => 11
+  #
+  # Delegates can optionally be prefixed using the <tt>:prefix</tt> option. If the value
+  # is <tt>true</tt>, the delegate methods are prefixed with the name of the object being
+  # delegated to.
+  #
+  #   Person = Struct.new(:name, :address)
+  #
+  #   class Invoice < Struct.new(:client)
+  #     delegate :name, :address, :to => :client, :prefix => true
+  #   end
+  #
+  #   john_doe = Person.new("John Doe", "Vimmersvej 13")
+  #   invoice = Invoice.new(john_doe)
+  #   invoice.client_name    # => "John Doe"
+  #   invoice.client_address # => "Vimmersvej 13"
+  #
+  # It is also possible to supply a custom prefix.
+  #
+  #   class Invoice < Struct.new(:client)
+  #     delegate :name, :address, :to => :client, :prefix => :customer
+  #   end
+  #
+  #   invoice = Invoice.new(john_doe)
+  #   invoice.customer_name    # => "John Doe"
+  #   invoice.customer_address # => "Vimmersvej 13"
+  #
+  # If the object to which you delegate can be nil, you may want to use the
+  # :allow_nil option. In that case, it returns nil instead of raising a
+  # NoMethodError exception:
+  #
+  #  class Foo
+  #    attr_accessor :bar
+  #    def initialize(bar = nil)
+  #      @bar = bar
+  #    end
+  #    delegate :zoo, :to => :bar
+  #  end
+  #
+  #  Foo.new.zoo   # raises NoMethodError exception (you called nil.zoo)
+  #
+  #  class Foo
+  #    attr_accessor :bar
+  #    def initialize(bar = nil)
+  #      @bar = bar
+  #    end
+  #    delegate :zoo, :to => :bar, :allow_nil => true
+  #  end
+  #
+  #  Foo.new.zoo   # returns nil
+  #
+  def delegate(*methods)
+    options = methods.pop
+    unless options.is_a?(Hash) && to = options[:to]
+      raise ArgumentError, "Delegation needs a target. Supply an options hash with a :to key as the last argument (e.g. delegate :hello, :to => :greeter)."
+    end
+
+    if options[:prefix] == true && options[:to].to_s =~ /^[^a-z_]/
+      raise ArgumentError, "Can only automatically set the delegation prefix when delegating to a method."
+    end
+
+    prefix = options[:prefix] && "#{options[:prefix] == true ? to : options[:prefix]}_"
+
+    file, line = caller.first.split(':', 2)
+    line = line.to_i
+
+    methods.each do |method|
+      on_nil =
+        if options[:allow_nil]
+          'return'
+        else
+          %(raise "#{prefix}#{method} delegated to #{to}.#{method}, but #{to} is nil: \#{self.inspect}")
+        end
+
+      module_eval(<<-EOS, file, line)
+        def #{prefix}#{method}(*args, &block)                           # def customer_name(*args, &block)
+          #{on_nil} if #{to}.nil?
+          #{to}.__send__(#{method.inspect}, *args, &block)  #   client && client.__send__(:name, *args, &block)
+        end                                                             # end
+      EOS
+    end
+  end
+end

data/lib/support/active_support_lite/object.rb

@@ -0,0 +1,9 @@
+class Object  #:nodoc:all
+
+   #:nodoc
+  def extended_by #:nodoc
+    ancestors = class << self; ancestors end
+    ancestors.select { |mod| mod.class == Module } - [ Object, Kernel ]
+  end
+    
+end

data/lib/support/active_support_lite/string.rb

@@ -0,0 +1,38 @@
+class String  #:nodoc:all
+   #:nodoc
+  def underscore
+    self.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
+
+   #:nodoc
+  def demodulize
+    gsub(/^.*::/, '')
+  end
+
+   #:nodoc
+  def constantize
+    unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ self
+      raise NameError, "#{self} is not a valid constant name!"
+    end
+    Object.module_eval("::#{$1}", __FILE__, __LINE__)
+  end
+
+   #:nodoc
+  def classify # DOES NOT SINGULARISE
+    camelize(self.sub(/.*\./, ''))
+  end
+
+   #:nodoc
+  def camelize( first_letter_in_uppercase = true)
+    if first_letter_in_uppercase
+      gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
+    else
+      first + camelize(lower_case_and_underscored_word)[1..-1]
+    end
+  end
+
+end

data/lib/support/active_support_lite/symbol.rb

@@ -0,0 +1,16 @@
+unless :to_proc.respond_to?(:to_proc)  #:nodoc:all
+  class Symbol
+    # Turns the symbol into a simple proc, which is especially useful for enumerations. Examples:
+    #
+    #   # The same as people.collect { |p| p.name }
+    #   people.collect(&:name)
+    #
+    #   # The same as people.select { |p| p.manager? }.collect { |p| p.salary }
+    #   people.select(&:manager?).collect(&:salary)
+     #:nodoc
+    def to_proc
+      Proc.new { |*args| args.shift.__send__(self, *args) }
+    end
+  end
+end
+

data/lib/support/applicable.rb

@@ -0,0 +1,41 @@
+module StateFu
+  module Applicable
+    module InstanceMethods
+
+      # if given a hash of options (or a splatted arglist containing
+      # one), merge them into @options. If given a block, eval it
+      # (yielding self if the block expects it)
+
+      def apply!( _options=nil, &block )
+        if _options.is_a?(Array)
+          _options  = _options.dup.extract_options!.symbolize_keys
+        else          
+          _options ||= {}
+          _options = _options.symbolize_keys!
+        end
+
+        @options = @options.nil?? _options : @options.merge(_options)
+        returning self do
+          if block_given?
+            case block.arity.abs
+            when 1, -1
+              instance_exec self, &block
+            when 0
+              instance_exec &block
+            else
+              raise ArgumentError, "Your block wants too many arguments!"
+            end
+          end
+        end
+      end
+    end
+
+    module ClassMethods
+    end
+
+    def self.included( mod )
+      mod.send( :include, InstanceMethods )
+      mod.extend( ClassMethods )
+    end
+  end
+end

data/lib/support/arrays.rb

@@ -0,0 +1,197 @@
+module StateFu
+
+  # Stuff shared between StateArray and EventArray
+  module ArrayWithSymbolAccessor
+
+    # Pass a symbol to the array and get the object with that .name
+    # [<Foo @name=:bob>][:bob]
+    # => <Foo @name=:bob>
+
+    def []( idx )
+      begin
+        super( idx )
+      rescue TypeError => e
+        if idx.respond_to?(:to_sym)
+          self.detect { |i| i == idx || i.respond_to?(:name) && i.name == idx.to_sym }
+        else
+          raise e
+        end
+      end
+    end
+
+    # so we can go Machine.states.names
+    # mildly helpful with irb + readline
+    def names
+      map(&:name)
+    end
+
+    # SPECME
+    def except *syms
+      reject {|el| syms.flatten.compact.map(&:to_sym).include?(el.to_sym) } #.extend ArrayWithSymbolAccessor
+    end
+
+    def only *syms
+      select {|el| syms.flatten.compact.map(&:to_sym).include?(el.to_sym) } #.extend ArrayWithSymbolAccessor
+    end
+      
+    def all
+      self
+    end
+    
+    def rand
+      self.rand
+    end
+
+  end
+
+  module TransitionArgsArray
+    attr_reader :transition
+    
+    def init(t)
+      @transition = t
+      self
+    end
+    
+    delegate :options, :to => :transition
+    delegate :binding, :to => :transition
+    delegate :machine, :to => :transition
+    delegate :origin,  :to => :transition
+    delegate :target,  :to => :transition                
+
+    def []( index )
+      begin
+        super( index )
+      rescue TypeError
+        options[index]
+      end
+    end
+    
+  end 
+  
+  # Array extender. Used by Machine to keep a list of states.
+  module StateArray
+    include ArrayWithSymbolAccessor
+
+    # is there exactly one possible event to fire, with a single
+    # target event?
+    def next?
+      raise NotImplementedError
+    end
+
+    # if next?, return the state
+    def next
+      raise NotImplementedError
+    end
+
+  end
+
+  # Array extender. Used by Machine to keep a list of events.
+  module EventArray
+    include ArrayWithSymbolAccessor
+
+    # return all events transitioning from the given state
+    def from( origin )
+      select { |e| e.respond_to?(:from?) && e.from?( origin ) }
+    end
+
+    # return all events transitioning to the given state
+    def to( target )
+      select { |e| e.respond_to?(:to?) && e.to?( target ) }
+    end
+
+    # is there exactly one possible event to fire, with a single
+    # target event?
+    def next?
+      raise NotImplementedError
+    end
+
+    # if next?, return the event
+    def next
+      raise NotImplementedError
+    end
+
+  end
+
+  module ModuleRefArray
+    def modules
+      self.map do |h|
+        case h
+        when String, Symbol
+          mod_name = h.to_s.split('/').inject(Object) do |mod, part|
+            mod = mod.const_get( part.camelize )
+          end
+        when Module
+          h
+        else
+          raise ArgumentError.new( h.class.inspect )
+        end
+      end
+    end # modules
+
+    def inject_into( obj )
+      metaclass = class << obj; self; end
+      mods = self.modules()
+      metaclass.class_eval do
+        mods.each do |mod|
+          include( mod )
+        end
+      end
+    end
+  end
+
+  # Array extender. Used by Machine to keep a list of helpers to mix into
+  # context objects.
+  module HelperArray
+    include ModuleRefArray
+  end
+
+  module ToolArray
+    include ModuleRefArray
+  end
+
+
+  module MessageArray
+    def strings
+      select { |m| m.is_a? String }
+    end
+
+    def symbols
+      select { |m| m.is_a? Symbol }
+    end
+  end
+
+  # Extend an Array with this. It's a fairly compact implementation,
+  # though it won't be super fast with lots of elements.
+  # items. Internally objects are stored as a list of
+  # [:key, 'value'] pairs.
+  module OrderedHash
+    # if given a symbol / string, treat it as a key
+    def []( index )
+      begin
+        super( index )
+      rescue TypeError
+        ( x = self.detect { |i| i.first == index }) && x[1]
+      end
+    end
+
+    # hash-style setter
+    def []=( index, value )
+      begin
+        super( index, value )
+      rescue TypeError
+        ( x = self.detect { |i| i.first == index }) ?
+        x[1] = value : self << [ index, value ].extend( OrderedHash )
+      end
+    end
+
+    # poor man's Hash.keys
+    def keys
+      map(&:first)
+    end
+
+    # poor man's Hash.values
+    def values
+      map(&:last)
+    end
+  end  # OrderedHash
+end