hexp 0.0.1 → 0.2.0

data/lib/hexp/builder.rb

@@ -0,0 +1,256 @@
+module Hexp
+  # Build Hexps using the builder pattern
+  #
+  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`.
+    #
+    # @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.
+    #
+    # @api private
+    #
+    def initialize(tag = nil, *args, &block)
+      @stack = []
+      if tag
+        tag!(tag, *args, &block)
+      else
+        _process(&block) if block
+      end
+    end
+
+    # Add a tag (HTML element)
+    #
+    # Typically this is called implicitly through method missing, but in case of
+    # name clashes or dynamically generated tags you can call this directly.
+    #
+    # @example
+    #   hexp = Hexp.build :div do
+    #     tag!(:p, "Oh the code, such sweet joy it brings")
+    #   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]
+    #
+    # @api public
+    #
+    def tag!(tag, *args, &block)
+      text, attributes = nil, {}
+      args.each do |arg|
+        case arg
+        when ::Hash
+          attributes.merge!(arg)
+        when ::String
+          text ||= ''
+          text << arg
+        end
+      end
+      @stack << [tag, attributes, text ? [text] : []]
+      if block
+        _process(&block)
+      end
+      if @stack.length > 1
+        node = @stack.pop
+        @stack.last[2] << node
+        NodeBuilder.new(node, self)
+      else
+        NodeBuilder.new(@stack.last, self)
+      end
+    end
+
+    alias method_missing tag!
+
+    # Add a text node to the tree
+    #
+    # @example
+    #   hexp = Hexp.build do
+    #     span do
+    #       text! 'Not all who wander are lost'
+    #     end
+    #   end
+    #
+    # @param text [String] the text to add
+    # @return [Hexp::Builder] self
+    # @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
+      self
+    end
+
+    # Add Hexp objects to the current tag
+    #
+    # Any Hexp::Node or other object implementing to_hexp can be added with
+    # this operator. Multiple objects can be specified in one call.
+    #
+    # Nokogiri and Builder allow inserting of strings containing HTML through
+    # this operator. Since this would violate the core philosophy of Hexp, and
+    # open the door for XSS vulnerabilities, we do not support that usage.
+    #
+    # If you really want to insert HTML that is already in serialized form,
+    # consider parsing it to Hexps first
+    #
+    # @example
+    #   widget = H[:button, "click me!"]
+    #   node = Hexp.build :div do |h|
+    #     h << widget
+    #   end
+    #   node.to_html #=> <div><button>click me!</button></div>
+    #
+    # @params args [Array<:to_hexp>] Hexpable objects to add to the current tag
+    # @return [Hexp::Builder]
+    #
+    # @api public
+    #
+    def <<(*args)
+      args.each do |arg|
+        if arg.respond_to?(:to_hexp)
+          @stack.last[2] << arg
+          self
+        else
+          ::Kernel.raise ::Hexp::FormatError, "Inserting literal HTML into a builder with << is deliberately not supported by Hexp"
+        end
+      end
+    end
+
+    # Implement the standard Hexp coercion protocol
+    #
+    # By implementing this a Builder is interchangeable for a regular node, so
+    # you can use it inside other nodes transparently. But you can call this
+    # method if you really, really just want the plain {Hexp::Node}
+    #
+    # @example
+    #  Hexp.build { div { text! 'hello' } }.to_hexp # => H[:div, ["hello"]]
+    #
+    # @return [Hexp::Node]
+    # @api public
+    #
+    def to_hexp
+      _raise_if_empty!
+      ::Hexp::Node[*@stack.last]
+    end
+
+    # Call the block, with a specific value of 'self'
+    #
+    # If the block takes an argument, then we pass ourselves (the builder) to
+    # the block, and call it as a closure. This way 'self' refers to the calling
+    # object, and it can reference its own methods and ivars.
+    #
+    # If the block does not take an argument, then we evaluate it in the context
+    # of ourselves (the builder), so unqualified method calls are seen as
+    # builder calls.
+    #
+    # @param block [Proc]
+    # @return [NilClass]
+    # @api private
+    #
+    def _process(&block)
+      if block.arity == 1
+        block.call(self)
+      else
+        self.instance_eval(&block)
+      end
+    end
+
+    # Allow setting HTML classes through method calls
+    #
+    # @example
+    #   Hexp.build do
+    #     div.miraculous.wondrous do
+    #       hr
+    #     end
+    #   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
+      #
+      def initialize(node, builder)
+        @node, @builder = node, builder
+      end
+
+      # Used for specifying CSS class names
+      #
+      # @example
+      #   Hexp.build { div.strong.warn }.to_hexp
+      #   # => H[:div, class: 'strong warn']
+      #
+      # @param sym [Symbol] the class to add
+      # @return [Hexp::Builder::NodeBuilder] self
+      # @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
+        self
+      end
+    end
+
+    # Return a debugging representation
+    #
+    # Hexp is intended for HTML, so it shouldn't be a problem that this is an
+    # actual method. It really helps for debugging or when playing around in
+    # irb. If you really want an `<inspect>` tag, use `tag!(:inspect)`.
+    #
+    # @example
+    #   p Hexp.build { div }
+    #
+    # @return [String]
+    # @api public
+    #
+    def inspect
+      "#<Hexp::Builder #{@stack.empty? ? '[]' :to_hexp.inspect}>"
+    end
+
+    # Gratefully borrowed from Builder.
+    # I'd like to benchmark this singleton class based version vs
+    # adding the methods to the class directly, before putting this in.
+    #
+    # @param sym [Symbol] Name of the method to define
+    # @api private
+    #
+    # def _cache_method_call(sym)
+    #   class << self; self; end.class_eval do
+    #     unless method_defined?(sym)
+    #       define_method(sym) do |*args, &block|
+    #         tag!(sym, *args, &block)
+    #       end
+    #     end
+    #   end
+    # end
+
+    private
+
+    # Raise an exception if nothing has been built yet
+    #
+    # @param text [String] The error message
+    # @raises {Hexp::FormatError}
+    # @api private
+    #
+    def _raise_if_empty!(text = 'Hexp::Builder is lacking a root element.')
+      ::Kernel.raise ::Hexp::FormatError, text if @stack.empty?
+    end
+  end
+end

data/lib/hexp/css_selector.rb

@@ -0,0 +1,205 @@
+module Hexp
+  module CssSelector
+    # Common behavior for parse tree nodes based on a list of members
+    #
+    module Members
+      include Equalizer.new(:members)
+
+      extend Forwardable
+      def_delegator :@members, :empty?
+
+      # Member nodes
+      #
+      attr_reader :members
+
+      # Shared initializer for parse tree nodes with children (members)
+      #
+      def initialize(members)
+        @members = Hexp.deep_freeze(members)
+      end
+
+      # Create a class level collection constructor
+      #
+      # @example
+      #   CommaSequence[member1, member2]
+      #
+      # @param klass [Class]
+      # @api private
+      #
+      def self.included(klass)
+        def klass.[](*members)
+          new(members)
+        end
+      end
+
+      # Return a debugging representation
+      #
+      # @return [String]
+      # @api private
+      #
+      def inspect
+        "#{self.class.name.split('::').last}[#{self.members.map(&:inspect).join(', ')}]"
+      end
+    end
+
+    # Common behavior for parse tree elements that have a name
+    #
+    module Named
+      include Equalizer.new(:name)
+      attr_reader :name
+
+      def initialize(name)
+        @name = name.freeze
+      end
+
+      def inspect
+        "<#{self.class.name.split('::').last} name=#{name}>"
+      end
+    end
+
+    # Top level parse tree node of a CSS selector
+    #
+    # Contains a number of {Sequence} objects
+    #
+    # 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]
+      # @return [Boolean]
+      #
+      def matches?(element)
+        members.any? do |sequence|
+          sequence.members.count == 1 &&
+            sequence.head_matches?(element)
+        end
+      end
+    end
+
+    # A single CSS sequence like 'div span .foo'
+    #
+    class Sequence
+
+      include Members
+
+      def head_matches?(element)
+        members.first.matches?(element)
+      end
+
+      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'
+    #
+    class SimpleSequence
+      include Members
+
+      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
+
+      def matches?(element)
+        element.tag.to_s == name
+      end
+
+      # def inspect
+      #   name
+      # end
+    end
+
+    # A CSS class declaration, like '.foo'
+    #
+    class Class
+      include Named
+
+      def matches?(element)
+        element.class?(name)
+      end
+    end
+
+    # A CSS id declaration, like '#section-14'
+    #
+    class Id
+      include Named
+
+      def matches?(element)
+        element.attr('id') == name
+      end
+    end
+
+    # An attribute selector, like [href^="http://"]
+    #
+    class Attribute
+      include Equalizer.new(:name, :namespace, :operator, :value, :flags)
+      attr_reader :name, :namespace, :operator, :value, :flags
+
+      def initialize(name, namespace, operator, value, flags)
+        @name = name.freeze
+        @namespace = namespace.freeze
+        @operator = operator.freeze
+        @value = value.freeze
+        @flag = flags.freeze
+      end
+
+      def inspect
+        "<#{self.class.name.split('::').last} name=#{name} namespace=#{namespace.inspect} operator=#{operator.inspect} value=#{value.inspect} flags=#{flags.inspect}>"
+      end
+
+      def matches?(element)
+        return false unless element[name]
+        attribute = element[name]
+
+        case operator
+          # CSS 2
+        when nil
+          true
+        when '='  # exact match
+          attribute == value
+        when '~=' # space separated list contains
+          attribute.split(' ').include?(value)
+        when '|=' # equal to, or starts with followed by a dash
+          attribute =~ /\A#{Regexp.escape(value)}(-|\z)/
+
+          # CSS 3
+        when '^=' # starts with
+          attribute.index(value) == 0
+        when '$=' # ends with
+          attribute =~ /#{Regexp.escape(value)}\z/
+        when '*=' # contains
+          !!(attribute =~ /#{Regexp.escape(value)}/)
+
+        else
+          raise "Unknown operator : #{operator}"
+        end
+      end
+    end
+  end
+end