saxxy 0.1.0

data/lib/saxxy/callbacks/sax.rb

@@ -0,0 +1,86 @@
+require "forwardable"
+require "saxxy/utils/callback_array"
+require "saxxy/event_registry"
+
+
+module Saxxy
+  module Callbacks
+
+    module SAX
+      def self.included(base)
+        base.extend Forwardable
+        base.def_delegators :@event_registry, :activate_events_on, :deactivate_events_on,
+          :push_text, :register_event_from_action, :remove_actions!
+      end
+
+      def initialize(context)
+        initialize_state
+        @active_pool << context
+      end
+
+      def on_start_element(name, attrs = {})
+        register_and_activate_events_on(name, attrs)
+        activate_contexts_on(name, attrs)
+      end
+
+      def on_characters(string)
+        push_text(string || "")
+      end
+
+      def on_end_element(name)
+        deactivate_events_on(name)
+        deactivate_contexts_on(name)
+      end
+
+      def on_end_document
+        @active_pool.clear
+        @inactive_pool.clear
+        @event_registry.clear
+      end
+
+      private
+      def initialize_state
+        @event_registry = EventRegistry.new
+        @inactive_pool = CallbackArray.new.on_add(&method(:on_add_to_inactive_pool))
+        @active_pool = CallbackArray.new.on_add(&method(:on_add_to_active_pool)).on_remove(&method(:on_remove_from_active_pool))
+      end
+
+      def register_and_activate_events_on(name, attrs)
+        actions.select { |a| a.matches(name, attrs) }.each do |action|
+          register_event_from_action(action, name, attrs)
+        end
+        activate_events_on(name, attrs)
+      end
+
+      def activate_contexts_on(name, attrs)
+        @inactive_pool.each { |context| context.activate_on(name, attrs) }
+      end
+
+      def deactivate_contexts_on(name)
+        @active_pool.each { |context| context.deactivate_on(name) }
+      end
+
+      def on_add_to_inactive_pool(context)
+        context.on_activation do |context|
+          @inactive_pool >> context
+          @active_pool << context
+        end
+      end
+
+      def on_add_to_active_pool(context)
+        context.on_deactivation { |context| @active_pool >> context }
+        context.child_contexts.each { |context| @inactive_pool << context }
+      end
+
+      def on_remove_from_active_pool(context)
+        @inactive_pool << context if @active_pool.member?(context.parent_context)
+        remove_actions!(*context.actions)
+      end
+
+      def actions
+        @active_pool.flat_map(&:actions)
+      end
+    end
+
+  end
+end

data/lib/saxxy/context.rb

@@ -0,0 +1,88 @@
+require "saxxy/activatable"
+require "saxxy/node_action"
+
+
+module Saxxy
+
+  ##
+  # @author rubymaniac
+  #
+  # Context describes, semantically, an XML tag-context.
+  # For example an XML tag-context: <div>This is a context</div>
+  #
+  # Whether a tag-context is described by a Context object
+  # depends on whether the Context's activation rule matches
+  # this tag-context. Because a Context can be activated
+  # on a tag-context that matches it's activation rule
+  # it includes the "Activatable" module.
+  #
+  # A context can belong to a parent context and thus it
+  # may have a `parent_context` attribute that points to
+  # it's parent. A context may also have `child_contexts`.
+  #
+  # @!attribute [r] activation_rule
+  #   @return [NodeRule] this context's activation rule
+  #
+  # @!attribute [r|w] parent_context
+  #   @return [Context] this context's parent
+  #
+  # @!attribute [r] child_contexts
+  #   @return [Array<Context>] this context's immediate descendants
+  ##
+  class Context
+    include Activatable
+
+    attr_accessor :parent_context
+    attr_reader :child_contexts, :actions
+
+    # Initializes a context with an `activation_rule` (defaults to `nil`).
+    #
+    # @param activation_rule [NodeRule] an instance of NodeRule or nil to
+    #   declare that this context is automatically active.
+    #
+    def initialize(activation_rule = nil)
+      @child_contexts = []
+      @actions = []
+      initialize_activatable(activation_rule)
+    end
+
+    # Registers either a Context as a `child_context` by setting
+    # it's `parent_context` attribute to itself and appending it to
+    # the `child_contexts` array, or a NodeAction by appending it to
+    # the `actions` array.
+    #
+    # @param obj [Context|NodeAction] An instance of Context or
+    #   an instance of NodeAction.
+    #
+    # @return [Context] self, i.e. the context
+    #
+    def register(obj)
+      case obj
+      when Context
+        obj.parent_context = self
+        @child_contexts << obj
+      when NodeAction
+        @actions << obj
+      end
+      self
+    end
+
+    # Checks whether this context has a parent.
+    #
+    # @return [Boolean] true if it has a `parent_context`, false otherwise
+    #
+    def has_parent?
+      !parent_context.nil?
+    end
+
+    # Checks whether this context is a root context,
+    # i.e. it has no `parent_context`
+    #
+    # @return [Boolean] false if it has a `parent_context`, true otherwise
+    #
+    def root?
+      !has_parent?
+    end
+  end
+
+end

data/lib/saxxy/context_tree.rb

@@ -0,0 +1,85 @@
+require "saxxy/context"
+require "saxxy/node_action"
+require "saxxy/node_rule"
+
+
+module Saxxy
+
+  ##
+  # @author rubymaniac
+  #
+  # ContextTree describes the tree of contexts that the user
+  # eventually constructs by constraining NodeActions to be
+  # active under some Context.
+  #
+  #
+  # @!attribute [r|w] root
+  #   @return [Context] the root context of the tree
+  #
+  ##
+  class ContextTree
+    attr_accessor :root
+
+    # Initializes a ContextTree by passing an optional context to be used
+    # by the actions in order to execute their action block and a block that
+    # will be evaluated in order to create the intenal tree structure.
+    #
+    # @param ctx [Object] an object to be used by the NodeActions
+    #   in order to evaluate their block
+    #
+    # @param block [Proc] a block that will get evaluated and create
+    #   the context tree structure
+    #
+    def initialize(ctx = nil, &block)
+      self.root = Saxxy::Context.new
+      @ctx = ctx || eval("self", block.binding)
+      eval_subtree!(&block)
+    end
+
+    # Creates a Context and uses the arguments to create its activation rule. After
+    # creating the context it registers it under the current root context and returns it.
+    #
+    # @param regexp_or_string [String|Regexp] the activation rule's name
+    # @param attributes [Hash] the activation rule's attributes
+    # @param block [Proc] a block that will get evaluated and register
+    #   the child contexts and the actions
+    #
+    # @return [Context] the registered Context
+    def under(regexp_or_string, attributes = {}, &block)
+      Saxxy::Context.new(Saxxy::NodeRule.new(regexp_or_string, attributes)).tap do |context|
+        __register_context(context, &block)
+      end
+    end
+
+    # Creates a NodeAction and uses the arguments to create its activation rule and registers
+    # it under the current root context.
+    #
+    # @param regexp_or_string [String|Regexp] the activation rule's name
+    # @param attributes [Hash] the activation rule's attributes
+    # @param block [Proc] the NodeAction's action block that will get
+    #   evaluated on the passed context at construction
+    #
+    # @return [NodeAction] the registered NodeAction
+    def on(regexp_or_string, attributes = {}, &block)
+      Saxxy::NodeAction.new(Saxxy::NodeRule.new(regexp_or_string, attributes), @ctx, &block).tap do |action|
+        __register_action(action)
+      end
+    end
+
+    private
+    def eval_subtree!(&block)
+      instance_eval(&block) if block_given?
+      self.root = root.parent_context if root.has_parent?
+    end
+
+    def __register_action(action)
+      root.register(action)
+    end
+
+    def __register_context(context, &block)
+      root.register(self.root = context)
+      eval_subtree!(&block)
+    end
+  end
+
+end

data/lib/saxxy/event.rb

@@ -0,0 +1,83 @@
+require "saxxy/activatable"
+
+
+module Saxxy
+
+  ##
+  # @author rubymaniac
+  #
+  # An Event refers to a specific NodeAction and is what
+  # is registered when a NodeAction matches a specific node.
+  # Because a NodeAction may match more than one node many
+  # events, under this action, should get registered.
+  #
+  #
+  # @!attribute [r] text
+  #   @return [String] the text under the matching node
+  #
+  # @!attribute [r] attributes
+  #   @return [Hash] the attributes of the matching node
+  #
+  # @!attribute [r] element_name
+  #   @return [Hash] the name of the matching node
+  #
+  # @!attribute [r] action
+  #   @return [NodeAction] the underlying NodeAction
+  ##
+  class Event
+    include Activatable
+
+    attr_reader :text, :attributes, :element_name, :action
+
+    # Initializes an Event with an associated NodeAction
+    #
+    # @param action [NodeAction] this event's action
+    #
+    def initialize(action)
+      @action = action
+      initialize_options
+      initialize_activatable(action.activation_rule)
+    end
+
+    # Appends the argument to the event's text attribute
+    #
+    # @param text [NodeAction] the text to append
+    #
+    # @return text [String] the event's text
+    def append_text(text)
+      @text += text
+      @text
+    end
+
+    # Merges the argument hash to the event's attributes
+    #
+    # @param attrs [Hash] the attributes to merge
+    #
+    # @return attributes [Hash] the event's attributes
+    def merge_attributes(attrs)
+      @attributes.merge!(attrs)
+    end
+
+    # Changes the element_name
+    #
+    # @param name [String] the new element_name
+    #
+    # @return element_name [String] the event's element_name
+    def set_element_name(name)
+      @element_name = name
+    end
+
+    # Calls the action with the text, element_name, attributes
+    def fire
+      action.call(text, element_name, attributes)
+    end
+
+    private
+    def initialize_options
+      @text = ""
+      @element_name = nil
+      @attributes = {}
+    end
+  end
+
+end

data/lib/saxxy/event_registry.rb

@@ -0,0 +1,122 @@
+require "saxxy/event"
+
+
+module Saxxy
+
+  ##
+  # @author rubymaniac
+  #
+  # The Event Registry is in charge of registering new events
+  # and firing the event callback whenever a specific event gets
+  # deactivated.
+  #
+  # The registry has an @actions instance variable that holds
+  #
+  ##
+  class EventRegistry
+
+    # Initializes an empty Event Registry
+    #
+    def initialize
+      clear
+    end
+
+    # Registers an event into the registry by initializing it and setting
+    # its element_name and attributes accordingly.
+    #
+    # @param action [NodeAction] the action under which the event is registered
+    # @param name [String] the element_name for the event
+    # @param attributes [Hash] the attributes for the event
+    #
+    # @return event [Event] the registered event
+    #
+    def register_event_from_action(action, name = nil, attributes = {})
+      new_event_for(action).tap do |e|
+        e.set_element_name(name)
+        e.merge_attributes(attributes)
+        self[action] << e
+      end
+    end
+
+    # Loops through the active actions (those registered) and takes the last,
+    # i.e. active, event.
+    #
+    # @return events [Array] all the active events
+    #
+    def events
+      @actions.values.map(&:last)
+    end
+
+    # Appends the text on every active event
+    #
+    # @param text [String] the text to append
+    #
+    # @return events [Array] all the active events
+    #
+    def push_text(text)
+      send_on_each_event(:append_text, text)
+    end
+
+    # Deactivate the active events on a specific node
+    #
+    # @param element_name [String] the element name
+    #
+    # @return events [Array] all the active events
+    #
+    def deactivate_events_on(element_name)
+      send_on_each_event(:deactivate_on, element_name)
+    end
+
+    # Activate the active events on a specific node. This is done
+    # in order to increase the events' internal counter.
+    #
+    # @param element_name [String] nodes' element name
+    # @param attributes [Hash] nodes' attributes
+    #
+    # @return events [Array] all the active events
+    #
+    def activate_events_on(element_name, attributes)
+      send_on_each_event(:activate_on, element_name, attributes)
+    end
+
+    # Deletes the provided actions from the @actions without
+    # firing any callbacks.
+    #
+    # @param actions [Array] actions to be removed
+    #
+    # @return actions [Hash] the registered actions
+    #
+    def remove_actions!(*actions)
+      actions.each { |a| @actions.delete(a) }
+      @actions
+    end
+
+    # Clears all registered actions
+    #
+    def clear
+      @actions = {}
+    end
+
+    private
+    def new_event_for(action)
+      Saxxy::Event.new(action).on_deactivation do |ev|
+        ev.fire
+        unregister_event(action, ev)
+      end
+    end
+
+    def unregister_event(action, event)
+      self[action].delete(event)
+      self[action].last ? self[action].last.append_text(event.text) : @actions.delete(action)
+    end
+
+    def [](action)
+      @actions[action] ||= []
+    end
+
+    def send_on_each_event(method, *args)
+      events.each { |e| e.public_send(method, *args) }
+    end
+  end
+
+end