hexp 0.2.0 → 0.3.0

data/lib/hexp/css_selector/parser.rb

@@ -10,35 +10,75 @@ module Hexp
     #
     # The classes that make up the parse tree largely mimic the ones from SASS,
     # like CommaSequence, SimpleSequence, Class, Id, etc. By having them in our
-    # own namespace however we can easily add Hexp-specific helper functions.
+    # own namespace however we can easily add Hexp-specific functionality to them.
     #
     class Parser
+      # Initialize the parser with the selector to parse
+      #
+      # @param [String] selector
+      #
+      # @api private
       def initialize(selector)
         @selector = selector.freeze
       end
 
+      # Parse the selector
+      #
+      # @return [Hexp::CssSelector::CommaSequence]
+      #
+      # @api private
       def parse
         rewrite_comma_sequence(SassParser.call(@selector))
       end
 
+      # Parse a CSS selector in one go
+      #
+      # @param [String] selector
+      # @return [Hexp::CssSelector::CommaSequence]
+      #
+      # @api private
       def self.call(selector)
         new(selector).parse
       end
 
       private
 
+      # Map CommaSequence from the SASS namespace to our own
+      #
+      # @param [Sass::Selector::CommaSequence] comma_sequence
+      # @return [Hexp::CssSelector::CommaSequence]
+      #
+      # @api private
       def rewrite_comma_sequence(comma_sequence)
         CommaSequence.new(comma_sequence.members.map{|sequence| rewrite_sequence(sequence)})
       end
 
+      # Map Sequence from the SASS namespace to our own
+      #
+      # @param [Sass::Selector::Sequence] comma_sequence
+      # @return [Hexp::CssSelector::Sequence]
+      #
+      # @api private
       def rewrite_sequence(sequence)
         Sequence.new(sequence.members.map{|simple_sequence| rewrite_simple_sequence(simple_sequence)})
       end
 
+      # Map SimpleSequence from the SASS namespace to our own
+      #
+      # @param [Sass::Selector::SimpleSequence] comma_sequence
+      # @return [Hexp::CssSelector::SimpleSequence]
+      #
+      # @api private
       def rewrite_simple_sequence(simple_sequence)
         SimpleSequence.new(simple_sequence.members.map{|simple| rewrite_simple(simple)})
       end
 
+      # Map Simple from the SASS namespace to our own
+      #
+      # @param [Sass::Selector::Simple] comma_sequence
+      # @return [Hexp::CssSelector::Simple]
+      #
+      # @api private
       def rewrite_simple(simple)
         case simple
         when ::Sass::Selector::Element             # span
@@ -50,7 +90,7 @@ module Hexp
         when ::Sass::Selector::Attribute           # [href^="http://"]
           raise "CSS attribute selector flags are curently ignored by Hexp (not implemented)" unless simple.flags.nil?
           raise "CSS attribute namespaces are curently ignored by Hexp (not implemented)" unless simple.namespace.nil?
-          raise "CSS attribute operator #{simple.operator} not understood by Hexp" unless %w[= ~= ^=].include?(simple.operator) || simple.operator.nil?
+          raise "CSS attribute operator #{simple.operator} not understood by Hexp" unless %w[= ~= ^= |= $= *=].include?(simple.operator) || simple.operator.nil?
           Attribute.new(
             simple.name.first,
             simple.namespace,
@@ -58,10 +98,13 @@ module Hexp
             simple.value ? simple.value.first : nil,
             simple.flags
           )
+        when ::Sass::Selector::Universal           # *
+          Universal.new
         else
           raise "CSS selectors containing #{simple.class} are not implemented in Hexp"
         end
 
+        # As of yet unimplemented
         # when ::Sass::Selector::Universal           # *
         # when ::Sass::Selector::Parent              # & in Sass
         # when ::Sass::Selector::Interpolation       # #{} in Sass

data/lib/hexp/css_selector/sass_parser.rb

@@ -3,10 +3,20 @@ module Hexp
     # A CSS Parser that only knows how to parse CSS selectors
     #
     class SassParser < ::Sass::SCSS::CssParser
+      # Initialize the parser with the selector to parse
+      #
+      # @param [String] selector
+      #
+      # @api private
       def initialize(selector)
         super(selector, '')
       end
 
+      # Parse the selector
+      #
+      # @return [Sass::Selector::CommaSequence]
+      #
+      # @api private
       def parse
         init_scanner!
         result = selector_comma_sequence
@@ -14,6 +24,12 @@ module Hexp
         result
       end
 
+      # Parse a CSS selector in one go
+      #
+      # @param [String] selector
+      # @return [Sass::Selector::CommaSequence]
+      #
+      # @api private
       def self.call(selector)
         self.new(selector).parse
       end

data/lib/hexp/dom.rb

@@ -2,6 +2,8 @@ module Hexp
   module DOM
     Document = Nokogiri::HTML::Document
     Node     = Nokogiri::XML::Node
+    NodeSet  = Nokogiri::XML::NodeSet
+    DTD      = Nokogiri::XML::DTD
     Text     = Nokogiri::XML::Text
   end
 end

data/lib/hexp/dsl.rb

@@ -1,26 +1,25 @@
 module Hexp
+  # Make the Hexp::Node DSL available to objects that implement `to_hexp`
+  #
+  # Mixing in {Hexp} has the same effect as mixing in {Hexp::DSL}, and is the
+  # recommended way.
+  #
   module DSL
-    [ :tag,
-      :attributes,
-      :children,
-      :attr,
-      :rewrite,
-      :replace,
-      :select,
-      :to_html,
-      :class?,
-      :add_class,
-      :add_child,
-      :add,
-      :<<,
-      :process,
-      :%,
-      :text,
-      :remove_attr,
-      :set_attributes,
-    ].each do |meth|
-      define_method meth do |*args, &blk|
-        to_hexp.public_send(meth, *args, &blk)
+    # The names of methods related to manipulating the list of children of a node
+    CHILDREN_METHODS   = Hexp::Node::Children.public_instance_methods.freeze
+
+    # The names of methods related to a node's attributes
+    ATTRIBUTES_METHODS = Hexp::Node::Attributes.public_instance_methods.freeze
+
+    # Methods that are defined directly in {Hexp::Node}
+    NODE_METHODS = Hexp::Node.public_instance_methods(false) - [
+      :to_hexp,
+      :inspect
+    ]
+
+    [CHILDREN_METHODS, ATTRIBUTES_METHODS, NODE_METHODS].flatten.each do |method|
+      define_method method do |*args, &blk|
+        to_hexp.public_send(method, *args, &blk)
       end
     end
   end

data/lib/hexp/errors.rb

@@ -1,4 +1,6 @@
 module Hexp
+  # Base class for exceptions raised by Hexp
+  #
   Error = Class.new(StandardError)
 
   # Raised when trying to stick things inside a Hexp where they don't belong
@@ -7,7 +9,6 @@ module Hexp
     # Create a new FormatError
     #
     # @api private
-    #
     def initialize(msg = 'You have illegal contents in your Hexp')
       super
     end
@@ -17,5 +18,4 @@ module Hexp
   #
   class ParseError < Error
   end
-
 end

data/lib/hexp/list.rb

@@ -8,10 +8,10 @@ module Hexp
     # @example
     #   Hexp::List.new([H[:p], H[:div]])
     #
-    # @param nodes [#to_ary] List of nodes
+    # @param [#to_ary] nodes
+    #   List of nodes
     #
     # @api public
-    #
     def initialize(nodes)
       super nodes.to_ary.freeze
     end
@@ -24,11 +24,12 @@ module Hexp
     #     Hexp::Node[:hr],
     #   ]
     #
-    # @param args [Array] individual nodes
+    # @param [Array] args
+    #   individual nodes
     #
     # @return [Hexp::List]
-    # @api public
     #
+    # @api public
     def self.[](*args)
       new(args)
     end
@@ -39,21 +40,21 @@ module Hexp
     # that this is a wrapping class. This is convenient when inspecting nested
     # hexps, but probably something we want to solve differently.
     #
-    # @api private
-    # @return string
+    # @return [String]
     #
+    # @api private
     def inspect
       __getobj__.inspect
     end
 
-    # Internal coercion to Array
+    # Implicit conversion to Array
     #
     # @example
     #   Hexp::List[ H[:p], H[:span] ].to_ary #=> [H[:p], H[:span]]
     #
     # @return [Array<Hexp::Node>]
-    # @api public
     #
+    # @api public
     def to_ary
       __getobj__
     end
@@ -72,10 +73,12 @@ module Hexp
     #   H[:div, [[:span]]].children.eql? [H[:span]]           #=> false
     #   H[:div, [[:span]]].children.eql? Hexp::List[H[:span]] #=> true
     #
-    # @param other [Object] Object to compare with
-    # @api public
-    # @return [Boolean]
+    # @param [Object] other
+    #   Object to compare with
     #
+    # @return [true,false]
+    #
+    # @api public
     def eql?(other)
       self == other && self.class == other.class
     end

data/lib/hexp/node.rb

@@ -1,5 +1,56 @@
 module Hexp
-  # A Hexp Node, or simply 'a hexp'
+  # A +Hexp::Node+ represents a single element in a HTML syntax tree. It
+  # consists of three parts : the {#tag}, the {#attributes} and the {#children}.
+  #
+  # Instances of +Hexp::Node+ are immutable. Because of this all methods that
+  # "alter" the node actually return a new instance, leaving the old one
+  # untouched.
+  #
+  # @example Immutable nodes : the old one is untouched
+  #   node = Hexp::Node.new(:div)
+  #   node2 = node.add_class('items')
+  #   p node  # => H[:div]
+  #   p node2 # => H[:div, 'class' => 'items']
+  #
+  # The +Hexp::Node+ constructor takes a +Symbol+, a +Hash+ and an +Array+ for
+  # the {#tag}, {#attributes} and {#children} respectively. However the
+  # attributes and children can each be ommitted if they are empty.
+  #
+  # If the node contains a single child node, then it is not necessary to wrap
+  # that child node in an array. Just put the single node in place of the list
+  # of children.
+  #
+  # One can use +H[tag, attrs, children]+ as a
+  # shorthand syntax. Finally one can use {Hexp.build Hexp.build} to construct nodes using
+  # Ruby blocks, not unlike the Builder or Nokogiri gems.
+  #
+  # @example Creating Hexp : syntax alternatives and optional parameters
+  #   Hexp::Node.new(:div, class: 'foo')
+  #   Hexp::Node.new(:div, {class: 'foo'}, "A text node")
+  #   Hexp::Node.new(:div, {class: 'foo'}, ["A text node"])
+  #   H[:div, {class: 'foo'}, H[:span, {class: 'big'}, "good stuff"]]
+  #   H[:div, {class: 'foo'}, [
+  #       H[:span, {class: 'big'}, "good stuff"],
+  #       H[:a, {href: '/index'}, "go home"]
+  #     ]
+  #   ]
+  #   Hexp.build { div.strong { "Hello, world!" } }
+  #
+  # Methods that read or alter the attributes Hash are defined in
+  # {Hexp::Node::Attributes}. Methods that read or alter the list of child nodes
+  # are defined in {Hexp::Node::Children}
+  #
+  # == CSS selectors
+  #
+  # When working with large trees of {Hexp::Node} objects, it is convenient to
+  # be able to target specific nodes using CSS selector syntax. Hexp supports a
+  # subset of the CSS 3 selector syntax, see {Hexp::Node::CssSelection} for info
+  # on the supported syntax.
+  #
+  # For changing, replacing or removing specific nodes based on a CSS selector
+  # string, see {Hexp::Node#replace}. To iterate over nodes, see
+  # {Hexp::Node#select}.
+  #
   class Node
     include Equalizer.new(:tag, :attributes, :children)
     extend Forwardable
@@ -149,66 +200,66 @@ module Hexp
       false
     end
 
+    # Return a new node, with a different tag
+    #
+    # @example
+    #   H[:div, class: 'foo'].set_tag(:bar)
+    #   # => H[:bar, class: 'foo']
+    #
+    # @param tag [#to_sym] The new tag
+    # @return [Hexp::Node]
+    #
+    # @api public
     def set_tag(tag)
       H[tag.to_sym, attributes, children]
     end
 
-    # Rewrite a node tree
-    #
-    # Since nodes are immutable, this is the main entry point for deriving nodes
-    # from others.
+    # Replace nodes in a tree
     #
-    # Rewrite will pass you each node in the tree, and expects something to replace
-    # it with. A single node, multiple nodes, or no nodes (remove it).
+    # With a CSS selector string like +"form.checkout"+ you specify the nodes
+    # you want to operate on. These will be passed one by one into the block.
+    # The block returns the {Hexp::Node} that will replace the old node, or it
+    # can replace an +Array+ of nodes to fill the place of the old node.
     #
-    # Rewrite will not pass in the root node, since rewrite always returns a single
-    # node, so it doesn't allow you to replace the root node with zero or multiple
-    # nodes.
+    # Because of this you can add one or more nodes, or remove nodes by
+    # returning an empty array.
     #
-    # The block can take one or two parameters, the first being the node that is
-    # being replaced, the second (optional) its parent. As a response the block
-    # needs to return one of these
+    # @example Remove all script tags
+    #   tree.replace('script') {|_| [] }
     #
-    #  * a single Hexp::Node
-    #  * a Hexp::NodeList, or Array of Hexp::Node
-    #  * an Array representation of a Hexp::Node, [:tag, {attributes}, [children]]
-    #  * nil
+    # @example Wrap each +<input>+ tag into a +<p>+ tag
+    #   tree.replace('input') do |input|
+    #     H[:p, input]
+    #   end
     #
-    # The last case (returning nil) means "do nothing", it will simply keep the
-    # currently referenced node where it is. This is very handy when you only want
-    # to act on certain nodes, just return nothing if you want to do nothing.
+    # @param [String] css_selector
     #
-    # Some examples :
+    # @yieldparam [Hexp::Node]
+    #   The matching nodes
     #
-    # Remove all script tags
-    #
-    # @example
-    #    tree.rewrite{|node| [] if node.tag == :script }
-    #
-    # Wrap each <input> tag into a <p> tag
+    # @return [Hexp::Node]
+    #   The rewritten tree
     #
-    # @example
-    #    tree.rewrite do |node|
-    #      if node.tag == :input
-    #        [ H[:p, [ child ] ]
-    #      end
-    #    end
-    #
-    # @param blk [Proc] The rewrite action
-    # @return [Hexp::Node] The rewritten tree
     # @api public
-    #
     def rewrite(css_selector = nil, &block)
       return Rewriter.new(self, block) if css_selector.nil?
       CssSelection.new(self, css_selector).rewrite(&block)
     end
     alias :replace :rewrite
 
+    # Select nodes based on a css selector
+    #
+    # @param [String] css_selector
+    # @yieldparam [Hexp::Node]
+    #
+    # @return [Hexp::Selector,Hexp::CssSelector]
+    #
+    # @api public
     def select(css_selector = nil, &block)
       if css_selector
         CssSelection.new(self, css_selector).each(&block)
       else
-        Selector.new(self, block)
+        Selection.new(self, block)
       end
     end
 

data/lib/hexp/node/attributes.rb

@@ -14,9 +14,10 @@ module Hexp
       #    H[:p, class: 'hello'].attr('id', 'para1') # => H[:p, {"class"=>"hello", "id"=>"para1"}]
       #    H[:p, class: 'hello'].attr('class', nil)  # => H[:p]
       #
+      # @param [Array<#to_s>] args
       # @return [String|Hexp::Node]
-      # @api private
       #
+      # @api private
       def attr(*args)
         arity     = args.count
         attr_name = args[0].to_s
@@ -38,10 +39,12 @@ module Hexp
       # @example
       #   H[:option].has_attr?('selected') #=> false
       #
-      # @param name [String|Symbol] the name of the attribute
-      # @return [Boolean]
-      # @api public
+      # @param [String|Symbol] name
+      #   The name of the attribute
       #
+      # @return [true,false]
+      #
+      # @api public
       def has_attr?(name)
         attributes.has_key? name.to_s
       end
@@ -51,10 +54,13 @@ module Hexp
       # @example
       #   H[:span, class: "banner strong"].class?("strong") #=> true
       #
-      # @param klass [String] the name of the class to check for
-      # @return [Boolean] true if the class is present, false otherwise
-      # @api public
+      # @param [String] klass
+      #   The name of the class to check for
+      #
+      # @return [Boolean]
+      #   True if the class is present, false otherwise
       #
+      # @api public
       def class?(klass)
         attr('class') && attr('class').split(' ').include?(klass.to_s)
       end
@@ -64,10 +70,12 @@ module Hexp
       # @example
       #   H[:div].add_class('foo') #=> H[:div, class: 'foo']
       #
-      # @param klass [#to_s] The class to add
+      # @param [#to_s] klass
+      #   The class to add
+      #
       # @return [Hexp::Node]
-      # @api public
       #
+      # @api public
       def add_class(klass)
         attr('class', [attr('class'), klass].compact.join(' '))
       end
@@ -77,8 +85,8 @@ module Hexp
       # Convenience method so you don't have to split the class list yourself.
       #
       # @return [Array<String>]
-      # @api public
       #
+      # @api public
       def class_list
         @class_list ||= (attr('class') || '').split(' ').freeze
       end
@@ -93,11 +101,12 @@ module Hexp
       # Calling this on a node with a class attribute that is equal to an
       # empty string will result in the class attribute being removed.
       #
-      # @param klass [#to_s] The class to be removed
-      # @return [Hexp::Node] A node that is identical to this one, but with
-      #                      the given class removed
-      # @api public
+      # @param [#to_s] klass
+      #   The class to be removed
+      # @return [Hexp::Node]
+      #   A node that is identical to this one, but with the given class removed
       #
+      # @api public
       def remove_class(klass)
         return self unless has_attr?('class')
         new_list = class_list - [klass.to_s]
@@ -107,10 +116,11 @@ module Hexp
 
       # Set or override multiple attributes using a hash syntax
       #
-      # @param attrs[Hash]
+      # @param [Hash<#to_s,#to_s>] attrs
+      #
       # @return [Hexp::Node]
-      # @api public
       #
+      # @api public
       def set_attrs(attrs)
         H[
           self.tag,
@@ -123,10 +133,13 @@ module Hexp
 
       # Remove an attribute by name
       #
-      # @param name [#to_s] The attribute to be removed
-      # @return [Hexp::Node] a new node with the attribute removed
-      # @api public
+      # @param [#to_s] name
+      #   The attribute to be removed
+      #
+      # @return [Hexp::Node]
+      #   A new node with the attribute removed
       #
+      # @api public
       def remove_attr(name)
         H[
           self.tag,
@@ -137,10 +150,13 @@ module Hexp
 
       # Attribute accessor
       #
-      # @param attribute_name [#to_s] The name of the attribute
-      # @return [String] The value of the attribute
-      # @api public
+      # @param_name [#to_s] attr
+      #   The name of the attribute
       #
+      # @return [String]
+      #   The value of the attribute
+      #
+      # @api public
       def [](attr_name)
         self.attributes[attr_name.to_s]
       end
@@ -148,16 +164,17 @@ module Hexp
       # Merge attributes into this Hexp
       #
       # Class attributes are treated special : the class lists are merged, rather
-      # than being overwritten. See {set_attrs} for a more basic version.
+      # than being overwritten. See {#set_attrs} for a more basic version.
       #
-      # This method is analoguous with {Hash#merge}. As argument it can take a
+      # This method is analoguous with `Hash#merge`. As argument it can take a
       # Hash, or another Hexp element, in which case that element's attributes
       # are used.
       #
-      # @param node_or_hash [#to_hexp|Hash]
+      # @param_or_hash [#to_hexp|Hash] node
+      #
       # @return [Hexp::Node]
-      # @api public
       #
+      # @api public
       def merge_attrs(node_or_hash)
         hash = node_or_hash.respond_to?(:to_hexp) ?
                  node_or_hash.to_hexp.attributes : node_or_hash