hexp 0.0.1 → 0.2.0

data/lib/hexp/node/rewriter.rb

@@ -0,0 +1,52 @@
+module Hexp
+  class Node
+    # Create a new Hexp node based on an existing node
+    #
+    # Rewriting in this case means iterating over the whole Hexp tree, and for
+    # each element providing zero or more elements to replace it with.
+    #
+    class Rewriter
+      include Hexp
+
+      def initialize(node, block)
+        @node, @block = node, block
+      end
+
+      def to_hexp
+        @hexp ||= H[
+          @node.tag,
+          @node.attributes,
+          @block ? rewrite_children : @node.children
+        ]
+      end
+
+      private
+
+      # Helper for rewrite
+      #
+      # @param blk [Proc] the block for rewriting
+      # @return [Array<Hexp::Node>]
+      # @api private
+      #
+      def rewrite_children
+        @node.children
+          .flat_map {|child| child.rewrite &@block   }
+          .flat_map {|child| coerce_rewrite_response(@block.(child.to_hexp, @node)) || [child] }
+      end
+
+      def coerce_rewrite_response(response)
+        return [] if response.nil?
+
+        return [response.to_hexp] if response.respond_to? :to_hexp
+        return [response.to_str]  if response.respond_to? :to_str
+
+        if response.respond_to? :to_ary
+          return [response] if response.first.is_a? Symbol
+          return response.to_ary
+        end
+
+        raise FormatError, "invalid rewrite response : #{response.inspect}, expected #{self.class} or Array, got #{response.class}"
+      end
+    end
+  end
+end

data/lib/hexp/node/selector.rb

@@ -0,0 +1,59 @@
+module Hexp
+  class Node
+    # Select nodes from a Hexp tree
+    #
+    # This is what is backing the {Hexp::Node#select} method. It serves a double
+    # purpose. At it's core it's an Enumerable for iterating over nodes that
+    # match a criterium.
+    #
+    # @example
+    #   # Loop over the nodes with class="big"
+    #   hexp.select {|el| el.class? 'big' }.each { ... }
+    #
+    # It also integrates with {Hexp::Node::Rewriter} for selective rewriting of
+    # a Hexp tree.
+    #
+    # @example
+    #   # stick all links inside a <span class="link> ... </span>
+    #   hexp.select {|el| el.tag == 'a' }.wrap(:span, class: 'link')
+    #
+    class Selector
+      include Enumerable
+
+      def initialize(node, block)
+        @node, @select_block = node, block
+      end
+
+      def rewrite(&block)
+        @node.rewrite do |node, parent|
+          if @select_block.(node)
+            block.(node, parent)
+          else
+            node
+          end
+        end
+      end
+
+      def attr(name, value)
+        rewrite do |node|
+          node.attr(name, value)
+        end
+      end
+
+      def wrap(tag, attributes = {})
+        rewrite do |node|
+          H[tag, attributes, [node]]
+        end
+      end
+
+      def each(&block)
+        return to_enum(:each) unless block_given?
+
+        @node.children.each do |child|
+          child.select(&@select_block).each(&block)
+        end
+        yield @node if @select_block.(@node)
+      end
+    end
+  end
+end

data/lib/hexp/nokogiri/equality.rb

@@ -2,6 +2,7 @@ module Hexp
   module Nokogiri
     # Used in test to see if two Nokogiri objects have the same content,
     # i.e. are equivalent as far as we are concerned
+    #
     class Equality
       CLASSES = [
         ::Nokogiri::HTML::Document,
@@ -14,6 +15,22 @@ module Hexp
         ::Nokogiri::XML::DTD,
       ]
 
+      # Create a new equality tester for two Nokogiri objects
+      #
+      # (see Hexp::Nokogiri::Equality::CLASSES for all possible objects that can
+      # be passed in)
+      #
+      # @example
+      #   doc = Nokogiri::HTML::Document.new
+      #   this_node = Nokogiri::XML::Element.new("div", doc)
+      #   that_node = Nokogiri::XML::Element.new("span", doc)
+      #   Hexp::Nokogiri::Equality.new(this_node, that_node).call #=> false
+      #
+      # @param this [Object] The first object to compare
+      # @param that [Object] The second object to compare
+      #
+      # @api public
+      #
       def initialize(this, that)
         @this, @that = this, that
         [this, that].each do |input|
@@ -21,6 +38,12 @@ module Hexp
         end
       end
 
+      # Perform the comparison
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      #
       def call
         [ equal_class?,
           equal_name?,
@@ -29,26 +52,56 @@ module Hexp
           equal_text? ].all?
       end
 
+      # Are the two elements instances of the same class
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      #
       def equal_class?
         @this.class == @that.class
       end
 
+      # Do both elements have the same tag name
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      #
       def equal_name?
         @this.name == @that.name
       end
 
+      # Do the elements under comparison have the same child elements
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      #
       def equal_children?
         return true unless @this.respond_to? :children
         @this.children.count == @that.children.count &&
           compare_children.all?
       end
 
+      # Compare the child elements, assuming both elements respond_to? :children
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      #
       def compare_children
         @this.children.map.with_index do |child, idx|
           self.class.new(child, @that.children[idx]).call
         end
       end
 
+      # Do the elements under comparison have the same attributes
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      #
       def equal_attributes?
         return true unless @this.respond_to? :attributes
         @this.attributes.keys.all? do |key|
@@ -56,6 +109,14 @@ module Hexp
         end
       end
 
+      # Compare the text of text elements
+      #
+      # If the elements are not of type Nokogiri::XML::Text, return true
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      #
       def equal_text?
         return true unless @this.instance_of?(::Nokogiri::XML::Text)
         @this.text == @that.text

data/lib/hexp/nokogiri/reader.rb

@@ -0,0 +1,27 @@
+module Hexp
+  module Nokogiri
+    # Read Nokogiri, turning it into Hexp
+    #
+    class Reader
+      # Take a Nokogiri root node and convert it to Hexp
+      #
+      # @param node [Nokogiri::XML::Element]
+      # @return [Hexp::Node]
+      # @api public
+      #
+      def call(node)
+        return node.text if node.text?
+
+        unless node.attributes.empty?
+          attrs = node.attributes.map do |key, value|
+            [key.to_sym, value.value]
+          end
+          attrs = Hash[attrs]
+        end
+
+        recurse = ->(node) { call(node) }
+        H[node.name.to_sym, attrs, node.children.map(&recurse)]
+      end
+    end
+  end
+end

data/lib/hexp/sass/selector_parser.rb

@@ -0,0 +1,4 @@
+module Hexp
+  module Sass
+  end
+end

data/lib/hexp/text_node.rb

@@ -1,26 +1,146 @@
 module Hexp
-  # Represents text inside HTML, at the moment a wrapper
-  # around a plain String. Needs work
-  class TextNode < SimpleDelegator
+  # Represents text inside HTML. Instances behave like Strings, but also support
+  # the most of `Hexp::Node` interface, so you don't have to treat them differently
+  # when traversing across trees.
+  #
+  # Strings used inside Hexp literals like `H[:span, "Hi!"]` automatically get
+  # converted to `TextNode` instances, so there is usually no reason to instantiate
+  # these yourself.
+  class TextNode < DelegateClass(String)
+    # Inspect the TextNode
+    #
+    # This delegates to the underlying String, making it
+    # non-obvious that you're dealing with something else. However, a TextNode
+    # supports the full API of String, so this might not be a big problem.
+    # The benefit is that inspection of complete nodes containing text looks
+    # nice
+    #
+    # @example
+    #   Hexp::TextNode.new("hello, world").inspect #=> "\"hello, world\""
+    #
+    # @return [String]
+    #
+    # @api public
+    #
     def inspect
       __getobj__.inspect
     end
 
-    def tree_walk
-      yield self
-    end
-
+    # The attributes of this Node
+    #
+    # Text nodes can not have attributes, so this always returns an empty Hash.
+    #
+    # @return [Hash]
+    #
+    # @api public
+    #
     def attributes
       {}.freeze
     end
 
+    # Same as inspect, used by `Hexp::Node#pp`
+    #
+    # @example
+    #   Hexp::TextNode.new("hello, world").pp #=> "\"hello, world\""
+    #
+    # @return [String]
+    #
+    # @api public
+    #
     def pp
       inspect
     end
 
-    def to_a
-      [:text, self, Hexp::List[]]
+    # The tag of this node
+    #
+    # A text node does not have a tag, so this returns nil
+    #
+    # @example
+    #   Hexp::TextNode.new("hello, world").tag #=> nil
+    #
+    # @return [NilClass]
+    #
+    # @api public
+    #
+    def tag
+    end
+
+    # Standard conversion protocol, returns self
+    #
+    # @example
+    #   Hexp::TextNode.new("hello, world").to_hexp #=> #<Hexp::TextNode "hello, world">
+    #
+    # @return [Hexp::TextNode]
+    #
+    # @api public
+    #
+    def to_hexp
+      self
     end
 
+    # Children of the node
+    #
+    # A text node has no children, this always returns an empty array.
+    #
+    # @example
+    #   Hexp::TextNode.new("hello, world").children #=> []
+    #
+    # @return [Array]
+    #
+    # @api public
+    #
+    def children
+      [].freeze
+    end
+
+    # Is this a text node?
+    #
+    # @example
+    #   Hexp::TextNode.new('foo').text? #=> true
+    #   H[:p].text? #=> false
+    #
+    # @return [TrueClass]
+    #
+    # @api public
+    #
+    def text?
+      true
+    end
+
+    # Is a certain CSS class present on this node?
+    #
+    # Text nodes have no attributes, so this always returns false.
+    #
+    # @example
+    #   Hexp::TextNode.new('foo').class?('bar') #=> false
+    #
+    # @return [FalseClass]
+    #
+    # @api public
+    #
+    def class?(klz)
+      false
+    end
+
+    # Rewrite a node
+    #
+    # See Hexp::Node#rewrite for more info. On a TextNode this simply return self.
+    #
+    # @example
+    #   tree.rewrite do |node|
+    #     H[:div, {class: 'wrap'}, node]
+    #   end
+    #
+    # @return [Hexp::TextNode]
+    #
+    # @api public
+    #
+    def rewrite(&blk)
+      self
+    end
+
+    def select(&block)
+      Node::Selector.new(self, block)
+    end
   end
 end

data/lib/hexp/version.rb

@@ -1,3 +1,3 @@
 module Hexp
-  VERSION = '0.0.1'
+  VERSION = '0.2.0'
 end

data/notes

@@ -0,0 +1,34 @@
+http://begriffs.github.io/showpiece/
+
+TODO
+====
+* Rename Hexp::Node to Hexp::Element
+* Rename Selector to Selection
+
+Issues
+======
+
+Root elements should not be treated separately
+
+A `rewrite` operation currently yields all nodes except the root node. Rewrite allows you to replace a node with zero, one or more nodes. My thinking at the time was that I wanted to make sure a single Hexp was returned, so if one could rewrite the root node that would be problematic.
+
+This however makes for a special case that is not very intuitive. When implementing `Hexp::Node::Selector` I came across this again. One can use a Selector strictly as an Enumerable
+
+```ruby
+# Find the first child element of all elements with class="strong"
+hexp.select {|el| el.class? 'strong' }.map {|el| el.children.first }
+```
+
+In this case there is no reason why that shouldn't iterate the whole tree, including the node. Other operations on `Selector` however do a Rewrite of the selected elements, and in this case the "all-except-the-root-node" limitation applies.
+
+``` ruby
+# Add class="strong" to all divs
+H[:div, [
+    [:div, 'one'],
+    [:div, 'two']
+  ]
+].select{|node| node.tag==:div}.attr('class', 'strong').to_hexp
+#=> H[:div, [H[:div, {"class"=>"strong"}, ["one"]], H[:div, {"class"=>"strong"}, ["two"]]]]
+```
+
+The top-level node is unaffected. To remove this limitation `Rewriter` will have to return a `Hexp::List` when zero or multiple elements are returned. Hexp::Node and Hexp::List will also have to implement as much as possible the same interface, so they can be largely used intechangably. This should especially be possible for all select/rewrite operations.