arbre2 2.1.0

data/lib/arbre/element/building.rb

@@ -0,0 +1,151 @@
+module Arbre
+  class Element
+
+    # Dynamic module onto which builder methods can be defined.
+    module BuilderMethods
+    end
+
+    # Element building concern. Contains methods pertaining to building and inserting child
+    # elements.
+    module Building
+
+      ######
+      # Builder methods
+
+        def self.included(klass)
+          klass.send :include, BuilderMethods
+          klass.send :extend, BuilderMethod
+        end
+
+      ######
+      # Builder method DSL
+
+        module BuilderMethod
+
+          def builder_method(method_name)
+            BuilderMethods.class_eval <<-EOF, __FILE__, __LINE__
+              def #{method_name}(*args, &block)
+                insert ::#{self.name}, *args, &block
+              end
+            EOF
+          end
+
+        end
+
+      ######
+      # Building & inserting elements
+
+        # Builds an element of the given class using the given arguments and block, in the
+        # same arbre context as this element.
+        def build(klass, *args, &block)
+          element = klass.new(arbre_context)
+          within(element) { element.build! *args, &block }
+          element
+        end
+
+        # Builds an element of the given class using the given arguments and block, in the
+        # same arbre context as this element, and adds it to the current arbre element's
+        # children.
+        def insert(klass, *args, &block)
+          element = klass.new(arbre_context)
+          current_element.insert_child element
+          within(element) { element.build! *args, &block }
+          element
+        end
+
+      ######
+      # Flow
+
+        # Executes a block within the context of the given element, or DOM query.
+        def append_within(element, &block)
+          element = find(element).first if element.is_a?(String)
+          arbre_context.with_current element: element, flow: :append, &block
+        end
+        alias_method :within, :append_within
+
+        # Executes a block within the context of the given element, or DOM query. All elements
+        # are prepended.
+        def prepend_within(element, &block)
+          element = find(element).first if element.is_a?(String)
+          arbre_context.with_current element: element, flow: :prepend, &block
+        end
+
+        %w(append prepend).each do |flow|
+          class_eval <<-RUBY, __FILE__, __LINE__+1
+            def #{flow}(klass = nil, *args, &block)
+              arbre_context.with_current element: current_element, flow: :#{flow} do
+                insert_or_call_block klass, *args, &block
+              end
+            end
+          RUBY
+        end
+
+        %w(after before).each do |flow|
+          class_eval <<-RUBY, __FILE__, __LINE__+1
+            def #{flow}(element, klass = nil, *args, &block)
+              element = find(element).first if element.is_a?(String)
+
+              arbre_context.with_current element: element.parent, flow: [ :#{flow}, element ] do
+                insert_or_call_block klass, *args, &block
+              end
+            end
+          RUBY
+        end
+
+        def insert_or_call_block(klass, *args, &block)
+          if klass
+            insert klass, *args, &block
+          else
+            yield
+          end
+        end
+        private :insert_or_call_block
+
+        # Inserts a child element at the right place in the child array, taking the current
+        # flow into account.
+        def insert_child(child)
+          case current_flow
+          when :append
+            children << child
+
+          when :prepend
+            children.insert_at 0, child
+
+            # Update the flow - the next element should be added after this one, not be
+            # prepended.
+            arbre_context.replace_current_flow [:after, child]
+
+          else
+            # flow: [ :before, element ] or [ :after, element ]
+            operation, element = current_flow
+            children.send :"insert_#{operation}", element, child
+
+            if operation == :after
+              # Now that we've inserted something after the element, we need to
+              # make sure that the next element we insert will be after this one.
+              arbre_context.replace_current_flow [:after, child]
+            end
+          end
+        end
+
+      ######
+      # Support methods
+
+        # Builds a temporary container using the given block, but doesn't add it to the tree.
+        # The block is executed within the current context.
+        def temporary(&block)
+          build Element, &block
+        end
+
+        def current_element
+          arbre_context.current_element
+        end
+
+        def current_flow
+          arbre_context.current_flow
+        end
+
+    end
+
+  end
+end

data/lib/arbre/element.rb

@@ -0,0 +1,194 @@
+require 'arbre/element/building'
+require 'arbre/html/querying'
+
+module Arbre
+
+  # Base class for all Arbre elements. Rendering is not implemented, and should be implemented
+  # by subclasses.
+  class Element
+    include Building
+    include Html::Querying
+
+    ######
+    # Initialization
+
+      # Initializes a new Arbre element. Pass an existing Arbre context to re-use it.
+      def initialize(arbre_context = Arbre::Context.new)
+        @_arbre_context = arbre_context
+        @_children = ChildElementCollection.new(self)
+
+        expose_assigns
+      end
+
+    ######
+    # Context
+
+      def arbre_context
+        @_arbre_context
+      end
+
+      def assigns
+        arbre_context.assigns
+      end
+
+      def helpers
+        arbre_context.helpers
+      end
+
+    ######
+    # Hierarchy
+
+      def parent
+        @_parent
+      end
+      def parent=(parent)
+        @_parent = parent
+      end
+
+      def children
+        @_children
+      end
+
+      # Removes this element from its parent.
+      def remove!
+        parent.children.remove self if parent
+      end
+
+      def <<(child)
+        children << child
+      end
+
+      def has_children?
+        children.any?
+      end
+
+      def empty?
+        !has_children?
+      end
+
+      def orphan?
+        !parent
+      end
+
+      # Retrieves all ancestors (ordered from near to far) for this element.
+      # @return [ElementCollection]
+      def ancestors
+        ancestors = ElementCollection.new
+
+        unless orphan?
+          ancestors << parent
+          ancestors.concat parent.ancestors
+        end
+
+        ancestors
+      end
+
+      # Retrieves all descendants (in prefix form) for this element.
+      # @return [ElementCollection]
+      def descendants
+        descendants = ElementCollection.new
+        children.each do |child|
+          descendants << child
+          descendants.concat child.descendants
+        end
+
+        descendants
+      end
+
+    ######
+    # Content
+
+      def content=(content)
+        children.clear
+        case content
+        when Element
+          children << content
+        when ElementCollection
+          children.concat content
+        else
+          children << TextNode.from_string(content.to_s)
+        end
+      end
+
+      def content
+        children.to_s
+      end
+
+    ######
+    # Set operations
+
+      def +(element)
+        if element.is_a?(Enumerable)
+          ElementCollection.new([self] + element)
+        else
+          ElementCollection.new([ self, element])
+        end
+      end
+
+    ######
+    # Building & rendering
+
+      # Override this method to build your element.
+      def build!
+        yield self if block_given?
+
+        self
+      end
+
+      def indent_level
+        if parent
+          parent.indent_level + 1
+        else
+          0
+        end
+      end
+
+      def to_s
+        content
+      end
+
+      def to_html
+        to_s
+      end
+
+      # Provide a clean element description when inspect is used.
+      def inspect
+        "#<#{self.class.name}:0x#{object_id.to_s(16)}>"
+      end
+
+    ######
+    # Helpers & assigns accessing
+
+      def respond_to?(method, include_private = false)
+        super || (helpers && helpers.respond_to?(method))
+      end
+
+      private
+
+      # Exposes the assigns from the context as instance variables to the given target.
+      def expose_assigns
+        assigns.each do |key, value|
+          instance_variable_set "@#{key}", value
+        end
+      end
+
+      # Access helper methods from any Arbre element through its context.
+      def method_missing(name, *args, &block)
+        if helpers && helpers.respond_to?(name)
+          define_helper_method name
+          send name, *args, &block
+        else
+          super
+        end
+      end
+
+      def define_helper_method(name)
+        self.class.class_eval <<-RUBY, __FILE__, __LINE__+1
+          def #{name}(*args, &block)
+            helpers.send :#{name}, *args, &block
+          end
+        RUBY
+      end
+
+  end
+end

data/lib/arbre/element_collection.rb

@@ -0,0 +1,93 @@
+module Arbre
+
+  class ElementCollection
+
+    ######
+    # Initialization
+
+      def initialize(elements = [])
+        @elements = elements.to_a
+      end
+
+    ######
+    # Array proxy
+
+      include Enumerable
+      delegate :each, :empty?, :length, :size, :count, :last, :to => :@elements
+      delegate :clear, :to => :@elements
+
+      def [](*args)
+        result = @elements[*args]
+        result = self.class.new(result) if result.is_a?(Enumerable)
+        result
+      end
+
+      def add(element)
+        @elements << element unless include?(element)
+        self
+      end
+      def <<(element)
+        add element
+      end
+
+      def concat(elements)
+        elements.each do |element|
+          self << element
+        end
+      end
+
+      def remove(element)
+        @elements.delete element
+      end
+
+      def to_ary
+        @elements
+      end
+      def to_a
+        @elements.dup
+      end
+
+      def ==(other)
+        to_a == other.to_a
+      end
+
+      def eql?(other)
+        other.is_a?(ElementCollection) && self == other
+      end
+
+    ######
+    # Set operations
+
+      def +(other)
+        self.class.new((@elements + other).uniq)
+      end
+
+      def -(other)
+        self.class.new(@elements - other)
+      end
+
+      def &(other)
+        self.class.new(@elements & other)
+      end
+
+    ######
+    # String conversion
+
+      def to_s
+        html_safe_join(map(&:to_s), "\n")
+      end
+
+      private
+
+      def html_safe_join(array, delimiter = '')
+        ActiveSupport::SafeBuffer.new.tap do |str|
+          array.each_with_index do |element, i|
+            str << delimiter if i > 0
+            str << element
+          end
+        end
+      end
+
+  end
+
+end

data/lib/arbre/html/attributes.rb

@@ -0,0 +1,91 @@
+module Arbre
+  module Html
+
+    # HTML attributes hash. Behaves like a hash with some minor differences:
+    #
+    # - Indifferent access: everything is stored as strings, but also values.
+    # - Setting an attribute to +true+ sets it to the name of the attribute, as per the HTML
+    #   standard.
+    # - Setting an attribute to +false+ or +nil+ will remove it.
+    class Attributes
+
+      def initialize(attributes = {})
+        @attributes = {}
+        update attributes
+      end
+
+      def self.[](*args)
+        Attributes.new(Hash[*args])
+      end
+
+      def [](attribute)
+        if attribute.to_s == 'class'
+          @attributes['class'] ||= ClassList.new
+        else
+          @attributes[attribute.to_s]
+        end
+      end
+      def []=(attribute, value)
+        if attribute.to_s == 'class'
+          if value.present?
+            @attributes['class'] = ClassList.new(value)
+          else
+            remove 'class'
+          end
+        elsif value == true
+          @attributes[attribute.to_s] = attribute.to_s
+        elsif value
+          @attributes[attribute.to_s] = value.to_s
+        else
+          remove attribute
+        end
+      end
+
+      def remove(attribute)
+        @attributes.delete attribute.to_s
+      end
+
+      def update(attributes)
+        attributes.each { |k, v| self[k] = v }
+      end
+
+      def ==(other)
+        to_hash == other.to_hash
+      end
+
+      def eql?(other)
+        other.is_a?(Attributes) && self == other
+      end
+
+      def has_key?(key)
+        @attributes.has_key?(key.to_s)
+      end
+
+      include Enumerable
+      delegate :each, :empty?, :length, :size, :count, :to => :@attributes
+
+      def pairs
+        map do |name, value|
+          next if name == 'class' && value.blank?
+          "#{html_escape(name)}=\"#{html_escape(value)}\""
+        end
+      end
+
+      def to_hash
+        @attributes
+      end
+
+      def to_s
+        pairs.join(' ').html_safe
+      end
+
+      protected
+
+      def html_escape(s)
+        ERB::Util.html_escape(s)
+      end
+
+    end
+
+  end
+end

data/lib/arbre/html/class_list.rb

@@ -0,0 +1,53 @@
+require 'set'
+
+module Arbre
+  module Html
+
+    # Holds a set of classes
+    class ClassList < Set
+
+      def initialize(classes = [])
+        super()
+        [*classes].each do |cls|
+          add cls
+        end
+      end
+
+      # Alias to the list itself.
+      def classes
+        self
+      end
+
+      # Adds one ore more classes to the list. You can pass in a string which is split by space, or
+      # an array of some kind.
+      def add(classes)
+        classes = classes.to_s.split(' ')
+        classes.each { |cls| super cls }
+        self
+      end
+      alias << add
+
+      def remove(classes)
+        classes = classes.split(' ')
+        classes.each { |cls| delete cls }
+        self
+      end
+      private :delete
+
+      def concat(classes)
+        classes.each { |cls| add cls }
+        self
+      end
+
+      def ==(other)
+        to_a.sort == other.to_a.sort
+      end
+
+      def to_s
+        to_a.join(' ')
+      end
+
+    end
+
+  end
+end

data/lib/arbre/html/comment.rb

@@ -0,0 +1,47 @@
+module Arbre
+  module Html
+
+    class Comment < Element
+      builder_method :comment
+
+      attr_accessor :comment
+
+      def build!(comment = nil)
+        @comment = comment
+      end
+
+      def to_s
+        spaces = (' ' * indent_level * Tag::INDENT_SIZE)
+
+        out = ActiveSupport::SafeBuffer.new
+
+        if !comment
+          out << '<!-- -->'.html_safe
+        elsif comment.include?("\n")
+          out << spaces << '<!--'.html_safe
+          out << "\n"
+          out << indent_comment
+          out << "\n"
+          out << spaces << '-->'.html_safe
+        else
+          out << '<!-- '.html_safe << comment << ' -->'.html_safe
+        end
+
+        out
+      end
+
+      private
+
+      def indent_comment
+        ActiveSupport::SafeBuffer.new.tap do |out|
+          comment.split("\n").each_with_index.map do |line, index|
+            out << "\n" unless index == 0
+            out << (' ' * (indent_level+1) * Tag::INDENT_SIZE) << line
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/arbre/html/document.rb

@@ -0,0 +1,93 @@
+module Arbre
+  module Html
+
+    # Root tag for any Html document.
+    #
+    # Represents the combination of a doctype, a +head+ tag and a +body+ tag.
+    class Document < Tag
+
+      ######
+      # Initialization
+
+        def initialize(*)
+          super
+        end
+
+      ######
+      # Building
+
+        def build!
+          append_head
+          append_body
+
+          within body do
+            yield self if block_given?
+          end
+        end
+
+        private
+
+        # Builds up a default head tag.
+        def append_head
+          @_head = append(Head) do
+            meta :"http-equiv" => "Content-Type", :content => "text/html; charset=utf-8"
+          end
+        end
+
+        # Builds up a default body tag.
+        def append_body
+          @_body = append(Body)
+        end
+
+        public
+
+      ######
+      # Head & body accessors
+
+        def title
+          @title ||= title_tag.content
+        end
+
+        def title=(title)
+          @title = title_tag.content = title
+        end
+
+        def title_tag
+          head.find_first('> title') || within(head) { prepend Title }
+        end
+        private :title_tag
+
+        # Adds content to the head tag and/or returns it.
+        def head(&block)
+          within @_head, &block if block_given?
+          @_head
+        end
+
+        # Adds content to the body tag and/or returns it.
+        def body(&block)
+          within @_body, &block if block_given?
+          @_body
+        end
+
+      ######
+      # Rendering
+
+        def tag_name
+          'html'
+        end
+
+        def doctype
+          '<!DOCTYPE html>'.html_safe
+        end
+
+        def to_s
+          out = ActiveSupport::SafeBuffer.new
+          out << doctype
+          out << "\n\n"
+          out << super
+        end
+
+    end
+
+  end
+end