gammo 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f88ade2267388af8d29137f6ff0db934d324d77f5bface53cd6ae9fea3f1e466
-  data.tar.gz: 92642a6208ede13520e29c20529f29fd21bb040eac39ec4af97935990b94b0eb
+  metadata.gz: f8fc3eae3f0b1cbe125012fef023b8796430f699f1bcac5a8336770070346315
+  data.tar.gz: ec33fbc6c045d1b458544ecbec141939a301fdce1ce9dd46542ba61dae5e5d6a
 SHA512:
-  metadata.gz: f15b94b27a1738234662a2f196c440b97e4cd2b83a9c9bb468d7c4cfd4058ad6482b0ac06559dc4cd50a0dc8d41ba6114db1a09d51177bca511d1ce4196ef9e6
-  data.tar.gz: 5377c2d17574abcc5e0069e7506ad5e47da211c970a79718218c88d9099723c04a7edba0b58da61eb9898e24fc300c04b3f8e2daba49ce41994ec990c27ff5fe
+  metadata.gz: 3a6f7dda7321a8cebba91755efe435a5207e95be939b87c8abccdf5b177730ac402975bf52572026d0776b9cc3ab8852e873099b9013e41c1222f9ba496a9085
+  data.tar.gz: 8cbe7ea25c29514dca39ded2407bee031bec9ecf2a02a06c82066ca34248b1ecb885e4d392c50801d1a874b13f282c8a5fc715220acbbde582e421c1bcce2814

data/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Testing
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  test:
+    name: Test with Ruby-${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [2.4, 2.5, 2.6, 2.7, 3.0]
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rake

data/Gemfile.lock

@@ -1,23 +1,23 @@
 PATH
   remote: .
   specs:
-    gammo (0.1.0)
+    gammo (0.2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     docile (1.3.2)
     erubi (1.9.0)
-    power_assert (1.1.5)
+    power_assert (1.2.0)
     racc (1.5.0)
     rake (12.3.3)
     simplecov (0.18.5)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
-    simplecov-html (0.12.2)
-    test-unit (3.3.5)
+    simplecov-html (0.12.3)
+    test-unit (3.3.6)
       power_assert
-    yard (0.9.20)
+    yard (0.9.25)
 
 PLATFORMS
   ruby
@@ -32,4 +32,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.1.4
+   2.2.3

data/README.md

@@ -7,7 +7,8 @@
 [![GitHub license](https://img.shields.io/github/license/namusyaka/gammo?color=brightgreen)](https://github.com/namusyaka/gammo/blob/master/LICENSE.txt)
 [![Documentation](http://img.shields.io/:yard-docs-38c800.svg)](http://www.rubydoc.info/gems/gammo/frames)
 
-Gammo is an implementation of the HTML5 parsing algorithm which conforms [the WHATWG specification](https://html.spec.whatwg.org/multipage/parsing.html), without any dependencies. Given an HTML string, Gammo parses it and builds DOM tree based on the tokenization and tree-construction algorithm defined in WHATWG parsing algorithm.
+Gammo provides a pure Ruby HTML5-compliant parser and CSS selector / XPath support for traversing the DOM tree built by Gammo.
+The implementation of the HTML5 parsing algorithm in Gammo conforms [the WHATWG specification](https://html.spec.whatwg.org/multipage/parsing.html). Given an HTML string, Gammo parses it and builds DOM tree based on the tokenization and tree-construction algorithm defined in WHATWG parsing algorithm, these implementations are provided without any external dependencies.
 
 Gammo, its naming is inspired by [Gumbo](https://github.com/google/gumbo-parser). But Gammo is a fried tofu fritter made with vegetables.
 
@@ -15,10 +16,45 @@ Gammo, its naming is inspired by [Gumbo](https://github.com/google/gumbo-parser)
 require 'gammo'
 require 'open-uri'
 
-parser = open('https://google.com') { |f| Gammo.new(f.read) }
-parser.parse #=> #<Gammo::Node::Document>
+parser = URI.open('https://google.com') { |f| Gammo.new(f.read) }
+document = parser.parse #=> #<Gammo::Node::Document>
+
+puts document.css('title').first.inner_text #=> 'Google'
 ```
 
+* [Overview](#overview)
+   * [Features](#features)
+* [Tokenizaton](#tokenizaton)
+   * [Token types](#token-types)
+* [Parsing](#parsing)
+   * [Notes](#notes)
+* [Node](#node)
+* [DOM Tree Traversal](#dom-tree-traversal)
+   * [XPath 1.0 (experimental)](#xpath-10-experimental)
+      * [Example](#example)
+      * [Axis Specifiers](#axis-specifiers)
+      * [Node Test](#node-test)
+      * [Operators](#operators)
+      * [Functions](#functions)
+         * [Node set functions](#node-set-functions)
+         * [String Functions](#string-functions)
+         * [Boolean Functions](#boolean-functions)
+         * [Number Functions](#number-functions)
+   * [CSS Selector (experimental)](#css-selector-experimental)
+      * [Example](#example)
+      * [Groups of selectors](#groups-of-selectors)
+      * [Simple selectors](#simple-selectors)
+         * [Type selector &amp; Universal selector](#type-selector--universal-selector)
+         * [Attribute selectors](#attribute-selectors)
+         * [Class selectors](#class-selectors)
+         * [ID selectors](#id-selectors)
+         * [Pseudo-classes](#pseudo-classes)
+      * [Combinators](#combinators)
+* [Performance](#performance)
+* [References](#references)
+* [License](#license)
+* [Release History](#release-history)
+
 ## Overview
 
 ### Features
@@ -26,7 +62,7 @@ parser.parse #=> #<Gammo::Node::Document>
 - [Tokenization](#tokenization): Gammo has a tokenizer for implementing [the tokenization algorithm](https://html.spec.whatwg.org/multipage/parsing.html#tokenization).
 - [Parsing](#parsing): Gammo provides a parser which implements the parsing algorithm by the above tokenization and [the tree-construction algorithm](https://html.spec.whatwg.org/multipage/parsing.html#tree-construction).
 - [Node](#node): Gammo provides the nodes which implement [WHATWG DOM specification](https://dom.spec.whatwg.org/) partially.
-- [DOM Tree Traversal](#dom-tree-traversal): Gammo provides a way of DOM tree traversal.
+- [DOM Tree Traversal](#dom-tree-traversal): Gammo provides a way of DOM tree traversal (CSS selector / XPath).
 - [Performance](#performance): Gammo does not prioritize performance, and there are a few potential performance notes.
 
 ## Tokenizaton
@@ -165,8 +201,7 @@ For some nodes such as `Gammo::Node::Element` and `Gammo::Node::Document`, they
 
 ## DOM Tree Traversal
 
-Currently, XPath 1.0 is the only way for traversing DOM tree built by Gammo.
-CSS selector support is also planned but not having any ETA.
+CSS selector and XPath-1.0 are the way for traversing DOM tree built by Gammo.
 
 ### XPath 1.0 (experimental)
 
@@ -346,12 +381,12 @@ Node tests consist of specific node names or more general expressions. Although
     <tr>
       <td><code>text()</code></td>
       <td>yes</td>
-      <td>Finds a node of type text, e.g. <code>hello</code> in <code><p>hello <a href="https://hello">world</a></p></code></td>
+      <td>Finds a node of type text, e.g. <code>hello</code> in <code>&lt;p&gt;hello &lt;a href="https://hello"&gt;world&lt;/a&gt;&lt;/p&gt;</td>
     </tr>
     <tr>
       <td><code>comment()</code></td>
       <td>yes</td>
-      <td>Finds a node of type comment, e.g. <code><!-- comment --></code></td>
+      <td>Finds a node of type comment, e.g. <code>&lt;!-- comment --&gt;</code></td>
     </tr>
     <tr>
       <td><code>node()</code></td>
@@ -546,9 +581,296 @@ XPath 1.0 defines four data types (nodeset, string, number, boolean) and there a
   </tbody>
 </table>
 
-### CSS Selector
+### CSS Selector (experimental)
+
+Gammo has an original lexer/parser for CSS Selector, it's provided as a helper in the DOM tree built by Gammo.
+Here is a simple example:
+
+```ruby
+document = Gammo.new('<!doctype html><input type="button">').parse
+node_set = document.css('input[type="button"]') #=> "<Gammo::CSSSelector::NodeSet>"
+
+node_set.length #=> 1
+node_set.first #=> "<Gammo::Node::Element>"
+```
+
+Since this is implemented by full scratch, Gammo is providing this support as a very experimental feature. Please file an issue if you find bugs.
+
+#### Example
+
+Before proceeding at the details of CSS Selector support, let's have a look at a few simple examples. Given a sample HTML text and its DOM tree:
+
+```ruby
+document = Gammo.new(<<-EOS).parse
+<!DOCTYPE html>
+<html>
+<head>
+</head>
+<body>
+  <h1>namusyaka.com</h1>
+  <p class="description">Here is a sample web site.</p>
+  <ul>
+    <li>hello</li>
+    <li>world</li>
+  </ul>
+  <ul id="links">
+    <li>Google <a href="https://google.com/">google.com</a></li>
+    <li>GitHub <a href="https://github.com/namusyaka">github.com/namusyaka</a></li>
+  </ul>
+</body>
+</html>
+EOS
+```
+
+The following CSS selector gets all `li` elements and prints thoese text contents:
+
+```ruby
+document.css('li').each do |elm|
+  puts elm.inner_text
+end
+```
+
+The following CSS selector gets all `li` elements under the `ul` element having the `id=links` attribute:
+
+```ruby
+document.xpath('ul#links li').each do |elm|
+  puts elm.inner_text
+end
+```
+
+#### Groups of selectors
+
+Gammo supports [groups of selectors](https://www.w3.org/TR/2018/REC-selectors-3-20181106/#grouping), this means you can use `,` to traverse DOM tree by multiple selectors.
 
-TBD.
+```ruby
+require 'gammo'
+
+@doc = Gammo.new(<<-EOS).parse
+<!DOCTYPE html>
+<html>
+<head>
+<title>hello</title>
+<meta charset="utf8">
+</head>
+<body>
+<p id="hello">hello</p>
+<p id="world">world</p>
+EOS
+
+@doc.css('#hello, #world').map(&:inner_text).join(' ') #=> 'hello world'
+```
+
+#### Simple selectors
+
+##### Type selector & Universal selector
+
+Gammo supports the basic grammar of type selector and universal selector, but not namespaces.
+
+##### Attribute selectors
+
+See more details: [6.3. Attribute selectors](https://www.w3.org/TR/2018/REC-selectors-3-20181106/#attribute-selectors)
+
+<table>
+  <thead>
+    <tr>
+      <th>Syntax</th>
+      <th>Supported</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>[att]</code></td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>[att=val]</code></td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>[att~=val]</code></td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>[att|=val]</code></td>
+      <td>yes</td>
+    </tr>
+  </tbody>
+</table>
+
+##### Class selectors
+
+Supported. See more details: [6.4. Class selectors](https://www.w3.org/TR/2018/REC-selectors-3-20181106/#class-html)
+
+##### ID selectors
+
+Supported. See more details: [6.5. ID selectors](https://www.w3.org/TR/2018/REC-selectors-3-20181106/#id-selectors)
+
+##### Pseudo-classes
+
+Partially supported. See the table below.
+
+<table>
+  <thead>
+    <tr>
+      <th>Class name</th>
+      <th>Supported</th>
+      <th>Can support?</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>:link</code></td>
+      <td>no</td>
+      <td>no</td>
+    </tr>
+    <tr>
+      <td><code>:visited</code></td>
+      <td>no</td>
+      <td>no</td>
+    </tr>
+    <tr>
+      <td><code>:hover</code></td>
+      <td>no</td>
+      <td>no</td>
+    </tr>
+    <tr>
+      <td><code>:active</code></td>
+      <td>no</td>
+      <td>no</td>
+    </tr>
+    <tr>
+      <td><code>:focus</code></td>
+      <td>no</td>
+      <td>no</td>
+    </tr>
+    <tr>
+      <td><code>:target</code></td>
+      <td>no</td>
+      <td>no</td>
+    </tr>
+    <tr>
+      <td><code>:lang</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:enabled</code></td>
+      <td>yes</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:disabled</code></td>
+      <td>yes</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:checked</code></td>
+      <td>yes</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:root</code></td>
+      <td>yes</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:nth-child</code></td>
+      <td>yes</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:nth-last-child</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:nth-of-type</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:nth-last-of-type</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:first-child</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:last-child</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:first-of-type</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:last-of-type</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:only-child</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:only-of-type</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:empty</code></td>
+      <td>no</td>
+      <td>yes</td>
+    </tr>
+    <tr>
+      <td><code>:not</code></td>
+      <td>yes</td>
+      <td>yes</td>
+    </tr>
+  </tbody>
+</table>
+
+#### Combinators
+
+See more details: [8. Combinators](https://www.w3.org/TR/2018/REC-selectors-3-20181106/#combinators)
+
+<table>
+  <thead>
+    <tr>
+      <th>Syntax</th>
+      <th>Supported</th>
+      <th>Desc</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>h1 em</code></td>
+      <td>yes</td>
+      <td>Descendant combinator</td>
+    </tr>
+    <tr>
+      <td><code>h1 > em</code></td>
+      <td>yes</td>
+      <td>Child combinator</td>
+    </tr>
+    <tr>
+      <td><code>math + p</code></td>
+      <td>yes</td>
+      <td>Next-sibling combinator</td>
+    </tr>
+    <tr>
+      <td><code>h1 ~ pre</code></td>
+      <td>yes</td>
+      <td>Subsequent-sibling combinator</td>
+    </tr>
+  </tbody>
+</table>
 
 ## Performance
 
@@ -571,6 +893,8 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Release History
 
+- v0.3.0
+    - CSS selector support [#11](https://github.com/namusyaka/gammo/pull/11)
 - v0.2.0
     - XPath 1.0 support [#4](https://github.com/namusyaka/gammo/pull/4)
 - v0.1.0

data/Rakefile

@@ -25,7 +25,11 @@ task :generate do
 end
 
 namespace :racc do
-  task :parser do
+  task :xpath do
     `bundle exec racc lib/gammo/xpath/parser.y -o lib/gammo/xpath/parser.rb`
   end
+
+  task :css do
+    `bundle exec racc lib/gammo/css_selector/parser.y -o lib/gammo/css_selector/parser.rb`
+  end
 end

data/lib/gammo/attributes.rb

@@ -86,6 +86,11 @@ module Gammo
       @attributes_hash.to_s
     end
 
+    def has_key?(key)
+      @attributes_hash.key?(key.to_s)
+    end
+    alias_method :key?, :has_key?
+
     private
 
     def attributes_to_hash(attrs)

data/lib/gammo/css_selector/ast/combinator.rb

@@ -0,0 +1,92 @@
+require 'set'
+require 'gammo/css_selector/node_set'
+require 'gammo/modules/subclassify'
+
+module Gammo
+  module CSSSelector
+    module AST
+      # Class for representing combinator defined in the CSS selector specification.
+      # @!visibility private
+      class Combinator
+        extend Subclassify
+
+        def initialize(selector)
+          @selector = selector
+        end
+
+        def evaluate(context)
+          strain context, NodeSet.new
+        end
+
+        # Class for representing the descendant combinator.
+        # @!visibility private
+        class Descendant < Combinator
+          declare :descendant
+
+          def strain(context, node_set)
+            @selector.search_descendant(context.dup, node_set)
+            node_set
+          end
+        end
+
+        # Class for representing the child combinator.
+        # @!visibility private
+        class Child < Combinator
+          declare :child
+
+          def strain(context, node_set)
+            context.node.children.inject(0) do |i, child|
+              next i unless child.kind_of?(Node::Element)
+              i += 1
+              node_set << child if @selector.match?(Context.new(node: child, position: i))
+              i
+            end
+            node_set
+          end
+        end
+
+        # Class for representing the next-sibling combinator.
+        # @!visibility private
+        class NextSibling < Combinator
+          declare :next_sibling
+
+          def strain(context, node_set)
+            node = context.node
+            context_position = context.position
+            context_node = context.node
+            while node = node.next_sibling
+              context.position += 1
+              context.node = node
+              next unless node.is_a?(Node::Element)
+              node_set << node if @selector.match?(context)
+              break
+            end
+            context.position = context_position
+            context.node = context_node
+            node_set
+          end
+        end
+
+        # Class for representing the subsequent-sibling combinator.
+        # @!visibility private
+        class SubsequentSibling < Combinator
+          declare :subsequent_sibling
+
+          def strain(context, node_set)
+            node = context.node
+            context_node = context.node
+            position = context.position
+            while node = node.next_sibling
+              context.position += 1
+              context.node = node
+              node_set << node if @selector.match?(context)
+            end
+            context.position = position
+            context.node = context_node
+            node_set
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gammo/css_selector/ast/selector/attrib_selector.rb

@@ -0,0 +1,86 @@
+module Gammo
+  module CSSSelector
+    module AST
+      module Selector
+        class Attrib
+          attr_accessor :value
+
+          extend Subclassify
+
+          def initialize(key:, value:, namespace_prefix: nil)
+            @key = key
+            @value = value
+            @namespace_prefix = namespace_prefix
+          end
+
+          def match?(context)
+            raise NotImplemented, "#match? must be implemented by sub class"
+          end
+
+          private
+
+          def attrib_value(node)
+            node.attributes[@key.to_sym]
+          end
+
+          class Equal < Attrib
+            declare :equal
+
+            def match?(context)
+              attrib_value(context.node) == @value
+            end
+          end
+
+          class PrefixMatch < Attrib
+            declare :prefix_match
+
+            def match?(context)
+              return false if !@value || @value.empty?
+              return false unless val = attrib_value(context.node)
+              val.start_with?(@value)
+            end
+          end
+
+          class SuffixMatch < Attrib
+            declare :suffix_match
+
+            def match?(context)
+              return false if !@value || @value.empty?
+              return false unless val = attrib_value(context.node)
+              val.end_with?(@value)
+            end
+          end
+
+          class SubstringMatch < Attrib
+            declare :substring_match
+
+            def match?(context)
+              return false if !@value || @value.empty?
+              return false unless val = attrib_value(context.node)
+              val.include?(@value)
+            end
+          end
+
+          class DashMatch < Attrib
+            declare :dash_match
+
+            def match?(context)
+              val = attrib_value(context.node) || ''
+              val == @value || (val.start_with?(@value) && val[@value.length] == ?-)
+            end
+          end
+
+          class Includes < Attrib
+            declare :includes
+
+            def match?(context)
+              return false if !@value || @value.empty?
+              val = attrib_value(context.node) || ''
+              val == @value || (val.split(/\s/).include?(@value))
+            end
+          end
+        end
+      end
+    end
+  end
+end