hexp 0.2.0 → 0.3.0

data/Rakefile

@@ -13,8 +13,8 @@ namespace :ci do
     metrics:yardstick:verify
     metrics:flog
     metrics:flay
-    metrics:reek
   ]
+  # metrics:reek
   # metrics:rubocop
 end
 
@@ -29,3 +29,19 @@ task :push => :gem do
   sh "git push --tags"
   sh "gem push pkg/hexp-#{Hexp::VERSION}.gem"
 end
+
+desc "update gh-pages"
+task :doc2gh do
+  sh "git diff-files --quiet || exit 1"
+  sh "git diff-index --quiet --cached HEAD || exit 1"
+  sh "yardoc"
+  sh "[ -d /tmp/doc ] && rm -rf /tmp/doc"
+  sh "mv doc /tmp"
+  sh "git co gh-pages"
+  sh "rm -rf *"
+  sh "cp -r /tmp/doc/* ."
+  sh "git add ."
+  sh "git commit -m 'Update gh-pages with YARD docs'"
+  sh "git push origin gh-pages"
+  sh "git co master"
+end

data/bench/node/rewrite_bench.rb

@@ -0,0 +1,23 @@
+require 'benchmark/ips'
+
+def ten_times_ten(depth = 10)
+  if depth == 0
+    H[:foo]
+  else
+    H[:foo, [ten_times_ten(depth - 1)] * 10]
+  end
+end
+
+
+Benchmark.ips do |x|
+  big_tree = ten_times_ten
+
+  x.report('rewrite') do
+    big_tree.rewrite {|x| x}
+  end
+
+  x.report('add_class') do
+    big_tree.rewrite {|x| x.add_class('hello')}
+  end
+
+end

data/config/flay.yml

@@ -1,3 +1,3 @@
 ---
 threshold: 11
-total_score: 293.0
+total_score: 302.0

data/config/flog.yml

@@ -1,2 +1,2 @@
 ---
-threshold: 45.7
+threshold: 47.1

data/config/reek.yml

@@ -91,6 +91,7 @@ TooManyStatements:
     - Hexp::Builder#tag!
     - Hexp::CssSelector::Attribute#matches?
     - Hexp::CssSelector::Parser#rewrite_simple
+    - Hexp::Node::Normalize#normalized_children
   max_statements: 6
 UncommunicativeMethodName:
   enabled: true
@@ -137,3 +138,8 @@ UtilityFunction:
     - Hexp::TextNode#attributes
     - Hexp::TextNode#children
   max_helper_calls: 0
+PrimaDonnaMethod:
+  exclude:
+    - Hexp::Builder#_raise_if_missing!
+    - Hexp::Builder#tag!
+    - Hexp::Builder#text!

data/config/yardstick.yml

@@ -1,5 +1,6 @@
 ---
-threshold: 93.7
+threshold: 99.1
+require_exact_threshold: false
 rules:
   ApiTag::Presence:
     enabled: true
@@ -25,7 +26,11 @@ rules:
       - Hexp::Nokogiri::Equality#equal_text?
   ReturnTag:
     enabled: true
-    exclude: []
+    exclude:
+      - Hexp::CssSelector::Members#initialize
+      - Hexp::CssSelector::Members.included
+      - Hexp::CssSelector::Named#initialize
+      - Hexp::Builder#_raise_if_empty!
   Summary::Presence:
     enabled: true
     exclude: []

data/hexp.gemspec

@@ -17,11 +17,12 @@ Gem::Specification.new do |gem|
   gem.test_files       = `git ls-files -- spec`.split($/)
   gem.extra_rdoc_files = %w[README.md]
 
-  gem.add_runtime_dependency 'sass'      , '~> 3.2'
-  gem.add_runtime_dependency 'nokogiri'  , '~> 1.6'
-  gem.add_runtime_dependency 'ice_nine'  , '~> 0.8'
-  gem.add_runtime_dependency 'equalizer' , '~> 0.0'
+  gem.add_runtime_dependency 'sass', '~> 3.2'
+  gem.add_runtime_dependency 'nokogiri', '~> 1.6'
+  gem.add_runtime_dependency 'ice_nine', '~> 0.9'
+  gem.add_runtime_dependency 'equalizer', '~> 0.0'
 
-  gem.add_development_dependency 'rake',  '~> 10.1'
+  gem.add_development_dependency 'rake', '~> 10.1'
   gem.add_development_dependency 'rspec', '~> 2.14'
+  gem.add_development_dependency 'benchmark_suite', '~> 1.0'
 end

data/lib/hexp.rb

@@ -9,11 +9,12 @@ require 'equalizer'
 module Hexp
   # Inject the Hexp::DSL module into classes that include Hexp
   #
-  # @param klazz [Class] The class that included Hexp
+  # @param [Class] klazz
+  #   The class that included Hexp
   #
   # @return [Class]
-  # @api private
   #
+  # @api private
   def self.included(klazz)
     klazz.send(:include, Hexp::DSL)
   end
@@ -22,28 +23,30 @@ module Hexp
   #
   # Delegates to IceNine
   #
-  # @param args [Array] arguments to pass on
-  # @return Object
-  # @api private
+  # @param [Array] args
+  #   arguments to pass on
+  # @return [Object]
   #
+  # @api private
   def self.deep_freeze(*args)
     IceNine.deep_freeze(*args)
   end
 
   # Variant of ::Array with slightly modified semantics
   #
-  # Array() is often used to wrap a value in an Array, unless it's already
-  # an array. However if your object implements #to_a, then Array() will use
+  # `Array()` is often used to wrap a value in an Array, unless it's already
+  # an array. However if your object implements `#to_a`, then `Array()` will use
   # that value. Because of this objects that aren't Array-like will get
   # converted as well, such as Struct objects.
   #
   # This implementation relies on #to_ary, which signals that the Object is
   # a drop-in replacement for an actual Array.
   #
-  # @param arg [Object]
+  # @param [Object] arg
+  #
   # @return [Array]
-  # @api private
   #
+  # @api private
   def self.Array(arg)
     if arg.respond_to? :to_ary
       arg.to_ary
@@ -61,10 +64,12 @@ module Hexp
   # @example
   #   Hexp.parse('<div>hello</div>') #=> H[:div, "hello"]
   #
-  # @param html [String] A HTML document
+  # @param [String] html
+  #   A HTML document
+  #
   # @return [Hexp::Node]
-  # @api public
   #
+  # @api public
   def self.parse(html)
     root = Nokogiri(html).root
     raise Hexp::ParseError, "Failed to parse HTML : no document root" if root.nil?
@@ -73,7 +78,7 @@ module Hexp
 
   # Use builder syntax to create a Hexp
   #
-  # (see Hexp::Builder)
+  # @see Hexp::Builder
   #
   # @example
   #   list = Hexp.build do
@@ -84,10 +89,13 @@ module Hexp
   #     end
   #   end
   #
-  # @param args [Array]
+  # @param [Array] args
+  #
+  # @yieldparam [Hexp::Builder]
+  #
   # @return [Hexp::Builder]
-  # @api public
   #
+  # @api public
   def self.build(*args, &block)
     Hexp::Builder.new(*args, &block)
   end
@@ -95,18 +103,18 @@ module Hexp
 end
 
 require 'hexp/version'
-require 'hexp/dsl'
-
 
 require 'hexp/node/attributes'
 require 'hexp/node/children'
-
 require 'hexp/node'
+
+require 'hexp/dsl'
+
 require 'hexp/node/normalize'
 require 'hexp/node/domize'
 require 'hexp/node/pp'
 require 'hexp/node/rewriter'
-require 'hexp/node/selector'
+require 'hexp/node/selection'
 require 'hexp/node/css_selection'
 
 require 'hexp/text_node'

data/lib/hexp/builder.rb

@@ -4,19 +4,24 @@ module Hexp
   class Builder < BasicObject
     include ::Hexp
 
-    # def inspect
-    #   ::Kernel.puts ::Kernel.caller ; ::Kernel.exit
-    # end
-
     # Construct a new builder, and start building
     #
-    # The recommended way to call this is through `Hexp.build`.
+    # The recommended way to call this is through `Hexp.build`. If the block
+    # takes an argument, then builder methods need to be called on that variable.
+    #
+    # @example With an explicit builder
+    #   hi = Hexp.build {|html| html.span "Hello" ; html.span " World"}
+    #
+    # @example Without a builder object
+    #   hi = Hexp.build { span "Hello" ; span " World"}
     #
-    # @param tag [Symbol] The tag of the outermost element (optional)
-    # @param args [Array<Hash|String>] Extra arguments, a String for a text
-    #        node, a Hash for attributes
-    # @param block [Proc] The block containing builder directives, can be with
-    #        or without an argument.
+    # @param [Symbol] tag
+    #   The tag of the outermost element (optional)
+    # @param [Array<Hash,String>] args
+    #   Extra arguments, a String for a text node, a Hash for attributes
+    #
+    # @yieldparam [Hexp::Builder]
+    #   If the block takes an argument it will receive the builder object
     #
     # @api private
     #
@@ -40,15 +45,17 @@ module Hexp
     #   end
     #   hexp.to_html #=> "<div><p>Oh the code, such sweet joy it brings</p></div>"
     #
-    # @param tag [Symbol] The tag name, like 'div' or 'head'
-    # @param args [Array<Hash|String>] A hash of attributes, or a string to use
-    #        inside the tag, or both. Multiple occurences of each can be
-    #        specified
-    # @param block [Proc] Builder directives for the contents of the tag
-    # @return [NilClass]
+    # @param [Symbol] tag
+    #   The tag name, like 'div' or 'head'
+    # @param [Array<Hash|String>] args
+    #   A hash of attributes, or a string to use inside the tag, or both. Multiple
+    #   occurences of each can be specified
+    # @param [Proc] block
+    #   Builder directives for the contents of the tag
     #
-    # @api public
+    # @return [nil]
     #
+    # @api public
     def tag!(tag, *args, &block)
       text, attributes = nil, {}
       args.each do |arg|
@@ -84,10 +91,12 @@ module Hexp
     #     end
     #   end
     #
-    # @param text [String] the text to add
+    # @param [String] text
+    #   the text to add
+    #
     # @return [Hexp::Builder] self
-    # @api public
     #
+    # @api public
     def text!(text)
       _raise_if_empty! "Hexp::Builder needs a root element to add text elements to"
       @stack.last[2] << text.to_s
@@ -113,7 +122,9 @@ module Hexp
     #   end
     #   node.to_html #=> <div><button>click me!</button></div>
     #
-    # @params args [Array<:to_hexp>] Hexpable objects to add to the current tag
+    # @param [Array<#to_hexp>] args
+    #   Hexpable objects to add to the current tag
+    #
     # @return [Hexp::Builder]
     #
     # @api public
@@ -139,8 +150,8 @@ module Hexp
     #  Hexp.build { div { text! 'hello' } }.to_hexp # => H[:div, ["hello"]]
     #
     # @return [Hexp::Node]
-    # @api public
     #
+    # @api public
     def to_hexp
       _raise_if_empty!
       ::Hexp::Node[*@stack.last]
@@ -157,9 +168,10 @@ module Hexp
     # builder calls.
     #
     # @param block [Proc]
-    # @return [NilClass]
-    # @api private
     #
+    # @return [nil]
+    #
+    # @api private
     def _process(&block)
       if block.arity == 1
         block.call(self)
@@ -178,14 +190,15 @@ module Hexp
     #   end
     #
     # @api private
-    #
     class NodeBuilder
       # Create new NodeBuilder
       #
-      # @param node [Array] (tag, attrs, children) triplet
-      # @param builder [Hexp::Builder] The parent builder to delegate back
-      # @api private
+      # @param [Array] node
+      #   (tag, attrs, children) triplet
+      # @param [Hexp::Builder] builder
+      #   The parent builder to delegate back
       #
+      # @api private
       def initialize(node, builder)
         @node, @builder = node, builder
       end
@@ -196,14 +209,16 @@ module Hexp
       #   Hexp.build { div.strong.warn }.to_hexp
       #   # => H[:div, class: 'strong warn']
       #
-      # @param sym [Symbol] the class to add
+      # @param [Symbol] sym
+      #   the class to add
+      #
       # @return [Hexp::Builder::NodeBuilder] self
-      # @api public
       #
+      # @api public
       def method_missing(sym, &block)
         attrs = @node[1]
         @node[1] = attrs.merge class: [attrs[:class], sym.to_s].compact.join(' ')
-        @builder._process &block if block
+        @builder._process(&block) if block
         self
       end
     end
@@ -218,10 +233,10 @@ module Hexp
     #   p Hexp.build { div }
     #
     # @return [String]
-    # @api public
     #
+    # @api public
     def inspect
-      "#<Hexp::Builder #{@stack.empty? ? '[]' :to_hexp.inspect}>"
+      "#<Hexp::Builder #{@stack.empty? ? '[]' : to_hexp.inspect}>"
     end
 
     # Gratefully borrowed from Builder.
@@ -245,10 +260,14 @@ module Hexp
 
     # Raise an exception if nothing has been built yet
     #
-    # @param text [String] The error message
-    # @raises {Hexp::FormatError}
-    # @api private
+    # @param [String] text
+    #   The error message
+    #
+    # @raise [Hexp::FormatError]
+    #   if the builder is converted to a {Hexp::Node} before a root element is
+    #   defined.
     #
+    # @api private
     def _raise_if_empty!(text = 'Hexp::Builder is lacking a root element.')
       ::Kernel.raise ::Hexp::FormatError, text if @stack.empty?
     end

data/lib/hexp/css_selector.rb

@@ -10,10 +10,14 @@ module Hexp
 
       # Member nodes
       #
+      # @return [Array]
+      #
+      # @api private
       attr_reader :members
 
       # Shared initializer for parse tree nodes with children (members)
       #
+      # @api private
       def initialize(members)
         @members = Hexp.deep_freeze(members)
       end
@@ -23,9 +27,9 @@ module Hexp
       # @example
       #   CommaSequence[member1, member2]
       #
-      # @param klass [Class]
-      # @api private
+      # @param [Class] klass
       #
+      # @api private
       def self.included(klass)
         def klass.[](*members)
           new(members)
@@ -35,8 +39,8 @@ module Hexp
       # Return a debugging representation
       #
       # @return [String]
-      # @api private
       #
+      # @api private
       def inspect
         "#{self.class.name.split('::').last}[#{self.members.map(&:inspect).join(', ')}]"
       end
@@ -46,12 +50,29 @@ module Hexp
     #
     module Named
       include Equalizer.new(:name)
+
+      # The name of this element
+      #
+      # @return [String]
+      #
+      # @api private
       attr_reader :name
 
+      # Shared constructor that sets a name
+      #
+      # @param [String] name
+      #   the name of the element
+      #
+      # @api private
       def initialize(name)
         @name = name.freeze
       end
 
+      # Return a representation convenient for debugging
+      #
+      # @return [String]
+      #
+      # @api private
       def inspect
         "<#{self.class.name.split('::').last} name=#{name}>"
       end
@@ -61,24 +82,22 @@ module Hexp
     #
     # Contains a number of {Sequence} objects
     #
-    # For example : `span .big, a'
+    # For example : 'span .big, a'
     #
     class CommaSequence
       include Members
 
-      # def inspect
-      #   members.map(&:inspect).join(', ')
-      # end
-
       # Does any sequence in this comma sequence fully match the given element
       #
       # This method does not recurse, it only checks if any of the sequences in
       # this CommaSequence with a length of one can fully match the given
       # element.
       #
-      # @param element [Hexp::Node]
+      # @param [Hexp::Node] element
+      #
       # @return [Boolean]
       #
+      # @api private
       def matches?(element)
         members.any? do |sequence|
           sequence.members.count == 1 &&
@@ -90,20 +109,29 @@ module Hexp
     # A single CSS sequence like 'div span .foo'
     #
     class Sequence
-
       include Members
 
+      # Does the first element of this sequence match the element
+      #
+      # @param [Hexp::Node] element
+      #
+      # @return [true, false]
+      #
+      # @api private
       def head_matches?(element)
         members.first.matches?(element)
       end
 
+      # Drop the first element of this Sequence
+      #
+      # This returns a new Sequence, with one member less.
+      #
+      # @return [Hexp::CssSelector::Sequence]
+      #
+      # @api private
       def drop_head
         self.class.new(members.drop(1))
       end
-
-      # def inspect
-      #   members.map(&:inspect).join(' ')
-      # end
     end
 
     # A CSS sequence that relates to a single element, like 'div.caption:first'
@@ -111,28 +139,41 @@ module Hexp
     class SimpleSequence
       include Members
 
+      # Does the element match all parts of this SimpleSequence
+      #
+      # @params [Hexp::Node] element
+      #
+      # @return [true, false]
+      #
+      # @api private
       def matches?(element)
         members.all? do |simple|
           simple.matches?(element)
         end
       end
-
-      # def inspect
-      #   members.map(&:inspect).join
-      # end
     end
 
     # A CSS element declaration, like 'div'
     class Element
       include Named
 
+      # Does the node match this element selector
+      #
+      # @param [Hexp::Node] element
+      #
+      # @return [true, false]
+      #
+      # @api private
       def matches?(element)
         element.tag.to_s == name
       end
+    end
 
-      # def inspect
-      #   name
-      # end
+    # Match any element, '*'
+    class Universal
+      def matches?(element)
+        true
+      end
     end
 
     # A CSS class declaration, like '.foo'
@@ -140,6 +181,13 @@ module Hexp
     class Class
       include Named
 
+      # Does the node match this class selector
+      #
+      # @param [Hexp::Node] element
+      #
+      # @return [true, false]
+      #
+      # @api private
       def matches?(element)
         element.class?(name)
       end
@@ -150,6 +198,13 @@ module Hexp
     class Id
       include Named
 
+      # Does the node match this id selector
+      #
+      # @param [Hexp::Node] element
+      #
+      # @return [true, false]
+      #
+      # @api private
       def matches?(element)
         element.attr('id') == name
       end
@@ -157,22 +212,66 @@ module Hexp
 
     # An attribute selector, like [href^="http://"]
     #
+    # @!attribute [r] name
+    #   @return [String] The attribute name
+    # @!attribute [r] namespace
+    #   @return [String]
+    # @!attribute [r] operator
+    #   @return [String] The operator that works on an attribute value
+    # @!attribute [r] value
+    #   @return [String] The value to match against
+    # @!attribute [r] flags
+    #   @return [String]
+    #
+    # @api private
     class Attribute
       include Equalizer.new(:name, :namespace, :operator, :value, :flags)
+
       attr_reader :name, :namespace, :operator, :value, :flags
 
+      # Construct a new Attribute selector
+      #
+      # The attributes directly mimic those returned from the SASS parser, even
+      # though we don't use all of them.
+      #
+      # @param [String] name
+      #   Name of the attribute, like 'href'
+      # @param [String] namespace
+      #   unused
+      # @param [nil, String] operator
+      #   Operator like '~=', '^=', ... Use blank to simply test attribute
+      #   presence.
+      # @param [String] value
+      #   Value to test for, operator dependent
+      # @param [Object] flags
+      #   unused
+      #
+      # @api private
       def initialize(name, namespace, operator, value, flags)
-        @name = name.freeze
+        @name      = name.freeze
         @namespace = namespace.freeze
-        @operator = operator.freeze
-        @value = value.freeze
-        @flag = flags.freeze
+        @operator  = operator.freeze
+        @value     = value.freeze
+        @flag      = flags.freeze
       end
 
+      # Debugging representation
+      #
+      # @return [String]
+      #
+      # @api private
       def inspect
         "<#{self.class.name.split('::').last} name=#{name} namespace=#{namespace.inspect} operator=#{operator.inspect} value=#{value.inspect} flags=#{flags.inspect}>"
       end
 
+      # Does the node match this attribute selector
+      #
+      # @param [Hexp::Node] element
+      #   node to test against
+      #
+      # @return [true, false]
+      #
+      # @api private
       def matches?(element)
         return false unless element[name]
         attribute = element[name]