nokogiri-html-ext 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b391309327d894afb0495dd2fcbe3e3555a0c41bd21937af25a134e0ad1d27ec
+  data.tar.gz: 16e6cd74fd4485610a239edd904318973125de3225a1a5beca69a311fb79eda5
+SHA512:
+  metadata.gz: dc29f44a0ed51d136b5c7e44ff646bfc6d024ac66308b7f539ce64e3ceaad3fe78faed345842946ed538ab4d4dd673a5d831a1cf2f1cc9689c429689c5815c0f
+  data.tar.gz: 2e4ec5bba2a5678f854194ea5d1c1c3a054fd5ae11e62d61f6992f0a52afe87ba239abc6f5114a5e6494a3e1cab1fac0f42a9fe81a79e490f21b77bd63e24161

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## v0.1.0 / 2022-07-01
+
+- Initial release! 🎉

data/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to nokogiri-html-ext
+
+There are a couple ways you can help improve nokogiri-html-ext:
+
+1. Fix an existing [issue][issues] and submit a [pull request][pulls].
+1. Review open [pull requests][pulls].
+1. Report a new [issue][issues]. _Only do this after you've made sure the behavior or problem you're observing isn't already documented in an open issue._
+
+## Getting Started
+
+nokogiri-html-ext is developed using Ruby 2.7.6 and is additionally tested against Ruby 3.0 and 3.1 using [GitHub Actions](https://github.com/jgarber623/nokogiri-html-ext/actions).
+
+Before making changes to nokogiri-html-ext, you'll want to install Ruby 2.7.6. It's recommended that you use a Ruby version managment tool like [rbenv](https://github.com/rbenv/rbenv), [chruby](https://github.com/postmodern/chruby), or [rvm](https://github.com/rvm/rvm). Once you've installed Ruby 2.7.6 using your method of choice, install the project's gems by running:
+
+```sh
+bundle install
+```
+
+## Making Changes
+
+1. Fork and clone the project's repo.
+1. Install development dependencies as outlined above.
+1. Create a feature branch for the code changes you're looking to make: `git checkout -b my-new-feature`.
+1. _Write some code!_
+1. If your changes would benefit from testing, add the necessary tests and verify everything passes by running `bundle exec rspec`.
+1. Commit your changes: `git commit -am 'Add some new feature or fix some issue'`. _(See [this excellent article](https://chris.beams.io/posts/git-commit/) for tips on writing useful Git commit messages.)_
+1. Push the branch to your fork: `git push -u origin my-new-feature`.
+1. Create a new [pull request][pulls] and we'll review your changes.
+
+## Code Style
+
+Code formatting conventions are defined in the `.editorconfig` file which uses the [EditorConfig](http://editorconfig.org) syntax. There are [plugins for a variety of editors](http://editorconfig.org/#download) that utilize the settings in the `.editorconfig` file. We recommended you install the EditorConfig plugin for your editor of choice.
+
+Your bug fix or feature addition won't be rejected if it runs afoul of any (or all) of these guidelines, but following the guidelines will definitely make everyone's lives a little easier.
+
+[issues]: https://github.com/jgarber623/nokogiri-html-ext/issues
+[pulls]: https://github.com/jgarber623/nokogiri-html-ext/pulls

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Jason Garber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+# nokogiri-html-ext
+
+**A Ruby gem extending [Nokogiri](https://nokogiri.org) with several useful HTML-centric features.**
+
+[![Gem](https://img.shields.io/gem/v/nokogiri-html-ext.svg?logo=rubygems&style=for-the-badge)](https://rubygems.org/gems/nokogiri-html-ext)
+[![Downloads](https://img.shields.io/gem/dt/nokogiri-html-ext.svg?logo=rubygems&style=for-the-badge)](https://rubygems.org/gems/nokogiri-html-ext)
+[![Build](https://img.shields.io/github/workflow/status/jgarber623/nokogiri-html-ext/CI?logo=github&style=for-the-badge)](https://github.com/jgarber623/nokogiri-html-ext/actions/workflows/ci.yml)
+[![Maintainability](https://img.shields.io/codeclimate/maintainability/jgarber623/nokogiri-html-ext.svg?logo=code-climate&style=for-the-badge)](https://codeclimate.com/github/jgarber623/nokogiri-html-ext)
+[![Coverage](https://img.shields.io/codeclimate/c/jgarber623/nokogiri-html-ext.svg?logo=code-climate&style=for-the-badge)](https://codeclimate.com/github/jgarber623/nokogiri-html-ext/code)
+
+## Key features
+
+- Resolves all relative URLs in a Nokogiri-parsed HTML document.
+- Adds helpers for getting and setting a document's `<base>` element's `href` attribute.
+- Supports Ruby 2.7 and newer
+
+## Getting Started
+
+Before installing and using nokogiri-html-ext, you'll want to have [Ruby](https://www.ruby-lang.org) 2.7 (or newer) installed. It's recommended that you use a Ruby version managment tool like [rbenv](https://github.com/rbenv/rbenv), [chruby](https://github.com/postmodern/chruby), or [rvm](https://github.com/rvm/rvm).
+
+nokogiri-html-ext is developed using Ruby 2.7.6 and is additionally tested against Ruby 3.0 and 3.1 using [GitHub Actions](https://github.com/jgarber623/nokogiri-html-ext/actions).
+
+## Installation
+
+If you're using [Bundler](https://bundler.io) to manage gem dependencies, add nokogiri-html-ext to your project's Gemfile:
+
+```ruby
+gem 'nokogiri-html-ext'
+```
+
+…and run `bundle install` in your shell.
+
+To install the gem manually, run the following in your shell:
+
+```sh
+gem install nokogiri-html-ext
+```
+
+## Usage
+
+### `base_href`
+
+nokogiri-html-ext provides two helper methods for getting and setting a document's `<base>` element's `href` attribute. The first, `base_href`, retrieves the element's `href` attribute value if it exists.
+
+```ruby
+doc = Nokogiri::HTML('<html><body>Hello, world!</body></html>')
+
+doc.base_href
+#=> nil
+
+doc = Nokogiri::HTML('<html><head><base target="_top"><body>Hello, world!</body></html>')
+
+doc.base_href
+#=> nil
+
+doc = Nokogiri::HTML('<html><head><base href="/foo"><body>Hello, world!</body></html>')
+
+doc.base_href
+#=> "/foo"
+```
+
+The `base_href=` method allows you to manipulate the document's `<base>` element.
+
+```ruby
+doc = Nokogiri::HTML('<html><body>Hello, world!</body></html>')
+
+doc.base_href = '/foo'
+#=> "/foo"
+
+doc.at_css('base').to_s
+#=> "<base href=\"/foo\">"
+
+doc = Nokogiri::HTML('<html><head><base href="/foo"><body>Hello, world!</body></html>')
+
+doc.base_href = '/bar'
+#=> "/bar"
+
+doc.at_css('base').to_s
+#=> "<base href=\"/bar\">"
+```
+
+### `resolve_relative_urls!`
+
+nokogiri-html-ext will resolve a document's relative URLs against a provided source URL. The source URL _should_ be an absolute URL (e.g. `https://jgarber.example`) representing the location of the document being parsed. The source URL _may_ be any `String` (or any Ruby object that responds to `#to_s`).
+
+nokogiri-html-ext takes advantage of [the `Nokogiri::XML::Document.parse` method](https://github.com/sparklemotion/nokogiri/blob/main/lib/nokogiri/xml/document.rb#L48)'s second positional argument to set the parsed document's URL.Nokogiri's source code is _very_ complex, but in short: [the `Nokogiri::HTML` method](https://github.com/sparklemotion/nokogiri/blob/main/lib/nokogiri/html.rb#L7-L8) is an alias to [the `Nokogiri::HTML4` method](https://github.com/sparklemotion/nokogiri/blob/main/lib/nokogiri/html4.rb#L10-L12) which eventually winds its way to the aforementioned `Nokogiri::XML::Document.parse` method. _Phew._ 🥵
+
+URL resolution uses Ruby's built-in URL parsing and normalizing capabilities. Absolute URLs will remain unmodified.
+
+**Note:** If the document's markup includes a `<base>` element whose `href` attribute is an absolute URL, _that_ URL will take precedence when performing URL resolution.
+
+An abbreviated example:
+
+```ruby
+markup = <<-HTML
+  <html>
+  <body>
+    <a href="/home">Home</a>
+    <img src="/foo.png" srcset="../bar.png 720w">
+  </body>
+  </html>
+HTML
+
+doc = Nokogiri::HTML(markup, 'https://jgarber.example')
+
+doc.url
+#=> "https://jgarber.example"
+
+doc.base_href
+#=> nil
+
+doc.base_href = '/foo/bar/biz'
+#=> "/foo/bar/biz"
+
+doc.resolve_relative_urls!
+
+doc.at_css('base')['href']
+#=> "https://jgarber.example/foo/bar/biz"
+
+doc.at_css('a')['href']
+#=> "https://jgarber.example/home"
+
+doc.at_css('img').to_s
+#=> "<img src=\"https://jgarber.example/foo.png\" srcset=\"https://jgarber.example/foo/bar.png 720w\">"
+```
+
+## Contributing
+
+Interested in helping improve nokogiri-html-ext? Awesome! Your help is greatly appreciated. See [CONTRIBUTING.md](https://github.com/jgarber623/nokogiri-html-ext/blob/main/CONTRIBUTING.md) for details.
+
+## Acknowledgments
+
+nokogiri-html-ext wouldn't exist without the [Nokogiri](https://nokogiri.org) project and its [community](https://github.com/sparklemotion/nokogiri).
+
+nokogiri-html-ext is written and maintained by [Jason Garber](https://sixtwothree.org).
+
+## License
+
+nokogiri-html-ext is freely available under the MIT License. Use it, learn from it, fork it, improve it, change it, tailor it to your needs.

data/lib/nokogiri/html-ext.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'html_ext/version'
+
+require_relative 'html_ext/document'

data/lib/nokogiri/html_ext/document.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module Nokogiri
+  module HTML4
+    class Document < Nokogiri::XML::Document
+      # A map of HTML `srcset` attributes and their associated element names.
+      #
+      # @see https://html.spec.whatwg.org/#srcset-attributes
+      # @see https://html.spec.whatwg.org/#attributes-3
+      IMAGE_CANDIDATE_STRINGS_ATTRIBUTES_MAP = {
+        'imagesrcset' => %w[link],
+        'srcset'      => %w[img source]
+      }.freeze
+
+      private_constant :IMAGE_CANDIDATE_STRINGS_ATTRIBUTES_MAP
+
+      # A map of HTML URL attributes and their associated element names.
+      #
+      # @see https://html.spec.whatwg.org/#attributes-3
+      URL_ATTRIBUTES_MAP = {
+        'action'     => %w[form],
+        'cite'       => %w[blockquote del ins q],
+        'data'       => %w[object],
+        'formaction' => %w[button input],
+        'href'       => %w[a area base link],
+        'ping'       => %w[a area],
+        'poster'     => %w[video],
+        'src'        => %w[audio embed iframe img input script source track video]
+      }.freeze
+
+      private_constant :URL_ATTRIBUTES_MAP
+
+      # Get the <base> element's HREF attribute value.
+      #
+      # @return [String, nil]
+      def base_href
+        (base = at_xpath('//base[@href]')) && base['href'].strip
+      end
+
+      # Set the <base> element's HREF attribute value.
+      #
+      # If a <base> element exists, its HREF attribute value is replaced with
+      # the given value. If no <base> element exists, this method will create
+      # one and append it to the document's <head> (creating that element if
+      # necessary).
+      #
+      # @param url [String, #to_s]
+      #
+      # @return [String]
+      def base_href=(url)
+        url_str = url.to_s
+
+        if (base = at_xpath('//base'))
+          base['href'] = url_str
+          url_str
+        else
+          base = XML::Node.new('base', self)
+          base['href'] = url_str
+
+          set_metadata_element(base)
+        end
+      end
+
+      # Convert the document's relative URLs to absolute URLs.
+      #
+      # @return [self]
+      #
+      # rubocop:disable Style/PerlBackrefs
+      def resolve_relative_urls!
+        resolve_relative_urls_for(URL_ATTRIBUTES_MAP) { |value| resolve_relative_url(value.strip) }
+
+        resolve_relative_urls_for(IMAGE_CANDIDATE_STRINGS_ATTRIBUTES_MAP) do |value|
+          value
+            .split(',')
+            .map { |candidate| candidate.strip.sub(/^(.+?)(\s+.+)?$/) { "#{resolve_relative_url($1)}#{$2}" } }
+            .join(', ')
+        end
+
+        self
+      end
+      # rubocop:enable Style/PerlBackrefs
+
+      private
+
+      def resolve_relative_url(url)
+        uri_parser.unescape(
+          uri_parser.join(*[document.url.strip, base_href, url].compact.map { |u| uri_parser.escape(u) })
+                    .normalize
+                    .to_s
+        )
+      end
+
+      def resolve_relative_urls_for(attributes_map)
+        attributes_map.each do |attribute, names|
+          xpaths = names.map { |name| "//#{name}[@#{attribute}]" }
+
+          xpath(*xpaths).each do |node|
+            node[attribute] = yield node[attribute]
+          end
+        end
+      end
+
+      def uri_parser
+        @uri_parser ||= URI::DEFAULT_PARSER
+      end
+    end
+  end
+end

data/lib/nokogiri/html_ext/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module HTMLExt
+    VERSION = '0.1.0'
+  end
+end

data/nokogiri-html-ext.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/nokogiri/html_ext/version'
+
+Gem::Specification.new do |spec|
+  spec.required_ruby_version = '>= 2.7'
+
+  spec.name          = 'nokogiri-html-ext'
+  spec.version       = Nokogiri::HTMLExt::VERSION
+  spec.authors       = ['Jason Garber']
+  spec.email         = ['jason@sixtwothree.org']
+
+  spec.summary       = 'Extend Nokogiri with several useful HTML-centric features.'
+  spec.description   = spec.summary
+  spec.homepage      = 'https://github.com/jgarber623/nokogiri-html-ext'
+  spec.license       = 'MIT'
+
+  spec.files         = Dir['lib/**/*'].reject { |f| File.directory?(f) }
+  spec.files        += %w[LICENSE CHANGELOG.md CONTRIBUTING.md README.md]
+  spec.files        += %w[nokogiri-html-ext.gemspec]
+
+  spec.require_paths = ['lib']
+
+  spec.metadata = {
+    'bug_tracker_uri'       => "#{spec.homepage}/issues",
+    'changelog_uri'         => "#{spec.homepage}/blob/v#{spec.version}/CHANGELOG.md",
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.add_runtime_dependency 'nokogiri', '>= 1.13'
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: nokogiri-html-ext
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jason Garber
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-07-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+description: Extend Nokogiri with several useful HTML-centric features.
+email:
+- jason@sixtwothree.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- lib/nokogiri/html-ext.rb
+- lib/nokogiri/html_ext/document.rb
+- lib/nokogiri/html_ext/version.rb
+- nokogiri-html-ext.gemspec
+homepage: https://github.com/jgarber623/nokogiri-html-ext
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/jgarber623/nokogiri-html-ext/issues
+  changelog_uri: https://github.com/jgarber623/nokogiri-html-ext/blob/v0.1.0/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.16
+signing_key: 
+specification_version: 4
+summary: Extend Nokogiri with several useful HTML-centric features.
+test_files: []