hexp 0.2.0 → 0.3.0

data/lib/hexp/node/children.rb

@@ -5,16 +5,30 @@ module Hexp
     module Children
       # Is this node an empty node
       #
-      # H[:p, class: 'foo'].empty? #=> true
-      # H[:p, [H[:span]].empty?    #=> false
+      # @example
+      #   H[:p, class: 'foo'].empty? #=> true
+      #   H[:p, [H[:span]].empty?    #=> false
       #
-      # @return [Boolean] true if this node has no children
-      # @api public
+      # @return [true,false]
+      #   True if this node has no children
       #
+      # @api public
       def empty?
         children.empty?
       end
 
+      # Add a child node to the end of the list of children
+      #
+      # @example
+      #   H[:ul].add_child(H[:li, "chunky"]) #=> H[:ul, [H[:li, "chunky]]]
+      #
+      # @param [Hexp::Node] child
+      #   The child node to add
+      #
+      # @return [Hexp::Node]
+      #   A new node containing that has the child added to its children
+      #
+      # @api public
       def add_child(child)
         H[
           self.tag,
@@ -25,16 +39,57 @@ module Hexp
       alias :add :add_child
       alias :<< :add_child
 
+      # All the text in this node and its descendants
+      #
+      # Concatenates the contents of all text nodes.
+      #
+      # @example
+      #   H[:div, [
+      #       H[:span, "My name is"],
+      #       " ",
+      #       H[:strong, "@plexus"],
+      #       "."
+      #     ]
+      #   ].text #=> "My name is @plexus."
+      #
+      # @return [String]
+      #
+      # @api public
       def text
         children.map do |node|
           node.text? ? node : node.text
         end.join
       end
 
+      # Replace the children of this node with a new list of children
+      #
+      # @example
+      #   H[:div, "Hello"].set_children([H[:span, "wicked!"], H[:br]])
+      #   # => H[:div, [H[:span, "wicked!"], H[:br]]]
+      #
+      # @param [Array,Hexp::NodeList] new_children
+      #
+      # @return [Hexp::Node]
+      #
+      # @api public
       def set_children(new_children)
         H[tag, attributes, new_children]
       end
 
+      # Perform an action on each child node, and replace the node with the result
+      #
+      # @example
+      #   H[:div, [H[:span, "foo"]]].map_children do |node|
+      #     node.add_class(node.text)
+      #   end
+      #   # => H[:div, [H[:span, {class: "foo"}, "foo"]]]
+      #
+      # @yieldparam [Hexp::Node]
+      #   The child node
+      #
+      # @return [Hexp::Node]
+      #
+      # @api public
       def map_children(&blk)
         return to_enum(:map_children) unless block_given?
         H[tag, attributes, children.map(&blk)]

data/lib/hexp/node/css_selection.rb

@@ -2,15 +2,74 @@ module Hexp
   class Node
     # Select nodes using CSS selectors
     #
-    class CssSelection < Selector
+    # The main interface to this is {Hexp::Node#select}, although there's
+    # nothing stopping you from using this class directly.
+    #
+    # This class is +Enumerable+, and calling {#each} without a block will give
+    # you an +Enumerator+, so you have all Ruby's tasty list operations at your
+    # disposal.
+    #
+    # Only a subset of the
+    # {http://www.w3.org/TR/css3-selectors/ CSS 3 selector syntax}
+    # is supported. Parsing a selector that contains unsupported elements
+    # should raise an exception.
+    #
+    # * tag selector : +div+, +a+, +section+
+    # * class selector : +.big+, +.user_profile+
+    # * id selector : +#main_content+, +#sidebar+
+    # * attribute selectors : +[href]+, +[class~=foo]+, +[lang|=en]+
+    #
+    # Attribute selectors support
+    # {http://www.w3.org/TR/css3-selectors/#attribute-selectors all the operators of the CSS 3 spec}
+    #, so have a look there for more details.
+    #
+    # Of course you can combine all these.
+    #
+    # @example
+    #   link = H[:a, {class: 'foo bar', lang: 'fr-be', href: 'http://example.com'}, "Hello, World"]
+    #   node = H[:div, {class: 'wrap'}, link]
+    #   node.select('div.wrap a.foo.bar[lang|=fr][href^=http]') do |a|
+    #     p a.text
+    #   end
+    #
+    class CssSelection < Selection
+      include Enumerable
+
+      # Create a new CssSelection based on a root node and a selector
+      #
+      # The selector can be unparsed (a plain +String+), or parsed. This class
+      # works recursively by passing a subset of the parsed selector to a subset
+      # of the tree, hence why this matters.
+      #
+      # @param [Hexp::Node] node
+      #   Root node of the tree
+      #
+      # @param [String,Hexp::CssSelector::CommaSequence] css_selector
+      #   CSS selector
+      #
+      # @api public
       def initialize(node, css_selector)
-        @node, @css_selector = node, css_selector
+        @node, @css_selector = node.to_hexp, css_selector.freeze
       end
 
+      # Debugging representation
+      #
+      # @return [String]
+      #
+      # @api public
       def inspect
         "#<#{self.class} @node=#{@node.inspect} @css_selector=#{@css_selector.inspect} matches=#{node_matches?}>"
       end
 
+      # Iterate over the nodes that match
+      #
+      # @yieldparam [Hexp::Node]
+      #   Each matching node
+      #
+      # @return [Enumerator,CssSelection]
+      #   Enumerator if no block is given, or self
+      #
+      # @api public
       def each(&block)
         return to_enum(:each) unless block_given?
 
@@ -18,8 +77,17 @@ module Hexp
           next_selection_for(child).each(&block)
         end
         yield @node if node_matches?
+        self
       end
 
+      # Replace / alter each node that matches
+      #
+      # @yieldparam [Hexp::Node]
+      #   Each matching node
+      #
+      # @return [Hexp::Node]
+      #
+      # @api private
       def rewrite(&block)
         return @node if @node.text?
 
@@ -35,29 +103,67 @@ module Hexp
 
       private
 
+      # The CSS selector, parsed to a comma sequence
+      #
+      # @return [Hexp::CssSelector::CommaSequence]
+      #
+      # @api private
       def comma_sequence
-        @comma_sequence ||= coerce_to_comma_sequence(@css_selector)
+        @comma_sequence ||= parse_selector
       end
 
-      def coerce_to_comma_sequence(css_selector)
-        return css_selector if css_selector.is_a? CssSelector::CommaSequence
+      # Parse the CSS selector, if it isn't in a parsed form already
+      #
+      # @return [Hexp::CssSelector::CommaSequence]
+      #
+      # @api private
+      def parse_selector
+        return @css_selector if @css_selector.is_a? CssSelector::CommaSequence
         CssSelector::Parser.call(@css_selector)
       end
 
+      # Is the current node part of the selection
+      #
+      # @return [true,false]
+      #
+      # @api private
       def node_matches?
         comma_sequence.matches?(@node)
       end
 
-      # returns a new commasequence with the parts removed that have been consumed by matching
-      # against this node. If no part matches, return nil
+      # Consume the matching part of the comma sequence, return the rest
+      #
+      # Returns a new comma sequence with the parts removed that have been
+      # consumed by matching against this node. If no part matches, returns nil.
+      #
+      # @return [Hexp::CssSelector::CommaSequence]
+      #
+      # @api private
       def next_comma_sequence
         @next_comma_sequence ||= CssSelector::CommaSequence.new(consume_matching_heads)
       end
 
+      # Recurse down a child down, passing in the remaining part of the selector
+      #
+      # @param [Hexp::Node] child
+      #   One of the children of the node in this selection object
+      #
+      # @return [Hexp::Node::CssSelection]
+      #
+      # @api private
       def next_selection_for(child)
         self.class.new(child, next_comma_sequence)
       end
 
+      # For each sequence in the comma sequence, remove the head if it matches
+      #
+      # For example, if this node is a `H[:div]`, and the selector is
+      # `span.foo, div a[:href]`, then the result of this method will be
+      # `span.foo, a[:href]`. This can then be used to match any child nodes.
+      #
+      # @return [Hexp::CssSelector::CommaSequence]
+      #
+      # @api private
       def consume_matching_heads
         comma_sequence.members.flat_map do |sequence|
           if sequence.head_matches? @node

data/lib/hexp/node/domize.rb

@@ -9,16 +9,18 @@ module Hexp
       # The resulting DOM Document
       #
       # @return [Nokogiri::HTML::Document]
-      # @api private
       #
+      # @api private
       attr_reader :dom
 
       # Instanitiate a Domizer
       #
-      # @param hexp [Hexp::Node]
-      # @param options [Hash] :include_doctype defaults to true
-      # @api private
+      # @param [Hexp::Node] hexp
       #
+      # @param [Hash] options
+      # @options options [true,false] :include_doctype Defaults to true
+      #
+      # @api private
       def initialize(hexp, options = {})
         @dom     = Hexp::DOM
         @raw     = hexp
@@ -28,10 +30,14 @@ module Hexp
       # Turn the hexp into a DOM
       #
       # @return [Nokogiri::HTML::Document]
-      # @api private
       #
+      # @api private
       def call
         @doc  = dom::Document.new
+        if @options[:html5]
+          @doc.children = dom::NodeSet.new(@doc, [])
+          @doc.create_internal_subset(nil, nil, nil)
+        end
         @root = domize(@raw)
         @doc << @root
 
@@ -46,10 +52,11 @@ module Hexp
 
       # Turn a Hexp::Node into a Document
       #
-      # @param hexp [Hexp::Node]
+      # @param [Hexp::Node] hexp
+      #
       # @return [Nokogiri::HTML::Document]
-      # @api private
       #
+      # @api private
       def domize(hexp)
         dom::Node.new(hexp.tag.to_s, @doc).tap do |node|
           set_attributes(node, hexp.attributes)
@@ -59,11 +66,12 @@ module Hexp
 
       # Set attributes on a DOM node
       #
-      # @param node [Nokogiri::XML::Element]
-      # @param attributes [Hash]
+      # @param [Nokogiri::XML::Element] node
+      # @param [Hash] attributes
+      #
       # @return [void]
-      # @api private
       #
+      # @api private
       def set_attributes(node, attributes)
         attributes.each do |key,value|
           node[key] = value
@@ -72,11 +80,12 @@ module Hexp
 
       # Set children on the DOM node
       #
-      # @param node [Nokogiri::XML::Element]
-      # @param children [Hexp::List]
+      # @param [Nokogiri::XML::Element] node
+      # @param [Hexp::List] children
+      #
       # @return [void]
-      # @api private
       #
+      # @api private
       def set_children(node, children)
         children.each do |child|
           if child.instance_of?(TextNode)

data/lib/hexp/node/normalize.rb

@@ -11,7 +11,6 @@ module Hexp
       #     Hexp::Node::Normalize.new([:p, {class:'foo'}])
       #
       # @api public
-      #
       def initialize(node)
         @raw = node
       end
@@ -21,7 +20,6 @@ module Hexp
       # @return [Array] strict hexp node
       #
       # @api private
-      #
       def call
         [@raw.first, normalized_attributes, normalized_children]
       end
@@ -33,7 +31,6 @@ module Hexp
       # @return [Hash] the attributes hash
       #
       # @api private
-      #
       def attributes
         attrs = @raw[1]
         return attrs if attrs.instance_of?(Hash)
@@ -45,7 +42,6 @@ module Hexp
       # @return [Hash]
       #
       # @api private
-      #
       def normalized_attributes
         Hash[*
           attributes.flat_map do |key, value|
@@ -59,7 +55,6 @@ module Hexp
       # @return [Array] the list of child hexps, non-strict
       #
       # @api private
-      #
       def children
         last = @raw.last
         if last.respond_to? :to_ary
@@ -76,18 +71,17 @@ module Hexp
       # @return [Array] list of normalized hexps
       #
       # @api private
-      #
       def normalized_children
         Hexp::List[*
           children.map do |child|
             case child
-            when Hexp::Node
+            when Hexp::Node, Hexp::TextNode
               child
-            when String, TextNode
+            when String
               Hexp::TextNode.new(child)
             when ->(ch) { ch.respond_to? :to_hexp }
               response = child.to_hexp
-              raise FormatError, "to_hexp must return a Hexp::Node, got #{response.inspect}" unless response.instance_of?(Hexp::Node)
+              raise FormatError, "to_hexp must return a Hexp::Node, got #{response.inspect}" unless response.instance_of?(Hexp::Node) || response.instance_of?(Hexp::TextNode)
               response
             when Array
               Hexp::Node[*child.map(&:freeze)]

data/lib/hexp/node/pp.rb

@@ -4,9 +4,10 @@ module Hexp
     class PP
       # Create a new pretty-printer
       #
-      # @param node [Hexp::Node] The node to represent
-      # @api private
+      # @param [Hexp::Node] node
+      #   The node to represent
       #
+      # @api private
       def initialize(node)
         @node = node
       end
@@ -14,8 +15,8 @@ module Hexp
       # Perform the pretty-printing
       #
       # @return [String] The pp output
-      # @api private
       #
+      # @api private
       def call
         [
           @node.class.inspect_name,
@@ -27,8 +28,8 @@ module Hexp
       # Format the node tag
       #
       # @return [String]
-      # @api private
       #
+      # @api private
       def pp_tag
         "[#{@node.tag.inspect}"
       end
@@ -36,8 +37,8 @@ module Hexp
       # Format the node attributes
       #
       # @return [String]
-      # @api private
       #
+      # @api private
       def pp_attributes
         attrs = @node.attributes
         return '' if attrs.empty?
@@ -47,8 +48,8 @@ module Hexp
       # Format the node children
       #
       # @return [String]
-      # @api private
       #
+      # @api private
       def pp_children
         children = @node.children
         return ']' if children.empty?
@@ -57,11 +58,14 @@ module Hexp
 
       # Indent a multiline string with a number of spaces
       #
-      # @param string [String] The string to indent
-      # @param indent [Integer] The number of spaces to use for indentation
+      # @param [String] string
+      #   The string to indent
+      # @param [Integer] indent
+      #   The number of spaces to use for indentation
+      #
       # @return [String]
-      # @api private
       #
+      # @api private
       def self.indent(string, indent = 2)
         string.lines.map {|line|  " "*indent + line}.join
       end