sawzall 0.1.0.pre2-x86_64-linux → 0.1.0.pre3-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52c393775e4ec6d53f6457b76bf926a2766649cd6c49321615b7207d056f1f2d
-  data.tar.gz: 195152a13c2046602bbf4f5e7f4499d0fd6549e9f63060f25bb4bb712af32ece
+  metadata.gz: b2934b373371c232d43ca9a2e2e3c0c15109144d377220eeca69ef8b73c46069
+  data.tar.gz: '049251be4d658dd1294990548e3b051f1152579bf9da2a631233e57721e9586d'
 SHA512:
-  metadata.gz: 39ae9d75e4c0aefcb976df8c04be54c6f34eb029ef12e653b354c57bf5378deca1ef41c74332f2dea31c5cb69aa8aa50246fb568984af272ca6d2c47182950d5
-  data.tar.gz: 9bec2ea88ca835402a6b752cb77f73e59eeb3a6c2ecf825ddcf1386f11e18c808fc634a97c2404925fef74728ebc2f44986a4fcd6c529b8cfa6e038a2c98f3e9
+  metadata.gz: de87b92d84b087d83fda72306a6779049050960acf6409eb8d9e8fbfb926d07fc1921f745342a61b619cef6707fef7be3094972767cab7ac97cf15ce7fea154f
+  data.tar.gz: f36f2f0884f10fa2fbb23733117b3c6f5629bd767e29cd4dfe5024d9ef4fd75e5063d64e70b57838d4bfb4da5c6e0fa73d0dd5b80b839da62b40f63e81e24003

data/README.md

@@ -1,38 +1,41 @@
-# Sawzall
+# Sawzall 🪚
 
-TODO: Delete this and the text below, and describe your gem
+Sawzall wraps the Rust scraper library (https://github.com/rust-scraper/scraper) to make it easy to parse HTML documents and query them with CSS selectors.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sawzall`. To experiment with that code, run `bin/console` for an interactive prompt.
+```ruby
+require "sawzall"
+require "net/http"
 
-## Installation
+doc = Sawzall.parse_document(Net::HTTP.get("example.org", "/"))
+doc.select("title").first.text #=> "Example Domain"
+```
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+> [!NOTE]
+> Sawzall is a hobby project. Expect ongoing development and maintenance to be very much correlated to how much value it brings me as a learning resource and as a tool for my other projects.
+>
+> You are welcome to report bugs you run into or submit pull requests for changes that would make it more useful for your use-case, but please bear the above in mind.
+
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add sawzall
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install sawzall
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+[API documentation](https://davidcornu.github.io/sawzall/)
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sawzall.
+Bug reports and pull requests are welcome on GitHub at https://github.com/davidcornu/sawzall.
 
 ## License
 

data/lib/sawzall/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sawzall
-  VERSION = "0.1.0.pre2"
+  VERSION = "0.1.0.pre3"
 end

data/lib/sawzall.rb

@@ -73,112 +73,186 @@ module Sawzall
   #     # @return [Sawzall::Element]
   #   end
 
-  # @!parse
-  #   class Element
-  #     # Returns the element's name in lowercase
-  #     #
-  #     # @example
-  #     #   doc = Sawzall.parse_fragment("<p>Paragraph</p>")
-  #     #   doc.select("p").first.name #=> "p"
-  #     #
-  #     # @!method name
-  #     # @return [String]
-  #
-  #     # Returns the element's outer HTML
-  #     #
-  #     # @example
-  #     #   doc = Sawzall.parse_fragment(<<~HTML)
-  #     #     <section>
-  #     #       <h1>Heading</h1>
-  #     #     </section>
-  #     #   HTML
-  #     #   section = doc.select("section").first
-  #     #   section.html #=> "<section>\n<h1>Heading</h1>\n</section>"
-  #     #
-  #     # @!method html
-  #     # @return [String]
-  #
-  #     # Returns the element's inner HTML
-  #     #
-  #     # @example
-  #     #   doc = Sawzall.parse_fragment(<<~HTML)
-  #     #     <section>
-  #     #       <h1>Heading</h1>
-  #     #     </section>
-  #     #   HTML
-  #     #   section = doc.select("section").first
-  #     #   section.inner_html #=> "\n<h1>Heading</h1>\n"
-  #     #
-  #     # @!method inner_html
-  #     # @return [String]
-  #
-  #     # Returns the given attribute's value or `nil`
-  #     #
-  #     # @example
-  #     #   doc = Sawzall.parse_fragment("<h1 id='title'>Heading</h1>")
-  #     #   h1 = doc.select("h1").first
-  #     #   h1.attr("id") #=> "title"
-  #     #   h1.attr("class") #=> nil
-  #     #
-  #     # @!method attr(attribute)
-  #     # @param attribute [String]
-  #     # @return [String, Nil]
-  #
-  #     # Returns the child elements that match the given CSS selector
-  #     #
-  #     # https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors
-  #     #
-  #     # @example
-  #     #   doc = Sawzall.parse_fragment(<<~HTML)
-  #     #     <div class="container">
-  #     #       <div>inner div 1</div>
-  #     #       <div>inner div 2</div>
-  #     #     </div>
-  #     #   HTML
-  #     #   container = doc.select(".container").first
-  #     #   matches = container.select("div")
-  #     #   matches.map(&:text) #=> ["inner div 1", "inner div 2"]
-  #     #
-  #     # @!method select(css_selector)
-  #     # @param css_selector [String]
-  #     # @raise [ArgumentError] if the CSS selector is invalid
-  #     # @return [Array<Sawzall::Element>]
-  #
-  #     # Returns the element's child elements
-  #     #
-  #     # @example
-  #     #   doc = Sawzall.parse_fragment(<<~HTML)
-  #     #     <div id="parent">
-  #     #       <div id="child1">
-  #     #         <div id="grandchild1"></div>
-  #     #       </div>
-  #     #       <div id="child2"></div>
-  #     #     </div>
-  #     #   HTML
-  #     #   parent = doc.select("#parent").first
-  #     #   parent
-  #     #     .child_elements
-  #     #     .map { it.attr("id") } #=> ["child1", "child2"]
-  #     #
-  #     # @!method child_elements
-  #     # @return [Array<Sawzall::Element>]
-  #
-  #     # Returns the element's text content using a very simplified version of the
-  #     # `innerText` algorithm.
-  #     #
-  #     # https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText
-  #     #
-  #     # @example
-  #     #   doc = Sawzall.parse_fragment(<<~HTML)
-  #     #     <ul>
-  #     #       <li>First item</li>
-  #     #       <li>Second item</li>
-  #     #     </ul>
-  #     #   HTML
-  #     #   ul = doc.select("ul").first
-  #     #   ul.text #=> "First item\nSecond item"
-  #     #
-  #     # @!method text
-  #     # @return [String]
-  #   end
+  class Element
+    # @!group 1) Querying
+
+    # Returns the element's name in lowercase
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment("<p>Paragraph</p>")
+    #   doc.select("p").first.name #=> "p"
+    #
+    # @!method name
+    # @return [String]
+
+    # Returns the element's outer HTML
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment(<<~HTML)
+    #     <section>
+    #       <h1>Heading</h1>
+    #     </section>
+    #   HTML
+    #   section = doc.select("section").first
+    #   section.html #=> "<section>\n<h1>Heading</h1>\n</section>"
+    #
+    # @!method html
+    # @return [String]
+
+    # Returns the element's inner HTML
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment(<<~HTML)
+    #     <section>
+    #       <h1>Heading</h1>
+    #     </section>
+    #   HTML
+    #   section = doc.select("section").first
+    #   section.inner_html #=> "\n<h1>Heading</h1>\n"
+    #
+    # @!method inner_html
+    # @return [String]
+
+    # Returns the given attribute's value or `nil`
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment("<h1 id='title'>Heading</h1>")
+    #   h1 = doc.select("h1").first
+    #   h1.attr("id") #=> "title"
+    #   h1.attr("class") #=> nil
+    #
+    # @!method attr(attribute)
+    # @param attribute [String]
+    # @return [String, Nil]
+
+    # Returns the element's attributes as an array of key-value pairs
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment("<h1 id='title' class='big'>Heading</h1>")
+    #   h1 = doc.select("h1").first
+    #   h1.attrs #=> [["class", "big"], ["id", "title"]]
+    #
+    # @!method attrs
+    # @return [Array<Array(String, String)>]
+
+    # Returns the child elements that match the given CSS selector
+    #
+    # https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment(<<~HTML)
+    #     <div class="container">
+    #       <div>inner div 1</div>
+    #       <div>inner div 2</div>
+    #     </div>
+    #   HTML
+    #   container = doc.select(".container").first
+    #   matches = container.select("div")
+    #   matches.map(&:text) #=> ["inner div 1", "inner div 2"]
+    #
+    # @!method select(css_selector)
+    # @param css_selector [String]
+    # @raise [ArgumentError] if the CSS selector is invalid
+    # @return [Array<Sawzall::Element>]
+
+    # Returns the element's child elements
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment(<<~HTML)
+    #     <div id="parent">
+    #       <div id="child1">
+    #         <div id="grandchild1"></div>
+    #       </div>
+    #       <div id="child2"></div>
+    #     </div>
+    #   HTML
+    #   parent = doc.select("#parent").first
+    #   parent
+    #     .child_elements
+    #     .map { it.attr("id") } #=> ["child1", "child2"]
+    #
+    # @!method child_elements
+    # @return [Array<Sawzall::Element>]
+
+    # Returns the element's text content using a very simplified version of the
+    # `innerText` algorithm.
+    #
+    # https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment(<<~HTML)
+    #     <ul>
+    #       <li>First item</li>
+    #       <li>Second item</li>
+    #     </ul>
+    #   HTML
+    #   ul = doc.select("ul").first
+    #   ul.text #=> "First item\nSecond item"
+    #
+    # @!method text
+    # @return [String]
+
+    # Checks whether the element has the given class
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment("<h1 class='title'>Heading</h1>")
+    #   h1 = doc.select("h1").first
+    #   h1.has_class?("title") #=> true
+    #   h1.has_class?("TITLE", case_sensitive: false) #=> true
+    #   h1.has_class?("heading") #=> false
+    #
+    # @!method has_class?(css_class, case_sensitive: true)
+    # @param css_class [String]
+    # @param case_sensitive [Boolean]
+    #   Whether matching should be case sensitive. When `false`, only ASCII characters are matched case-insensitively.
+    # @return [Boolean]
+
+    # Returns the element's classes
+    #
+    # @example
+    #   doc = Sawzall.parse_fragment("<h1 class='one two'>Heading</h1>")
+    #   h1 = doc.select("h1").first
+    #   h1.classes #=> ["one", "two"]
+    #
+    # @!method classes
+    # @return [Array<String>]
+
+    # @!endgroup
+
+    # @!group 2) Debugging
+
+    # Overrides Ruby's default `Object#inspect` so the output is a bit more useful
+    def inspect
+      "<#{self.class.name} name=#{name.inspect} child_elements=#{child_elements.inspect}>"
+    end
+
+    # Provides a custom pretty-printing implementation for Ruby's `PP`
+    def pretty_print(pp)
+      pp.group(2, "#(#{self.class.name} {", "})") do
+        pp.breakable
+
+        fields = [:name]
+        fields << :child_elements unless child_elements.empty?
+
+        pp.seplist(fields) do |field|
+          case field
+          when :name
+            pp.text("name = ")
+            pp.pp(name)
+          when :child_elements
+            pp.group(2, "child_elements = [", "]") do
+              pp.breakable
+              pp.seplist(child_elements) do |child|
+                pp.pp(child)
+              end
+            end
+          end
+        end
+
+        pp.breakable
+      end
+    end
+
+    # @!endgroup
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sawzall
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre2
+  version: 0.1.0.pre3
 platform: x86_64-linux
 authors:
 - David Cornu
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-05-12 00:00:00.000000000 Z
+date: 2025-05-16 00:00:00.000000000 Z
 dependencies: []
 description: |
   Sawzall wraps the Rust scraper library (https://github.com/rust-scraper/scraper)