state-fu 0.11.1

data/lib/support/core_ext.rb

@@ -0,0 +1,90 @@
+# if ActiveSupport is absent, install a very small subset of it for
+# some convenience methods
+unless Object.const_defined?('ActiveSupport')  #:nodoc
+  Dir[File.join(File.dirname( __FILE__), 'active_support_lite','**' )].sort.each do |lib|
+    lib = File.expand_path lib
+    next unless File.file?( lib )
+    require lib
+  end
+
+  class Hash #:nodoc
+    include ActiveSupport::CoreExtensions::Hash::Keys
+  end
+end
+
+# ruby1.9 style symbol comparability for ruby1.8
+if RUBY_VERSION < "1.9"
+  class Symbol   #:nodoc
+    unless instance_methods.include?(:'<=>')
+      def <=> other
+        self.to_s <=> other.to_s
+      end
+    end
+  end
+end
+
+module ArrayToHash
+  def to_h
+    if RUBY_VERSION >= '1.8.7'
+      Hash[self]
+    else
+      inject({}) { |h, a| h[a.first] = a.last; h }
+    end
+  end
+end
+
+class Array
+  include ArrayToHash unless instance_methods.include?(:to_h)
+end
+
+class Object
+
+  def self.__define_method( method_name, &block )
+    self.class.class_eval do
+      define_method method_name, &block
+    end
+  end
+
+  def __define_singleton_method( method_name, &block )
+    (class << self; self; end).class_eval do
+      define_method method_name, &block
+    end
+  end
+
+
+  def with_methods_on(other)
+    (class << self; self; end).class_eval do
+      # we need some accounting to ensure that everything behaves itself when
+      # .with_methods_on is called more than once.
+      @_with_methods_on ||= []
+      if !@_with_methods_on.include?("method_missing_before_#{other.__id__}")
+        alias_method "method_missing_before_#{other.__id__}", :method_missing
+      end     
+      @_with_methods_on << "method_missing_before_#{other.__id__}"
+        
+      define_method :method_missing do |method_name, *args|
+        if _other.respond_to?(method_name, true)
+          _other.__send__( method_name, *args )
+        else
+          send "method_missing_before_#{other.__id__}", method_name, *args
+        end
+      end      
+    end
+
+    result = yield
+
+    (class << self; self; end).class_eval do
+      # heal the damage
+      if @_with_methods_on.pop != "method_missing_before_#{other.__id__}"
+        raise "there is no god"
+      end        
+      if !@_with_methods_on.include?("method_missing_before_#{other.__id__}")
+        alias_method :method_missing, "method_missing_before_#{other.__id__}"
+        undef_method "method_missing_before_#{other.__id__}"
+      end     
+    end
+
+    result
+  end # with_methods_on
+end
+

data/lib/support/exceptions.rb

@@ -0,0 +1,106 @@
+module StateFu
+
+  class MagicMethodError < NoMethodError
+  end
+
+  class Error < ::StandardError
+    attr_reader :binding, :options
+
+    def initialize binding, message=nil, options={}
+      @binding = binding
+      @options = options
+      super message
+    end
+    
+  end
+
+  class TransitionNotFound < Error
+    attr_reader :valid_transitions
+    attr_reader :valid_destinations    
+    DEFAULT_MESSAGE = "Transition could not be determined"
+    
+    def initialize(binding, valid_transitions, message=DEFAULT_MESSAGE, options={})
+      @valid_transitions  = valid_transitions
+      @valid_destinations = valid_transitions.map(&:destination)
+      super(binding, message, options)
+    end
+
+    def inspect
+      "<#{self.class.to_s} #{message} available=[#{valid_destinations.inspect}]>"
+    end
+    
+  end
+  
+  class TransitionError < Error
+    # TODO default message
+    attr_reader :transition
+
+    def initialize transition, message=nil, options={}
+      raise caller.inspect unless transition.is_a?(Transition)
+      @transition = transition 
+      super transition.binding, message, options
+    end
+
+    delegate :origin, :to => :transition
+    delegate :target, :to => :transition
+    delegate :event,  :to => :transition    
+    delegate :args,   :to => :transition    
+
+    # TODO capture these on initialization
+    delegate :unmet_requirements,         :to => :transition        
+    delegate :unmet_requirement_messages, :to => :transition            
+    delegate :requirement_errors,         :to => :transition            
+
+    def inspect
+      origin_name = origin && origin.name
+      target_name = target && target.name
+      event_name  = event  && event.name  
+      "<#{self.class.to_s} #{message} #{origin_name.inspect}=[#{event_name.inspect}]=>#{target_name.inspect}>"
+    end
+  end
+
+  class UnknownTarget < TransitionError
+  end
+
+  class TransitionAlreadyFired < TransitionError
+  end
+  
+  class RequirementError < TransitionError
+    include Enumerable 
+
+    delegate :each,   :to => :to_h
+    delegate :length, :to => :to_h
+    delegate :empty?, :to => :to_h
+        
+    def to_a
+      unmet_requirement_messages
+    end
+    
+    def to_h
+      requirement_errors
+    end
+    
+    def to_s
+      inspect
+    end
+    
+    def inspect
+      "<#{self.class.to_s}::#{__id__} :#{transition.origin.to_sym}-[#{transition.event.to_sym}]->:#{transition.target.to_sym} unmet_requirements=#{to_a.inspect}>"
+    end
+  end
+
+  class TransitionHalted < TransitionError
+  end
+
+  # deprecated?
+  # class Invalid Transition < TransitionError
+
+  class IllegalTransition < TransitionError
+    attr_reader :legal_transitions
+
+    def initialize transition, message=nil, valid_transitions=nil, options={}
+      @valid_transitions = valid_transitions
+      super transition, message, options
+    end    
+  end
+end

data/lib/support/has_options.rb

@@ -0,0 +1,16 @@
+module HasOptions
+  
+  def self.included(base)
+    base.class_eval do
+      attr_accessor :options
+    end
+  end
+  
+  def []v
+    options[v]
+  end
+
+  def []=v,k
+    options[v]=k
+  end
+end

data/lib/support/logger.rb

@@ -0,0 +1,165 @@
+
+require 'logger'
+module StateFu
+  #
+  # TODO - spec coverage
+  #
+  # Provide logging facilities, including the ability to use a shared logger.  
+  # Use Rails' log if running as a rails plugin; allow independent control of 
+  # StateFu log level.
+  
+  class Logger
+    cattr_accessor :prefix   # prefix for log messages
+    cattr_accessor :suppress # set true to send messages to /dev/null
+    cattr_accessor :shared
+    cattr_accessor :suppress
+    
+    DEBUG   = 0
+    INFO    = 1
+    WARN    = 2
+    ERROR   = 3
+    FATAL   = 4
+    UNKNOWN = 5
+
+    ENV_LOG_LEVEL = 'STATEFU_LOGLEVEL'
+    DEFAULT_LEVEL = INFO
+
+    DEFAULT_SHARED_LOG_PREFIX = '[StateFu] '
+
+    @@prefix    = DEFAULT_SHARED_LOG_PREFIX
+    @@logger    = nil
+    @@suppress  = false
+    @@shared    = false
+    @@log_level = nil
+
+    def self.new( logger = $stdout, options={} )
+      self.suppress = false
+      self.logger   = logger, options
+      self
+    end
+
+    def self.initial_log_level
+      if env_level = ENV[ENV_LOG_LEVEL]
+        parse_log_level( env_level )
+      else
+        DEFAULT_LEVEL
+      end
+    end
+
+    def self.level
+      @@log_level ||= initial_log_level
+    end
+
+    def self.level=( new_level )
+      @@log_level = parse_log_level(new_level)
+    end
+
+    def self.shared?
+      !! @@shared
+    end
+
+    def self.prefix
+      shared? ? @@prefix : nil
+    end
+
+    def self.logger= logger
+      set_logger logger
+    end
+
+    def self.instance
+      @@logger ||= set_logger(Logger.default_logger)
+    end
+
+    def self.suppress!
+      self.suppress = true
+    end
+
+    def self.suppressed?(severity = DEBUG)
+      suppress == true || severity < level
+    end
+
+    def self.add(severity, message = nil, progname = nil, &block)
+      severity = parse_log_level( severity )
+      return if suppressed?( severity )
+      message = [prefix, (message || (block && block.call) || progname).to_s].compact.join
+      # message = "#{message}\n" unless message[-1] == ?\n
+      instance.add( severity, message )
+    end
+
+    def self.debug   progname = nil, &block; add DEBUG,   progname, &block; end
+    def self.info    progname = nil, &block; add INFO,    progname, &block; end 
+    def self.warn    progname = nil, &block; add WARN,    progname, &block; end 
+    def self.error   progname = nil, &block; add ERROR,   progname, &block; end 
+    def self.fatal   progname = nil, &block; add FATAL,   progname, &block; end 
+    def self.unknown progname = nil, &block; add UNKNOWN, progname, &block; end 
+
+    #
+    # TODO fix these crappy methods
+    #
+    
+    # setter for logger instance
+    def self.set_logger( logger, options = { :shared => false } )
+      case logger
+      when String
+        file     = File.open(logger, File::WRONLY | File::APPEND)        
+        @@logger = Logger.activesupport_logger_available? ? ActiveSupport::BufferedLogger.new(file) : ::Logger.new(file)
+      when ::Logger
+        @@logger = logger
+      when Logger.activesupport_logger_available? && ActiveSupport::BufferedLogger
+        @@logger = logger
+      else
+        raise ArgumentError.new
+      end
+      self.shared = !!options.symbolize_keys![:shared]
+      if shared?
+        @@prefix = options[:prefix] || DEFAULT_SHARED_LOG_PREFIX
+        puts "shared :: #{@@prefix} #{prefix}"
+      end      
+      if lvl = options[:level] || options[:log_level]
+        self.level = lvl
+      end      
+      instance
+    end
+
+    private
+    
+    def self.get_logger( logr = $stdout )
+      if Object.const_defined?( "RAILS_DEFAULT_LOGGER" )
+        set_logger RAILS_DEFAULT_LOGGER, :shared => true
+      else
+        if Object.const_defined?( 'ActiveSupport' ) && ActiveSupport.const_defined?('BufferedLogger')
+          set_logger( ActiveSupport::BufferedLogger.new( logr ))
+        else
+          set_logger ::Logger.new( logr )
+        end
+      end
+    end
+
+    def self.activesupport_logger_available?
+      Object.const_defined?( 'ActiveSupport' ) && ActiveSupport.const_defined?('BufferedLogger')
+    end
+    
+    def self.default_logger
+      if Object.const_defined?( "RAILS_DEFAULT_LOGGER" )
+        RAILS_DEFAULT_LOGGER
+      else
+        $stdout
+      end
+    end
+    
+    def self.parse_log_level(input)
+      case input
+      when String, Symbol
+        const_get( input )
+      when 0,1,2,3,4,5
+        input
+      when nil
+        level
+      else
+        raise ArgumentError
+      end
+    end
+    
+  end
+end
+

data/lib/support/methodical.rb

@@ -0,0 +1,17 @@
+module StateFu
+  module Methodical
+
+    def self.__define_method( method_name, &block )
+      self.class.class_eval do
+        define_method method_name, &block
+      end
+    end
+
+    def __define_singleton_method( method_name, &block )
+      (class << object; self; end).class_eval do
+        define_method method_name, &block
+      end
+    end
+
+  end
+end

data/lib/support/no_stdout.rb

@@ -0,0 +1,55 @@
+require 'stringio'
+
+# a module for suppressing or capturing STDOUT or STDERR.
+# useful when shelling out to "noisy" applications or to suppress
+# output during tests.
+module NoStdout  #:nodoc:all
+  module InstanceMethods
+
+    # Suppresses or redirects STDOUT inside the given block.
+    # supply an IO of your own to capture STDOUT, otherwise it's put
+    # in a new StringIO object.
+    def no_stdout ( to = StringIO.new('','r+'), &block )
+      orig_stdout  = $stdout
+      $stdout      = @alt_stdout = to
+      result       = yield
+      $stdout      = orig_stdout
+      result
+    end
+
+    # returns the contents of STDOUT from the previous usage of
+    # no_stdout, or nil
+    def last_stdout
+      return nil unless @alt_stdout
+      @alt_stdout.rewind
+      @alt_stdout.read
+    end
+
+    ## COPIED FROM ABOVE ####
+
+    # Suppresses or redirects STDERR inside the given block.
+    # supply an IO of your own to capture STDERR, otherwise it's put
+    # in a new StringIO object.
+    def no_stderr ( to = StringIO.new('','r+'), &block )
+      orig_stderr  = $stderr
+      $stderr      = @alt_stderr = to
+      result       = yield
+      $stderr      = orig_stderr
+      result
+    end
+
+    # returns the contents of STDERR from the previous usage of
+    # no_stderr, or nil
+    def last_stderr
+      return nil unless @alt_stderr
+      @alt_stderr.rewind
+      @alt_stderr.read
+    end
+  end
+
+  def self.included klass
+    klass.class_eval do
+      include InstanceMethods
+    end
+  end
+end