hexp 0.0.1 → 0.2.0

data/lib/hexp/css_selector/parser.rb

@@ -0,0 +1,74 @@
+module Hexp
+  module CssSelector
+    # A parser of CSS selectors
+    #
+    # This is a wrapper around the SASS parser. This way we are isolated from
+    # changes in SASS. It also makes things easier should we decide to switch
+    # to a different parsing library or roll our own parser. We only use a
+    # fraction of the functionality of SASS so this might be worth it, although
+    # at this point I want to avoid reinventing that wheel.
+    #
+    # 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.
+    #
+    class Parser
+      def initialize(selector)
+        @selector = selector.freeze
+      end
+
+      def parse
+        rewrite_comma_sequence(SassParser.call(@selector))
+      end
+
+      def self.call(selector)
+        new(selector).parse
+      end
+
+      private
+
+      def rewrite_comma_sequence(comma_sequence)
+        CommaSequence.new(comma_sequence.members.map{|sequence| rewrite_sequence(sequence)})
+      end
+
+      def rewrite_sequence(sequence)
+        Sequence.new(sequence.members.map{|simple_sequence| rewrite_simple_sequence(simple_sequence)})
+      end
+
+      def rewrite_simple_sequence(simple_sequence)
+        SimpleSequence.new(simple_sequence.members.map{|simple| rewrite_simple(simple)})
+      end
+
+      def rewrite_simple(simple)
+        case simple
+        when ::Sass::Selector::Element             # span
+          Element.new(simple.name.first)
+        when ::Sass::Selector::Class               # .foo
+          Class.new(simple.name.first)
+        when ::Sass::Selector::Id                  # #main
+          Id.new(simple.name.first)
+        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?
+          Attribute.new(
+            simple.name.first,
+            simple.namespace,
+            simple.operator,
+            simple.value ? simple.value.first : nil,
+            simple.flags
+          )
+        else
+          raise "CSS selectors containing #{simple.class} are not implemented in Hexp"
+        end
+
+        # when ::Sass::Selector::Universal           # *
+        # when ::Sass::Selector::Parent              # & in Sass
+        # when ::Sass::Selector::Interpolation       # #{} in Sass
+        # when ::Sass::Selector::Pseudo              # :visited, ::first-line, :nth-child(2n+1)
+        # when ::Sass::Selector::SelectorPseudoClass # :not(.foo)
+
+      end
+    end
+  end
+end

data/lib/hexp/css_selector/sass_parser.rb

@@ -0,0 +1,22 @@
+module Hexp
+  module CssSelector
+    # A CSS Parser that only knows how to parse CSS selectors
+    #
+    class SassParser < ::Sass::SCSS::CssParser
+      def initialize(selector)
+        super(selector, '')
+      end
+
+      def parse
+        init_scanner!
+        result = selector_comma_sequence
+        raise "Invalid CSS selector : unconsumed input #{@scanner.rest}" unless @scanner.eos?
+        result
+      end
+
+      def self.call(selector)
+        self.new(selector).parse
+      end
+    end
+  end
+end

data/lib/hexp/dom.rb

@@ -3,7 +3,5 @@ module Hexp
     Document = Nokogiri::HTML::Document
     Node     = Nokogiri::XML::Node
     Text     = Nokogiri::XML::Text
-
-
   end
 end

data/lib/hexp/dsl.rb

@@ -0,0 +1,27 @@
+module Hexp
+  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)
+      end
+    end
+  end
+end

data/lib/hexp/errors.rb

@@ -0,0 +1,21 @@
+module Hexp
+  Error = Class.new(StandardError)
+
+  # Raised when trying to stick things inside a Hexp where they don't belong
+  #
+  class FormatError < Error
+    # Create a new FormatError
+    #
+    # @api private
+    #
+    def initialize(msg = 'You have illegal contents in your Hexp')
+      super
+    end
+  end
+
+  # Raised by {Hexp.parse} when the input can't be converted to a {Hexp::Node}
+  #
+  class ParseError < Error
+  end
+
+end

data/lib/hexp/h.rb

@@ -1,2 +1,5 @@
-require 'hexp'
-H=Hexp::Node
+if defined?(::H) && ::H != Hexp::Node
+  $stderr.puts "WARN: H is already defined, Hexp H[] shorthand not available"
+else
+  H=Hexp::Node
+end

data/lib/hexp/list.rb

@@ -1,25 +1,83 @@
 module Hexp
   # A list of nodes
   #
-  # @example
-  #   Hexp::List[
-  #     Hexp::Node[:marquee, "Try Hexp for instanst satisfaction!"],
-  #     Hexp::Node[:hr],
-  #   ]
-  #
-  class List < SimpleDelegator
-    include Equalizer.new(:__getobj__)
+  class List < DelegateClass(Array)
 
+    # Create new Hexp::List
+    #
+    # @example
+    #   Hexp::List.new([H[:p], H[:div]])
+    #
+    # @param nodes [#to_ary] List of nodes
+    #
+    # @api public
+    #
     def initialize(nodes)
-      super Hexp.deep_freeze nodes
+      super nodes.to_ary.freeze
     end
 
+    # Convenience constructor
+    #
+    # @example
+    #   Hexp::List[
+    #     Hexp::Node[:marquee, "Try Hexp for instanst satisfaction!"],
+    #     Hexp::Node[:hr],
+    #   ]
+    #
+    # @param args [Array] individual nodes
+    #
+    # @return [Hexp::List]
+    # @api public
+    #
     def self.[](*args)
       new(args)
     end
 
+    # String representation
+    #
+    # This delegates to the underlying array, so it's not obvious from the output
+    # 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
+    #
     def inspect
       __getobj__.inspect
     end
+
+    # Internal coercion to Array
+    #
+    # @example
+    #   Hexp::List[ H[:p], H[:span] ].to_ary #=> [H[:p], H[:span]]
+    #
+    # @return [Array<Hexp::Node>]
+    # @api public
+    #
+    def to_ary
+      __getobj__
+    end
+
+    # Value and type equality
+    #
+    # Hexp::List is mostly interchangeable with a plain Array, and so equality
+    # with `==` delegates to the underlying array, making `Hexp::List[] == []`
+    # true.
+    #
+    # If you want a stronger comparison, than this version will compare both
+    # the value (in this case : contents), and the type.
+    #
+    # @example
+    #   H[:div, [[:span]]].children == [H[:span]]             #=> true
+    #   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]
+    #
+    def eql?(other)
+      self == other && self.class == other.class
+    end
   end
 end

data/lib/hexp/node.rb

@@ -1,53 +1,162 @@
 module Hexp
-  # A Hexp Node
+  # A Hexp Node, or simply 'a hexp'
   class Node
     include Equalizer.new(:tag, :attributes, :children)
     extend Forwardable
 
-    attr_reader :tag, :attributes, :children
-    def_delegators :@children, :empty?
+    include Hexp::Node::Attributes
+    include Hexp::Node::Children
 
-    # Normalize the arguments
+    # The HTML tag of this node
     #
-    # @param args [Array] args a Hexp node
-    # @return [Hexp::Node]
+    # @example
+    #   H[:p].tag #=> :p
+    #
+    # @return [Symbol]
+    # @api public
+    #
+    attr_reader :tag
+
+    # The attributes of this node
     #
     # @example
-    #    Hexp::Node[:p, {'class' => 'foo'}, [[:b, "Hello, World!"]]]
+    #   H[:p, class: 'foo'].attributes #=> {'class' => 'foo'}
     #
+    # @return [Hash<String, String>]
     # @api public
-    def initialize(*args)
-      @tag, @attributes, @children = Hexp.deep_freeze(
-        Normalize.new(args).call
-      )
-    end
+    #
+    attr_reader :attributes
+
+    # The child nodes of this node
+    #
+    # @example
+    #   H[:p, [ H[:span], 'hello' ]].children
+    #   #=> Hexp::List[ H[:span], Hexp::TextNode["hello"] ]
+    #
+    # @return [Hexp::List]
+    # @api public
+    #
+    attr_reader :children
 
+    # Main entry point for creating literal hexps
+    #
+    # At the moment this just redirects to #new, and since Hexp::Node is aliased
+    # to H this provides a shorthand for the contructor,
+    #
+    # @example
+    #   H[:span, {attr: 'value'}].
+    #
+    # Note that while the H[] form is part of the public API and expected to
+    # remain, it's implementation might change. In particular H might become
+    # a class or module in its own right, so it is recommended to only use
+    # this method in its H[] form.
+    #
+    # @param args [Array] args a Hexp node components
+    # @return [Hexp::Node]
+    # @api public
+    #
     def self.[](*args)
       new(*args)
     end
 
+    # Normalize the arguments
+    #
+    # @param args [Array] args a Hexp node components
+    # @return [Hexp::Node]
+    #
+    # @example
+    #    Hexp::Node.new(:p, {'class' => 'foo'}, [[:b, "Hello, World!"]])
+    #
+    # @api public
+    #
+    def initialize(*args)
+      @tag, @attributes, @children = Normalize.new(args).call
+    end
+
+    # Standard hexp coercion protocol, return self
+    #
+    # @example
+    #   H[:p].to_hexp #=> H[:p]
+    #
+    # @return [Hexp::Node] self
+    # @api public
+    #
     def to_hexp
       self
     end
 
-    def to_html
-      to_dom.to_html
+    # Serialize this node to HTML
+    #
+    # @example
+    #   H[:html, [ H[:body, ["hello, world"] ] ]] .to_html
+    #   # => "<html><body>hello, world</body></html>"
+    #
+    # @return [String]
+    # @api public
+    #
+    def to_html(options = {})
+      to_dom(options).to_html
     end
 
-    def to_dom
-      Domize.new(self).call
+    # Convert this node into a Nokogiri Document
+    #
+    # @example
+    #  H[:p].to_dom
+    #  #=> #<Nokogiri::HTML::Document name="document"
+    #        children=[#<Nokogiri::XML::DTD name="html">,
+    #        #<Nokogiri::XML::Element name="p">]>
+    #
+    # @return [Nokogiri::HTML::Document]
+    # @api private
+    #
+    def to_dom(options = {})
+      Domize.new(self, options).call
     end
 
+    # Return a string representation that is close to the literal form
+    #
+    # @example
+    #   H[:p, {class: 'foo'}].inspect #=> "H[:p, {\"class\"=>\"foo\"}]"
+    #
+    # @return [String]
+    # @api public
+    #
     def inspect
-      self.class.inspect_name + [tag, attributes, children ].reject(&:empty?).inspect
+      self.class.inspect_name + [tag, attributes, children].compact.reject(&:empty?).inspect
     end
 
+    # Pretty print, a multiline representation with indentation
+    #
+    # @example
+    #   H[:p, [[:span], [:div]]].pp # => "H[:p, [\n  H[:span],\n  H[:div]]]"
+    #
+    # @return [String]
+    # @api public
+    #
     def pp
       self.class::PP.new(self).call
     end
 
-    # Rewrite a node tree. Since nodes are immutable, this is the main entry point
-    # for deriving nodes from others.
+    # Is this a text node? Returns false
+    #
+    # @example
+    #   H[:p].text? #=> false
+    #
+    # @return [FalseClass]
+    # @api public
+    #
+    def text?
+      false
+    end
+
+    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.
     #
     # 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).
@@ -73,10 +182,12 @@ module Hexp
     #
     # Remove all script tags
     #
+    # @example
     #    tree.rewrite{|node| [] if node.tag == :script }
     #
     # Wrap each <input> tag into a <p> tag
     #
+    # @example
     #    tree.rewrite do |node|
     #      if node.tag == :input
     #        [ H[:p, [ child ] ]
@@ -85,32 +196,76 @@ module Hexp
     #
     # @param blk [Proc] The rewrite action
     # @return [Hexp::Node] The rewritten tree
-    def rewrite(&blk)
-      return to_enum(:rewrite) unless block_given?
-
-      H[self.tag,
-        self.attributes,
-        self.children.flat_map {|child| child.rewrite(&blk)   }
-                     .flat_map do |child|
-          response = blk.call(child, self)
-          if response.instance_of?(Hexp::Node)
-            [ response ]
-          elsif response.respond_to?(:to_ary)
-            if response.first.instance_of?(Symbol)
-              [ response ]
-            else
-              response
-            end
-          elsif response.nil?
-            [ child ]
-          else
-            raise FormatError, "invalid rewrite response : #{response.inspect}, expected Hexp::Node or Array, got #{response.class}"
-          end
+    # @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
+
+    def select(css_selector = nil, &block)
+      if css_selector
+        CssSelection.new(self, css_selector).each(&block)
+      else
+        Selector.new(self, block)
+      end
+    end
+
+    # Run a number of processors on this node
+    #
+    # This is pure convenience, but it helps to conceptualize the "processor"
+    # idea of a component (be it a lambda or other object), that responds to
+    # call, and transform a {Hexp::Node} tree.
+    #
+    # @example
+    #   hexp.process(
+    #     ->(node) { node.replace('.section') {|node| H[:p, class: 'big', node]} },
+    #     ->(node) { node.add_class 'foo' },
+    #     InlineAssets.new
+    #   )
+    #
+    # @param processors [Array<#call>]
+    # @return [Hexp::Node]
+    # @api public
+    #
+    def process(*processors)
+      processors.empty? ? self : processors.first.(self).process(*processors.drop(1))
+    end
+
+    private
+
+    # Set an attribute, used internally by #attr
+    #
+    # Setting an attribute to nil will delete it
+    #
+    # @param name [String|Symbol]
+    # @param value [String|NilClass]
+    # @return [Hexp::Node]
+    #
+    # @api private
+    #
+    def set_attr(name, value)
+      if value.nil?
+        new_attrs = {}
+        attributes.each do |nam,val|
+          new_attrs[nam] = val unless nam == name.to_s
         end
-      ]
+      else
+        new_attrs = attributes.merge(name.to_s => value.to_s)
+      end
+      self.class.new(self.tag, new_attrs, self.children)
     end
 
     class << self
+
+      # Returns the class name for use in creating inspection strings
+      #
+      # This will return "H" if H == Hexp::Node, or "Hexp::Node" otherwise.
+      #
+      # @return [String]
+      # @api private
+      #
       def inspect_name
         if defined?(H) && H == self
           'H'
@@ -118,6 +273,7 @@ module Hexp
           self.name
         end
       end
+
     end
   end
 end