branston 0.6.1 → 0.6.2

data/lib/branston/vendor/plugins/state_machine/lib/state_machine/assertions.rb

@@ -1,36 +0,0 @@
-module StateMachine
-  # Provides a set of helper methods for making assertions about the content
-  # of various objects
-  module Assertions
-    # Validates that the given hash *only* includes the specified valid keys.
-    # If any invalid keys are found, an ArgumentError will be raised.
-    #
-    # == Examples
-    # 
-    #   options = {:name => 'John Smith', :age => 30}
-    #   
-    #   assert_valid_keys(options, :name)           # => ArgumentError: Invalid key(s): age
-    #   assert_valid_keys(options, 'name', 'age')   # => ArgumentError: Invalid key(s): age, name
-    #   assert_valid_keys(options, :name, :age)     # => nil
-    def assert_valid_keys(hash, *valid_keys)
-      invalid_keys = hash.keys - valid_keys
-      raise ArgumentError, "Invalid key(s): #{invalid_keys.join(', ')}" unless invalid_keys.empty?
-    end
-    
-    # Validates that the given hash only includes at *most* one of a set of
-    # exclusive keys.  If more than one key is found, an ArgumentError will be
-    # raised.
-    # 
-    # == Examples
-    # 
-    #   options = {:only => :on, :except => :off}
-    #   assert_exclusive_keys(options, :only)                   # => nil
-    #   assert_exclusive_keys(options, :except)                 # => nil
-    #   assert_exclusive_keys(options, :only, :except)          # => ArgumentError: Conflicting keys: only, except
-    #   assert_exclusive_keys(options, :only, :except, :with)   # => ArgumentError: Conflicting keys: only, except
-    def assert_exclusive_keys(hash, *exclusive_keys)
-      conflicting_keys = exclusive_keys & hash.keys
-      raise ArgumentError, "Conflicting keys: #{conflicting_keys.join(', ')}" unless conflicting_keys.length <= 1
-    end
-  end
-end

data/lib/branston/vendor/plugins/state_machine/lib/state_machine/callback.rb

@@ -1,189 +0,0 @@
-require 'state_machine/guard'
-require 'state_machine/eval_helpers'
-
-module StateMachine
-  # Callbacks represent hooks into objects that allow logic to be triggered
-  # before or after a specific transition occurs.
-  class Callback
-    include EvalHelpers
-    
-    class << self
-      # Determines whether to automatically bind the callback to the object
-      # being transitioned.  This only applies to callbacks that are defined as
-      # lambda blocks (or Procs).  Some integrations, such as DataMapper, handle
-      # callbacks by executing them bound to the object involved, while other
-      # integrations, such as ActiveRecord, pass the object as an argument to
-      # the callback.  This can be configured on an application-wide basis by
-      # setting this configuration to +true+ or +false+.  The default value
-      # is +false+.
-      # 
-      # *Note* that the DataMapper and Sequel integrations automatically
-      # configure this value on a per-callback basis, so it does not have to
-      # be enabled application-wide.
-      # 
-      # == Examples
-      # 
-      # When not bound to the object:
-      # 
-      #   class Vehicle
-      #     state_machine do
-      #       before_transition do |vehicle|
-      #         vehicle.set_alarm
-      #       end
-      #     end
-      #     
-      #     def set_alarm
-      #       ...
-      #     end
-      #   end
-      # 
-      # When bound to the object:
-      # 
-      #   StateMachine::Callback.bind_to_object = true
-      #   
-      #   class Vehicle
-      #     state_machine do
-      #       before_transition do
-      #         self.set_alarm
-      #       end
-      #     end
-      #     
-      #     def set_alarm
-      #       ...
-      #     end
-      #   end
-      attr_accessor :bind_to_object
-      
-      # The application-wide terminator to use for callbacks when not
-      # explicitly defined.  Terminators determine whether to cancel a
-      # callback chain based on the return value of the callback.
-      # 
-      # See StateMachine::Callback#terminator for more information.
-      attr_accessor :terminator
-    end
-    
-    # An optional block for determining whether to cancel the callback chain
-    # based on the return value of the callback.  By default, the callback
-    # chain never cancels based on the return value (i.e. there is no implicit
-    # terminator).  Certain integrations, such as ActiveRecord and Sequel,
-    # change this default value.
-    # 
-    # == Examples
-    # 
-    # Canceling the callback chain without a terminator:
-    # 
-    #   class Vehicle
-    #     state_machine do
-    #       before_transition do |vehicle|
-    #         throw :halt
-    #       end
-    #     end
-    #   end
-    # 
-    # Canceling the callback chain with a terminator value of +false+:
-    # 
-    #   class Vehicle
-    #     state_machine do
-    #       before_transition do |vehicle|
-    #         false
-    #       end
-    #     end
-    #   end
-    attr_reader :terminator
-    
-    # The guard that determines whether or not this callback can be invoked
-    # based on the context of the transition.  The event, from state, and
-    # to state must all match in order for the guard to pass.
-    # 
-    # See StateMachine::Guard for more information.
-    attr_reader :guard
-    
-    # Creates a new callback that can get called based on the configured
-    # options.
-    # 
-    # In addition to the possible configuration options for guards, the
-    # following options can be configured:
-    # * <tt>:bind_to_object</tt> - Whether to bind the callback to the object involved.
-    #   If set to false, the object will be passed as a parameter instead.
-    #   Default is integration-specific or set to the application default.
-    # * <tt>:terminator</tt> - A block/proc that determines what callback
-    #   results should cause the callback chain to halt (if not using the
-    #   default <tt>throw :halt</tt> technique).
-    # 
-    # More information about how those options affect the behavior of the
-    # callback can be found in their attribute definitions.
-    def initialize(*args, &block)
-      options = args.last.is_a?(Hash) ? args.pop : {}
-      @methods = args
-      @methods.concat(Array(options.delete(:do)))
-      @methods << block if block_given?
-      
-      raise ArgumentError, 'Method(s) for callback must be specified' unless @methods.any?
-      
-      options = {:bind_to_object => self.class.bind_to_object, :terminator => self.class.terminator}.merge(options)
-      
-      # Proxy lambda blocks so that they're bound to the object
-      bind_to_object = options.delete(:bind_to_object)
-      @methods.map! do |method|
-        bind_to_object && method.is_a?(Proc) ? bound_method(method) : method
-      end
-      
-      @terminator = options.delete(:terminator)
-      @guard = Guard.new(options)
-    end
-    
-    # Gets a list of the states known to this callback by looking at the
-    # guard's known states
-    def known_states
-      guard.known_states
-    end
-    
-    # Runs the callback as long as the transition context matches the guard
-    # requirements configured for this callback.
-    # 
-    # If a terminator has been configured and it matches the result from the
-    # evaluated method, then the callback chain should be halted.
-    def call(object, context = {}, *args)
-      if @guard.matches?(object, context)
-        @methods.each do |method|
-          result = evaluate_method(object, method, *args)
-          throw :halt if @terminator && @terminator.call(result)
-        end
-        
-        true
-      else
-        false
-      end
-    end
-    
-    private
-      # Generates a method that can be bound to the object being transitioned
-      # when the callback is invoked
-      def bound_method(block)
-        arity = block.arity
-        
-        if RUBY_VERSION >= '1.9'
-          lambda do |object, *args|
-            object.instance_exec(*(arity == 0 ? [] : args), &block)
-          end
-        else
-          # Generate a thread-safe unbound method that can be used on any object.
-          # This is a workaround for not having Ruby 1.9's instance_exec
-          unbound_method = Object.class_eval do
-            time = Time.now
-            method_name = "__bind_#{time.to_i}_#{time.usec}"
-            define_method(method_name, &block)
-            method = instance_method(method_name)
-            remove_method(method_name)
-            method
-          end
-          
-          # Proxy calls to the method so that the method can be bound *and*
-          # the arguments are adjusted
-          lambda do |object, *args|
-            unbound_method.bind(object).call(*(arity == 0 ? [] : args))
-          end
-        end
-      end
-  end
-end

data/lib/branston/vendor/plugins/state_machine/lib/state_machine/condition_proxy.rb

@@ -1,94 +0,0 @@
-require 'state_machine/eval_helpers'
-
-module StateMachine
-  # Represents a type of module in which class-level methods are proxied to
-  # another class, injecting a custom <tt>:if</tt> condition along with method.
-  # 
-  # This is used for being able to automatically include conditionals which
-  # check the current state in class-level methods that have configuration
-  # options.
-  # 
-  # == Examples
-  # 
-  #   class Vehicle
-  #     class << self
-  #       attr_accessor :validations
-  #       
-  #       def validate(options, &block)
-  #         validations << options
-  #       end
-  #     end
-  #     
-  #     self.validations = []
-  #     attr_accessor :state, :simulate
-  #     
-  #     def moving?
-  #       self.class.validations.all? {|validation| validation[:if].call(self)}
-  #     end
-  #   end
-  # 
-  # In the above class, a simple set of validation behaviors have been defined.
-  # Each validation consists of a configuration like so:
-  # 
-  #   Vehicle.validate :unless => :simulate
-  #   Vehicle.validate :if => lambda {|vehicle| ...}
-  # 
-  # In order to scope conditions, a condition proxy can be created to the
-  # Vehicle class.  For example,
-  # 
-  #   proxy = StateMachine::ConditionProxy.new(Vehicle, lambda {|vehicle| vehicle.state == 'first_gear'})
-  #   proxy.validate(:unless => :simulate)
-  #   
-  #   vehicle = Vehicle.new     # => #<Vehicle:0xb7ce491c @simulate=nil, @state=nil>
-  #   vehicle.moving?           # => false
-  #   
-  #   vehicle.state = 'first_gear'
-  #   vehicle.moving?           # => true
-  #   
-  #   vehicle.simulate = true
-  #   vehicle.moving?           # => false
-  class ConditionProxy < Module
-    include EvalHelpers
-    
-    # Creates a new proxy to the given class, merging in the given condition
-    def initialize(klass, condition)
-      @klass = klass
-      @condition = condition
-    end
-    
-    # Hooks in condition-merging to methods that don't exist in this module
-    def method_missing(*args, &block)
-      # Get the configuration
-      if args.last.is_a?(Hash)
-        options = args.last
-      else
-        args << options = {}
-      end
-      
-      # Get any existing condition that may need to be merged
-      if_condition = options.delete(:if)
-      unless_condition = options.delete(:unless)
-      
-      # Provide scope access to configuration in case the block is evaluated
-      # within the object instance
-      proxy = self
-      proxy_condition = @condition
-      
-      # Replace the configuration condition with the one configured for this
-      # proxy, merging together any existing conditions
-      options[:if] = lambda do |*args|
-        # Block may be executed within the context of the actual object, so
-        # it'll either be the first argument or the executing context
-        object = args.first || self
-        
-        proxy.evaluate_method(object, proxy_condition) &&
-        Array(if_condition).all? {|condition| proxy.evaluate_method(object, condition)} &&
-        !Array(unless_condition).any? {|condition| proxy.evaluate_method(object, condition)}
-      end
-      
-      # Evaluate the method on the original class with the condition proxied
-      # through
-      @klass.send(*args, &block)
-    end
-  end
-end

data/lib/branston/vendor/plugins/state_machine/lib/state_machine/eval_helpers.rb

@@ -1,67 +0,0 @@
-module StateMachine
-  # Provides a set of helper methods for evaluating methods within the context
-  # of an object.
-  module EvalHelpers
-    # Evaluates one of several different types of methods within the context
-    # of the given object.  Methods can be one of the following types:
-    # * Symbol
-    # * Method / Proc
-    # * String
-    # 
-    # == Examples
-    # 
-    # Below are examples of the various ways that a method can be evaluated
-    # on an object:
-    # 
-    #   class Person
-    #     def initialize(name)
-    #       @name = name
-    #     end
-    #     
-    #     def name
-    #       @name
-    #     end
-    #   end
-    #   
-    #   class PersonCallback
-    #     def self.run(person)
-    #       person.name
-    #     end
-    #   end
-    # 
-    #   person = Person.new('John Smith')
-    #   
-    #   evaluate_method(person, :name)                            # => "John Smith"
-    #   evaluate_method(person, PersonCallback.method(:run))      # => "John Smith"
-    #   evaluate_method(person, Proc.new {|person| person.name})  # => "John Smith"
-    #   evaluate_method(person, lambda {|person| person.name})    # => "John Smith"
-    #   evaluate_method(person, '@name')                          # => "John Smith"
-    # 
-    # == Additional arguments
-    # 
-    # Additional arguments can be passed to the methods being evaluated.  If
-    # the method defines additional arguments other than the object context,
-    # then all arguments are required.
-    # 
-    # For example,
-    # 
-    #   person = Person.new('John Smith')
-    #   
-    #   evaluate_method(person, lambda {|person| person.name}, 21)                              # => "John Smith"
-    #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21)          # => "John Smith is 21"
-    #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21, 'male')  # => ArgumentError: wrong number of arguments (3 for 2)
-    def evaluate_method(object, method, *args)
-      case method
-        when Symbol
-          object.method(method).arity == 0 ? object.send(method) : object.send(method, *args)
-        when Proc, Method
-          args.unshift(object)
-          [0, 1].include?(method.arity) ? method.call(*args.slice(0, method.arity)) : method.call(*args)
-        when String
-          eval(method, object.instance_eval {binding})
-        else
-          raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
-        end
-    end
-  end
-end

data/lib/branston/vendor/plugins/state_machine/lib/state_machine/event.rb

@@ -1,252 +0,0 @@
-require 'state_machine/transition'
-require 'state_machine/guard'
-require 'state_machine/assertions'
-require 'state_machine/matcher_helpers'
-
-module StateMachine
-  # An invalid event was specified
-  class InvalidEvent < StandardError
-  end
-  
-  # An event defines an action that transitions an attribute from one state to
-  # another.  The state that an attribute is transitioned to depends on the
-  # guards configured for the event.
-  class Event
-    include Assertions
-    include MatcherHelpers
-    
-    # The state machine for which this event is defined
-    attr_accessor :machine
-    
-    # The name of the event
-    attr_reader :name
-    
-    # The fully-qualified name of the event, scoped by the machine's namespace 
-    attr_reader :qualified_name
-    
-    # The list of guards that determine what state this event transitions
-    # objects to when fired
-    attr_reader :guards
-    
-    # A list of all of the states known to this event using the configured
-    # guards/transitions as the source
-    attr_reader :known_states
-    
-    # Creates a new event within the context of the given machine
-    def initialize(machine, name) #:nodoc:
-      @machine = machine
-      @name = name
-      @qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
-      @guards = []
-      @known_states = []
-      
-      add_actions
-    end
-    
-    # Creates a copy of this event in addition to the list of associated
-    # guards to prevent conflicts across events within a class hierarchy.
-    def initialize_copy(orig) #:nodoc:
-      super
-      @guards = @guards.dup
-      @known_states = @known_states.dup
-    end
-    
-    # Creates a new transition that determines what to change the current state
-    # to when this event fires.
-    # 
-    # == Defining transitions
-    # 
-    # The options for a new transition uses the Hash syntax to map beginning
-    # states to ending states.  For example,
-    # 
-    #   transition :parked => :idling, :idling => :first_gear
-    # 
-    # In this case, when the event is fired, this transition will cause the
-    # state to be +idling+ if it's current state is +parked+ or +first_gear+
-    # if it's current state is +idling+.
-    # 
-    # To help define these implicit transitions, a set of helpers are available
-    # for slightly more complex matching:
-    # * <tt>all</tt> - Matches every state in the machine
-    # * <tt>all - [:parked, :idling, ...]</tt> - Matches every state except those specified
-    # * <tt>any</tt> - An alias for +all+ (matches every state in the machine)
-    # * <tt>same</tt> - Matches the same state being transitioned from
-    # 
-    # See StateMachine::MatcherHelpers for more information.
-    # 
-    # Examples:
-    # 
-    #   transition all => nil                               # Transitions to nil regardless of the current state
-    #   transition all => :idling                           # Transitions to :idling regardless of the current state
-    #   transition all - [:idling, :first_gear] => :idling  # Transitions every state but :idling and :first_gear to :idling
-    #   transition nil => :idling                           # Transitions to :idling from the nil state
-    #   transition :parked => :idling                       # Transitions to :idling if :parked
-    #   transition [:parked, :stalled] => :idling           # Transitions to :idling if :parked or :stalled
-    #   
-    #   transition :parked => same                          # Loops :parked back to :parked
-    #   transition [:parked, :stalled] => same              # Loops either :parked or :stalled back to the same state
-    #   transition all - :parked => same                    # Loops every state but :parked back to the same state
-    # 
-    # == Verbose transitions
-    # 
-    # Transitions can also be defined use an explicit set of deprecated
-    # configuration options:
-    # * <tt>:from</tt> - A state or array of states that can be transitioned from.
-    #   If not specified, then the transition can occur for *any* state.
-    # * <tt>:to</tt> - The state that's being transitioned to.  If not specified,
-    #   then the transition will simply loop back (i.e. the state will not change).
-    # * <tt>:except_from</tt> - A state or array of states that *cannot* be
-    #   transitioned from.
-    # 
-    # Examples:
-    # 
-    #   transition :to => nil
-    #   transition :to => :idling
-    #   transition :except_from => [:idling, :first_gear], :to => :idling
-    #   transition :from => nil, :to => :idling
-    #   transition :from => [:parked, :stalled], :to => :idling
-    #   
-    #   transition :from => :parked
-    #   transition :from => [:parked, :stalled]
-    #   transition :except_from => :parked
-    # 
-    # Notice that the above examples are the verbose equivalent of the examples
-    # described initially.
-    # 
-    # == Conditions
-    # 
-    # In addition to the state requirements for each transition, a condition
-    # can also be defined to help determine whether that transition is
-    # available.  These options will work on both the normal and verbose syntax.
-    # 
-    # Configuration options:
-    # * <tt>:if</tt> - A method, proc or string to call to determine if the
-    #   transition should occur (e.g. :if => :moving?, or :if => lambda {|vehicle| vehicle.speed > 60}).
-    #   The condition should return or evaluate to true or false.
-    # * <tt>:unless</tt> - A method, proc or string to call to determine if the
-    #   transition should not occur (e.g. :unless => :stopped?, or :unless => lambda {|vehicle| vehicle.speed <= 60}).
-    #   The condition should return or evaluate to true or false.
-    # 
-    # Examples:
-    # 
-    #   transition :parked => :idling, :if => :moving?
-    #   transition :parked => :idling, :unless => :stopped?
-    #   
-    #   transition :from => :parked, :to => :idling, :if => :moving?
-    #   transition :from => :parked, :to => :idling, :unless => :stopped?
-    # 
-    # == Order of operations
-    # 
-    # Transitions are evaluated in the order in which they're defined.  As a
-    # result, if more than one transition applies to a given object, then the
-    # first transition that matches will be performed.
-    def transition(options)
-      raise ArgumentError, 'Must specify as least one transition requirement' if options.empty?
-      
-      # Only a certain subset of explicit options are allowed for transition
-      # requirements
-      assert_valid_keys(options, :from, :to, :except_from, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
-      
-      guards << guard = Guard.new(options.merge(:on => name))
-      @known_states |= guard.known_states
-      guard
-    end
-    
-    # Determines whether any transitions can be performed for this event based
-    # on the current state of the given object.
-    # 
-    # If the event can't be fired, then this will return false, otherwise true.
-    def can_fire?(object)
-      !transition_for(object).nil?
-    end
-    
-    # Finds and builds the next transition that can be performed on the given
-    # object.  If no transitions can be made, then this will return nil.
-    def transition_for(object, requirements = {})
-      requirements[:from] = machine.states.match!(object).name unless custom_from_state = requirements.include?(:from)
-      
-      guards.each do |guard|
-        if match = guard.match(object, requirements)
-          # Guard allows for the transition to occur
-          from = requirements[:from]
-          to = match[:to].values.empty? ? from : match[:to].values.first
-          
-          return Transition.new(object, machine, name, from, to, !custom_from_state)
-        end
-      end
-      
-      # No transition matched
-      nil
-    end
-    
-    # Attempts to perform the next available transition on the given object.
-    # If no transitions can be made, then this will return false, otherwise
-    # true.
-    # 
-    # Any additional arguments are passed to the StateMachine::Transition#perform
-    # instance method.
-    def fire(object, *args)
-      machine.reset(object)
-      
-      if transition = transition_for(object)
-        transition.perform(*args)
-      else
-        machine.invalidate(object, :state, :invalid_transition, [[:event, name]])
-        false
-      end
-    end
-    
-    # Draws a representation of this event on the given graph.  This will
-    # create 1 or more edges on the graph for each guard (i.e. transition)
-    # configured.
-    # 
-    # A collection of the generated edges will be returned.
-    def draw(graph)
-      valid_states = machine.states.by_priority.map {|state| state.name}
-      guards.collect {|guard| guard.draw(graph, name, valid_states)}.flatten
-    end
-    
-    # Generates a nicely formatted description of this event's contents.
-    # 
-    # For example,
-    # 
-    #   event = StateMachine::Event.new(machine, :park)
-    #   event.transition all - :idling => :parked, :idling => same
-    #   event   # => #<StateMachine::Event name=:park transitions=[all - :idling => :parked, :idling => same]>
-    def inspect
-      transitions = guards.map do |guard|
-        guard.state_requirements.map do |state_requirement|
-          "#{state_requirement[:from].description} => #{state_requirement[:to].description}"
-        end * ', '
-      end
-      
-      "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
-    end
-    
-    protected
-      # Add the various instance methods that can transition the object using
-      # the current event
-      def add_actions
-        # Checks whether the event can be fired on the current object
-        machine.define_instance_method("can_#{qualified_name}?") do |machine, object|
-          machine.event(name).can_fire?(object)
-        end
-        
-        # Gets the next transition that would be performed if the event were
-        # fired now
-        machine.define_instance_method("#{qualified_name}_transition") do |machine, object|
-          machine.event(name).transition_for(object)
-        end
-        
-        # Fires the event
-        machine.define_instance_method(qualified_name) do |machine, object, *args|
-          machine.event(name).fire(object, *args)
-        end
-        
-        # Fires the event, raising an exception if it fails
-        machine.define_instance_method("#{qualified_name}!") do |machine, object, *args|
-          object.send(qualified_name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{machine.name} via :#{name} from #{machine.states.match!(object).name.inspect}")
-        end
-      end
-  end
-end