controll 0.2.0 → 0.3.0

data/lib/controll/{helper/event_matcher.rb → event/matcher.rb}

@@ -1,5 +1,5 @@
-module Controll::Helper
-  class EventMatcher
+module Controll
+  class Event::Matcher
     attr_reader :event
 
     def initialize event
@@ -12,7 +12,7 @@ module Controll::Helper
 
     protected
 
-    include Controll::FlowHandler::EventHelper
+    include Controll::Event::Helper
 
     def normalized events
       [events].flatten.map(&:to_sym)

data/lib/controll/event.rb

@@ -0,0 +1,60 @@
+module Controll
+  class Event
+    autoload :Helper,      'controll/event/helper'
+    autoload :Matcher,     'controll/event/matcher'    
+
+    class InvalidError < StandardError; end
+
+    attr_reader :name, :type, :options
+
+    def initialize name, *args
+      raise ArgumentError, "Event must have a name identifier" if name.blank?
+      @name     = name.to_sym
+      @options  = args.extract_options! 
+      @type     = (extract_type(args.first) || options[:type] || :notice).to_sym
+      raise ArgumentError, "Invalid type: #{@type} must be one of: #{self.class.valid_types}" unless self.class.valid_type? @type 
+      @options.delete(:type) if options[:type] == @type
+    end
+
+    def self.default_valid_types
+      [:notice, :error, :warning, :success]
+    end
+    
+    def self.valid_types
+      @valid_types ||= default_valid_types
+    end
+
+    def self.reset_types
+      @valid_types = default_valid_types
+    end
+
+    valid_types.each do |type|
+      define_method :"#{type}?" do
+        self.type == type.to_sym
+      end
+    end
+
+    class << self
+      attr_writer :valid_types
+
+      def valid_type? type
+        valid_types.map(&:to_sym).include? type.to_sym
+      end
+
+      def add_valid_types *types
+        @valid_types += types if types.all? {|type| type.kind_of? Symbol}
+      end
+    end
+
+    protected
+
+    def extract_type arg
+      return arg.type if arg.respond_to? :type
+      arg.to_sym if type? arg
+    end
+
+    def type? arg
+      arg.kind_of?(String) || arg.kind_of?(Symbol)
+    end
+  end
+end

data/lib/controll/events.rb

@@ -0,0 +1,48 @@
+module Controll
+  class Events
+    include Enumerable
+    include Controll::Event::Helper
+
+    attr_reader :events
+
+    def initialize *events
+      @events = events.flatten.map{|event| normalize event }
+    end
+
+    def each
+      events.each {|event| yield event }
+    end
+
+    def << event
+      events << event
+    end
+
+    def last
+      events.last
+    end
+
+    def self.valid_types
+      Controll::Event.valid_types
+    end
+
+    # fx error? - returns if any event of type error
+    valid_types.each do |type|
+      meth = :"#{type}?"
+      define_method meth do
+        self.any? {|event| event.send(meth) }
+      end
+    end
+
+    # fx errors - returns all events of type error
+    valid_types.each do |type|
+      meth = type.to_s.pluralize
+      define_method meth do
+        self.select {|event| event.send(:"#{type}?") }
+      end
+    end
+
+    def valid_types
+      Controll::Event.valid_types
+    end
+  end
+end

data/lib/controll/executor/base.rb

@@ -1,16 +1,12 @@
 module Controll
   module Executor
     class Base
-      attr_accessor :initiator, :options
+      attr_accessor :controller, :options
 
-      def initialize initiator, options = {}
-        @initiator = initiator
+      def initialize controller, options = {}
+        @controller = controller
         @options = options
       end
-
-      def method_missing(meth, *args, &block)
-        initiator.send(meth, *args, &block)
-      end
     end
   end
 end

data/lib/controll/executor/controlled.rb

@@ -0,0 +1,36 @@
+require 'controll/executor/base'
+
+module Controll::Executor
+  class Controlled < Delegator
+
+    def execute
+      validations
+      do_command unless error?
+    end
+
+    # return last notification or :success as result
+    # return <Event>
+    def result
+      main_event
+    end
+
+    class << self
+      def execute &block
+        define_method :execute do
+          super
+          instance_eval &block
+          result
+        end
+      end
+    end
+
+    protected
+
+    def validations
+    end
+
+    def error?
+      notifications.error?
+    end
+  end
+end

data/lib/controll/executor/delegator.rb

@@ -0,0 +1,6 @@
+module Controll
+  module Executor
+    class Delegator < Controll::Assistant
+    end
+  end
+end

data/lib/controll/executor.rb

@@ -1,6 +1,13 @@
 module Controll
   module Executor
     autoload :Base,         'controll/executor/base'
-    autoload :Notificator,  'controll/executor/notificator'
+    autoload :Controlled,   'controll/executor/controlled'
+    autoload :Delegator,    'controll/executor/delegator'
   end
+end
+
+module Executors
+  Base        = Controll::Executor::Base
+  Delegator   = Controll::Executor::Delegator
+  Controlled  = Controll::Executor::Controlled
 end

data/lib/controll/flow/action/base.rb

@@ -0,0 +1,30 @@
+module Controll::Flow::Action
+  class Base
+    attr_reader :path, :controller, :errors
+
+    def initialize controller, path
+      @controller = controller
+      @path = path.to_s
+    end
+
+    def set_errors *errors
+      @errors = errors.flatten
+    end
+
+    def errors
+      @errors |= []
+    end
+
+    protected
+
+    def controller_action
+      @controller_action ||= "do_#{type}"
+    end          
+
+    def error_check!
+      unless controller.respond_to? controller_action
+        raise Controll::NotEnabled, "Controll::Enabler has not been included in #{controller.class}. Missing #{controller_action} method"
+      end
+    end
+  end
+end

data/lib/controll/flow/action/fallback.rb

@@ -0,0 +1,25 @@
+module Controll::Flow::Action
+  class Fallback < Base
+    attr_reader :controller, :event
+
+    def initialize controller, event = nil
+      @controller = controller
+      @event = event if event
+    end
+
+    def perform      
+      error_check! if event
+      controller.do_fallback self
+    end
+    
+    def type
+      :fallback
+    end
+
+    class << self
+      def action controller, event = nil
+        self.new controller, event
+      end
+    end
+  end
+end

data/lib/controll/flow/action/path_action.rb

@@ -0,0 +1,24 @@
+module Controll::Flow::Action
+  class PathAction < Base
+    def perform
+      raise BadPathError, "Bad path: #{path}" if path.blank?
+      error_check!
+      controller.send controller_action, self
+    end
+
+    def resolved_path
+      controller.send(path)
+    end
+
+    protected
+
+    # useful for path helpers used in event maps
+    def method_missing(method_name, *args, &block)
+      if controller.respond_to? method_name
+        controller.send method_name, *args, &block
+      else
+        super
+      end
+    end
+  end
+end

data/lib/controll/flow/action.rb

@@ -0,0 +1,7 @@
+module Controll::Flow
+  module Action
+    autoload :Base,         'controll/flow/action/base'
+    autoload :PathAction,   'controll/flow/action/path_action'
+    autoload :Fallback,     'controll/flow/action/fallback'
+  end
+end

data/lib/controll/flow/action_mapper/base.rb

@@ -0,0 +1,13 @@
+module Controll::Flow::ActionMapper
+  class Base
+    class << self
+      def path_action_class
+        Controll::Flow::Action::PathAction
+      end
+
+      def action controller, event
+        raise NotImplementedError, 'You must implement the #action class method'
+      end
+    end
+  end
+end

data/lib/controll/flow/action_mapper/complex.rb

@@ -0,0 +1,52 @@
+module Controll::Flow::ActionMapper
+  class Complex < Base
+    attr_reader :event_maps
+
+    class << self
+      attr_writer :action_clazz
+      attr_reader :types, :event_maps
+
+      # this method could be generated whenever a class inherits from ActionHandler class?
+      def inherited base
+        if base.parent.respond_to? :add_action_handler
+          base.add_action_handler self.name.demodulize
+        end
+      end
+
+      def action controller, event
+        action_types ||= types
+        path = path_finder(event).path
+        path_action_class.new controller, path unless path.blank?
+      end
+
+      # reader
+      def event_map_for type = :notice
+        @event_maps ||= {}
+        event_maps[type.to_sym] || {}
+      end
+
+      # writer
+      # also auto-adds type to types
+      def event_map *args, &block
+        @event_maps ||= {}
+        @types ||= []
+        return @event_maps if args.empty? && !block_given?
+
+        type = args.first.kind_of?(Symbol) ? args.shift : :notice        
+        event_maps[type.to_sym] = block_given? ? instance_eval(&block) : args.first
+        @types << type unless types.include?(type)
+      end 
+
+      protected
+
+      def path_finder event
+        raise Controll::Flow::NoMappingFoundError, "No event maps defined" if event_maps.blank?
+        path_finder_class.new event, event_maps, types
+      end
+
+      def path_finder_class
+        Controll::Flow::EventMapper::PathFinder
+      end
+    end
+  end
+ end

data/lib/controll/flow/action_mapper/simple.rb

@@ -0,0 +1,54 @@
+module Controll::Flow::ActionMapper
+  class Simple < Base
+    NoEventsDefinedError      = Controll::Flow::NoEventsDefinedError
+    NoDefaultPathDefinedError = Controll::Flow::NoDefaultPathDefinedError
+
+    # TODO: Should combine with Redirecter style, allowing for multiple render path mappings!
+    # This is fx useful for Wizards etc. where one Controller can render to many views, depending on state
+    class << self
+      def inherited base
+        if base.parent.respond_to? :add_action_handler
+          base.add_action_handler self.name.demodulize
+        end
+      end
+
+      def action controller, event, path = nil
+        check!
+        event = normalize event
+        path_action_class.new(controller, path || default_path) if events.include? event.name
+      end
+
+      # http://bugs.ruby-lang.org/issues/1082
+      #   hello.singleton_class
+      # Instead of always having to write:
+      #   (class << hello; self; end)
+      def default_path str = nil, &block
+        (class << self; self; end).send :define_method, :default_path do 
+          block_given? ? instance_eval(&block) : str
+        end
+      end 
+
+      def events *args, &block
+        (class << self; self; end).send :define_method, :events do 
+          args.flatten
+        end
+
+        default_path(&block) if block_given?
+      end 
+
+      protected
+
+      def check!
+        unless respond_to?(:events) && !events.blank?
+          raise NoEventsDefinedError, "You must define the events/actions that can be mapped by this class" 
+        end
+
+        unless respond_to?(:default_path) && !default_path.blank?
+          raise NoDefaultPathDefinedError, "You must set a default_path to be routed to if no event/action matches"
+        end
+      end        
+
+      include Controll::Event::Helper      
+    end
+  end
+end

data/lib/controll/flow/action_mapper.rb

@@ -0,0 +1,7 @@
+module Controll::Flow
+  module ActionMapper
+    autoload :Base,      'controll/flow/action_mapper/base'
+    autoload :Simple,    'controll/flow/action_mapper/simple'
+    autoload :Complex,   'controll/flow/action_mapper/complex'
+  end
+end

data/lib/controll/flow/errors.rb

@@ -0,0 +1,16 @@
+module Controll::Flow
+  class ActionEventError          < StandardError; end
+
+  class EventNotImplementedError  < StandardError; end
+  
+  class PathActionError           < StandardError; end
+
+  # Complex mapper
+  class NoMappingFoundError   < PathActionError; end
+
+  # Simple mapper
+  class NoEventsDefinedError      < PathActionError; end
+  class NoDefaultPathDefinedError < PathActionError; end
+  
+  class BadPathError              < PathActionError; end
+end

data/lib/controll/flow/event_mapper/path_finder.rb

@@ -0,0 +1,36 @@
+module Controll::Flow
+  module EventMapper
+    class PathFinder
+      attr_accessor :event, :maps, :types
+
+      NoMappingFoundError = Controll::Flow::NoMappingFoundError
+
+      # event <Event>
+      def initialize event, maps, types = []
+        raise ArgumentError, "Event argument must not be empty" if event.blank?
+        raise ArgumentError, "Maps argument must not be empty" if maps.blank?
+        @event = normalize event
+        @types = types unless types.blank?
+        @maps = maps
+      end
+
+      def path
+        @path ||= mapper.map_event 
+      rescue StandardError => e
+        raise NoMappingFoundError, "No event mapping could be found for: #{event.inspect} in: #{maps}. Cause: #{e}"
+      end
+
+      protected
+
+      include Controll::Event::Helper
+
+      def event_map
+        @event_map ||= maps[event.type] || {}
+      end
+
+      def mapper
+        @mapper ||= Controll::Flow::EventMapper::Util.new event, event_map
+      end      
+    end
+  end
+end

data/lib/controll/flow/event_mapper/util.rb

@@ -0,0 +1,43 @@
+module Controll::Flow
+  module EventMapper
+    class Util        
+      attr_reader :event_map, :event
+
+      NoMappingFoundError = Controll::Flow::NoMappingFoundError
+
+      def initialize event, event_map
+        @event ||= normalize event
+
+        unless valid_map? event_map
+          raise ArgumentError, "Invalid redirect map: #{event_map}, must be a non-empty Hash" 
+        end
+        @event_map ||= event_map
+      end
+
+      # An event can also be a Symbol,
+      # in which case it is a :notice event
+      def map_event
+        event_map.each do |path, events|            
+          return path.to_s if valid? events
+        end
+        raise NoMappingFoundError, "No path could be found for event: #{event.inspect} in map: #{event_map}" 
+      end
+
+      protected
+
+      include Controll::Event::Helper
+
+      def valid_map? event_map
+        event_map.kind_of?(Hash) && !event_map.blank?
+      end
+
+      def valid? events
+        matcher.match?(events)
+      end
+
+      def matcher
+        @matcher ||= Controll::Event::Matcher.new event
+      end        
+    end
+  end
+end

data/lib/controll/flow/event_mapper.rb

@@ -0,0 +1,6 @@
+module Controll::Flow
+  module EventMapper
+    autoload :Util,         'controll/flow/event_mapper/util'
+    autoload :PathFinder,   'controll/flow/event_mapper/path_finder'
+  end
+end

data/lib/controll/flow/master/executor.rb

@@ -0,0 +1,57 @@
+module Controll::Flow
+  class Master    
+    class Executor < Controll::Executor::Base
+      Flow = Controll::Flow
+
+      NoEventsDefinedError  = Flow::NoEventsDefinedError
+      NoMappingFoundError   = Flow::NoMappingFoundError
+
+      attr_reader :event, :action_handlers
+        
+      def initialize initiator, options
+        raise ArgumentError, "Must take an options arg" unless options.kind_of?(Hash)
+        raise ArgumentError, "Must take an :event option" unless options[:event]
+        raise ArgumentError, "Must take an :action_handlers option" unless options[:action_handlers]
+        super
+        @event = options[:event]
+        @action_handlers = options[:action_handlers]
+      end
+
+      def execute        
+        action_handlers.each do |action_handler|
+          begin          
+            action_handler_clazz = handler_class(action_handler)
+            next unless action_handler_clazz
+            return action_handler_clazz.action(controller, event)
+          rescue NoEventsDefinedError => e
+            errors << e
+          rescue NoMappingFoundError => e
+            errors << e
+          end
+        end
+        fallback
+      end
+
+      def errors
+        @errors ||= []
+      end
+
+      protected
+
+      def fallback
+        fallback_class.new controller, event
+      end
+
+      def fallback_class
+        Flow::Action::Fallback
+      end
+
+      def handler_class action_handler
+        clazz = "#{initiator.class}::#{action_handler.to_s.camelize}"
+        clazz.constantize
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/controll/flow/master/macros.rb

@@ -0,0 +1,66 @@
+module Controll::Flow
+  class Master
+    module Macros
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def handler options = {}, &block
+          mapper_type = :simple if options[:simple]
+          mapper_type ||= :complex if options[:complex]
+
+          master_clazz = Controll::Flow::Master
+
+          unless mapper_type
+            raise ArgumentError, "You must specify mapper type, one of: #{master_clazz.mapper_types} in: #{options}" 
+          end
+
+          handler_type = options.delete(mapper_type)
+
+          unless master_clazz.valid_handler? handler_type
+            raise ArgumentError, "Must one of: #{master_clazz.valid_handlers} was: #{handler_type}"
+          end
+          
+          parent = "Controll::Flow::ActionMapper::#{mapper_type.to_s.camelize}".constantize
+
+          clazz_name = handler_type.to_s.camelize
+          context = self.kind_of?(Class) ? self : self.class
+
+          clazz = parent ? Class.new(parent) : Class.new
+          context.const_set clazz_name, clazz          
+          clazz = context.const_get(clazz_name)
+
+          container_class_name = clazz.name.sub(/\.*(::\w+)$/, '')          
+          container_class = container_class_name.constantize
+          container_class.add_action_handler clazz.name.demodulize
+
+          clazz.instance_eval(&block) if block_given?
+          clazz
+        end
+
+        def renderer mapper_type = :simple, options = {}, &block
+          handler options.merge(mapper_type => :renderer), &block
+        end
+
+        def redirecter mapper_type = :complex, options = {}, &block
+          handler options.merge(mapper_type => :redirecter), &block
+        end
+
+        def event &block
+          raise ArgumentError, "Must be called with a block" unless block_given?
+          define_method :event do
+            instance_variable_get("@event") || instance_variable_set("@event", instance_eval(&block))
+          end
+        end
+
+        # def set_action_handlers *names, &block
+        #   raise ArgumentError, "Must be called with names of action handlers" if names.empty?
+
+        #   define_method :action_handlers do
+        #     value = block_given? ? instance_eval(&block) : names.flatten
+        #     instance_variable_get("@action_handlers") || instance_variable_set("@action_handlers", value)
+        #   end
+        # end
+      end
+    end
+  end
+end