html-pipeline 2.14.2 → 3.0.0.pre1

data/lib/html_pipeline.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+lib_dir = File.join(File.dirname(__dir__), "lib")
+gem_loader = Zeitwerk::Loader.for_gem
+gem_loader.inflector.inflect(
+  "html_pipeline" => "HTMLPipeline",
+)
+gem_loader.ignore(File.join(lib_dir, "html-pipeline.rb"))
+gem_loader.setup
+
+if ENV.fetch("DEBUG", false)
+  require "amazing_print"
+  require "debug"
+end
+
+class HTMLPipeline
+  # HTML processing filters and utilities. This module includes a small
+  # framework for defining DOM based content filters and applying them to user
+  # provided content.
+  #
+  # See HTMLPipeline::Filter for information on building filters.
+  #
+  # Construct a Pipeline for running multiple HTML filters.  A pipeline is created once
+  # with one to many filters, and it then can be `call`ed many times over the course
+  # of its lifetime with input.
+  #
+  # filters         - Array of Filter objects. Each must respond to call(doc,
+  #                   context). Filters are performed in the order provided.
+  # default_context - The default context hash. Values specified here will be merged
+  #                   into values from the each individual pipeline run.  Can NOT be
+  #                   nil.  Default: empty Hash.
+  # result_class    - The default Class of the result object for individual
+  #                   calls.  Default: Hash.  Protip:  Pass in a Struct to get
+  #                   some semblance of type safety.
+  class MissingDependencyError < RuntimeError; end
+  class InvalidFilterError < ArgumentError; end
+
+  class << self
+    def optional_dependency(name, requirer)
+      require name
+    rescue LoadError # rubocop:disable Lint/SuppressedException:
+    end
+
+    def require_dependency(name, requirer)
+      require name
+    rescue LoadError => e
+      raise MissingDependencyError,
+        "Missing dependency '#{name}' for #{requirer}. See README.md for details.\n#{e.class.name}: #{e}"
+    end
+
+    def require_dependencies(names, requirer)
+      dependency_list = names.dup
+      loaded = false
+
+      while !loaded && names.length > 1
+        name = names.shift
+
+        begin
+          require_dependency(name, requirer)
+          loaded = true # we got a dependency
+          define_dependency_loaded_method(name, true)
+        # try the next dependency
+        rescue MissingDependencyError
+          define_dependency_loaded_method(name, false)
+        end
+      end
+
+      return if loaded
+
+      begin
+        name = names.shift
+        require name
+        define_dependency_loaded_method(name, true)
+      rescue LoadError => e
+        raise MissingDependencyError,
+          "Missing all dependencies '#{dependency_list.join(", ")}' for #{requirer}. See README.md for details.\n#{e.class.name}: #{e}"
+      end
+    end
+
+    def define_dependency_loaded_method(name, value)
+      self.class.define_method(:"#{name}_loaded?", -> { value })
+    end
+end
+  # Public: Returns an Array of Filter objects for this Pipeline.
+  attr_reader :text_filters, :node_filters
+
+  # Public: A hash representing the sanitization configuration settings
+  attr_reader :sanitization_config
+
+  # Public: Instrumentation service for the pipeline.
+  # Set an ActiveSupport::Notifications compatible object to enable.
+  attr_accessor :instrumentation_service
+
+  # Public: String name for this Pipeline. Defaults to Class name.
+  attr_writer :instrumentation_name
+
+  def instrumentation_name
+    return @instrumentation_name if defined?(@instrumentation_name)
+
+    @instrumentation_name = self.class.name
+  end
+
+  class << self
+    # Public: Default instrumentation service for new pipeline objects.
+    attr_accessor :default_instrumentation_service
+  end
+
+  def initialize(text_filters: [], convert_filter: nil, sanitization_config: SanitizationFilter::DEFAULT_CONFIG, node_filters: [], default_context: {}, result_class: Hash)
+    raise ArgumentError, "default_context cannot be nil" if default_context.nil?
+
+    @text_filters = text_filters.flatten.freeze
+    validate_filters(@text_filters, HTMLPipeline::TextFilter)
+
+    @node_filters = node_filters.flatten.freeze
+    validate_filters(@node_filters, HTMLPipeline::NodeFilter)
+
+    @convert_filter = convert_filter
+    if @convert_filter.nil? && !@node_filters.empty?
+      raise InvalidFilterError, "Must provide `convert_filter` if `node_filter`s is also provided"
+    elsif !@convert_filter.nil?
+      validate_filter(@convert_filter, HTMLPipeline::ConvertFilter)
+    end
+
+    @sanitization_config = sanitization_config.nil? ? nil : Selma::Sanitizer.new(sanitization_config)
+
+    @default_context = default_context.freeze
+    @instrumentation_service = self.class.default_instrumentation_service
+  end
+
+  # Apply all filters in the pipeline to the given HTML.
+  #
+  # html    - A UTF-8 String comprised of HTML.
+  # context - The context hash passed to each filter. See the Filter docs
+  #           for more info on possible values. This object MUST NOT be modified
+  #           in place by filters.  Use the Result for passing state back.
+  # result  - The result Hash passed to each filter for modification.  This
+  #           is where Filters store extracted information from the content.
+  #
+  # Returns the result Hash after being filtered by this Pipeline.  Contains an
+  # :output key with the String HTML markup based on the
+  # output of the last filter in the pipeline.
+  def call(text, context: {}, result: {})
+    context = @default_context.merge(context)
+    context = context.freeze
+    result ||= {}
+
+    payload = default_payload({ text_filters: @text_filters.map(&:name),
+                                context: context, result: result, })
+    instrument("call_text_filters.html_pipeline", payload) do
+      result[:output] =
+        @text_filters.inject(text) do |doc, filter|
+          perform_filter(filter, doc, context: context, result: result)
+        end
+    end
+
+    text = result[:output]
+
+    html = @convert_filter.call(text) unless @convert_filter.nil?
+
+    unless @node_filters.empty?
+      payload = default_payload({ node_filters: @node_filters.map { |f| f.class.name },
+        context: context, result: result, })
+      instrument("call_node_filters.html_pipeline", payload) do
+        result[:output] = Selma::Rewriter.new(sanitizer: @sanitization_config, handlers: @node_filters).rewrite(html)
+      end
+    end
+
+    result = result.merge(Hash[*@node_filters.collect(&:result).flatten])
+    @node_filters.each(&:reset!)
+
+    result
+  end
+
+  # Internal: Applies a specific filter to the supplied doc.
+  #
+  # The filter is instrumented.
+  #
+  # Returns the result of the filter.
+  def perform_filter(filter, doc, context: {}, result: {})
+    payload = default_payload({ filter: filter.name,
+                                context: context, result: result, })
+    instrument("call_filter.html_pipeline", payload) do
+      filter.call(doc, context: context, result: result)
+    end
+  end
+
+  # Like call but guarantee the value returned is a string of HTML markup.
+  def to_html(input, context: {}, result: {})
+    result = call(input, context: context, result: result)
+    output = result[:output]
+    if output.respond_to?(:to_html)
+      output.to_html
+    else
+      output.to_s
+    end
+  end
+
+  # Public: setup instrumentation for this pipeline.
+  #
+  # Returns nothing.
+  def setup_instrumentation(name, service: nil)
+    self.instrumentation_name = name
+    self.instrumentation_service =
+      service || self.class.default_instrumentation_service
+  end
+
+  # Internal: if the `instrumentation_service` object is set, instruments the
+  # block, otherwise the block is ran without instrumentation.
+  #
+  # Returns the result of the provided block.
+  def instrument(event, payload = {}, &block)
+    payload ||= default_payload
+    return yield(payload) unless instrumentation_service
+
+    instrumentation_service.instrument(event, payload, &block)
+  end
+
+  # Internal: Default payload for instrumentation.
+  #
+  # Accepts a Hash of additional payload data to be merged.
+  #
+  # Returns a Hash.
+  def default_payload(payload = {})
+    { pipeline: instrumentation_name }.merge(payload)
+  end
+
+  private def validate_filter(filter, klass)
+    unless correctly_ancestored?(filter, klass)
+      raise InvalidFilterError, "Filter must inherit from `#{klass}`; #{filter} does not"
+    end
+  end
+
+  private def validate_filters(filters, klass)
+    return if filters.nil? || filters.empty?
+
+    invalid_filters = filters.reject { |f| correctly_ancestored?(f, klass) }
+
+    unless invalid_filters.empty?
+      verb = invalid_filters.count == 1 ? "does" : "do"
+      raise InvalidFilterError, "All filters must inherit from `#{klass}`; #{invalid_filters.join(", ")} #{verb} not"
+    end
+  end
+
+  private def correctly_ancestored?(filter, klass)
+    if filter.respond_to?(:ancestors)
+      filter.ancestors.include?(klass)
+    else
+      filter.class.ancestors.include?(klass)
+    end
+  end
+end

metadata

@@ -1,114 +1,112 @@
 --- !ruby/object:Gem::Specification
 name: html-pipeline
 version: !ruby/object:Gem::Version
-  version: 2.14.2
+  version: 3.0.0.pre1
 platform: ruby
 authors:
-- Ryan Tomayko
-- Jerry Cheung
 - Garen J. Torikian
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-06-12 00:00:00.000000000 Z
+date: 2022-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: selma
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: 0.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: 0.0.1
 - !ruby/object:Gem::Dependency
-  name: nokogiri
+  name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '2.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
-description: GitHub HTML processing filters and utilities
+        version: '2.5'
+description: HTML processing filters and utilities
 email:
-- ryan@github.com
-- jerry@github.com
 - gjtorikian@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".github/FUNDING.yml"
+- ".github/dependabot.yml"
+- ".github/workflows/automerge.yml"
+- ".github/workflows/lint.yml"
+- ".github/workflows/tag_and_release.yml"
+- ".github/workflows/test.yml"
 - ".gitignore"
-- ".travis.yml"
-- Appraisals
+- ".rubocop.yml"
 - CHANGELOG.md
-- CONTRIBUTING.md
 - Gemfile
-- LICENSE
+- LICENSE.txt
 - README.md
 - Rakefile
-- bin/html-pipeline
+- UPGRADING.md
 - html-pipeline.gemspec
-- lib/html/pipeline.rb
-- lib/html/pipeline/@mention_filter.rb
-- lib/html/pipeline/@team_mention_filter.rb
-- lib/html/pipeline/absolute_source_filter.rb
-- lib/html/pipeline/autolink_filter.rb
-- lib/html/pipeline/body_content.rb
-- lib/html/pipeline/camo_filter.rb
-- lib/html/pipeline/email_reply_filter.rb
-- lib/html/pipeline/emoji_filter.rb
-- lib/html/pipeline/filter.rb
-- lib/html/pipeline/https_filter.rb
-- lib/html/pipeline/image_filter.rb
-- lib/html/pipeline/image_max_width_filter.rb
-- lib/html/pipeline/markdown_filter.rb
-- lib/html/pipeline/plain_text_input_filter.rb
-- lib/html/pipeline/sanitization_filter.rb
-- lib/html/pipeline/syntax_highlight_filter.rb
-- lib/html/pipeline/text_filter.rb
-- lib/html/pipeline/textile_filter.rb
-- lib/html/pipeline/toc_filter.rb
-- lib/html/pipeline/version.rb
-homepage: https://github.com/jch/html-pipeline
+- lib/html-pipeline.rb
+- lib/html_pipeline.rb
+- lib/html_pipeline/convert_filter.rb
+- lib/html_pipeline/convert_filter/markdown_filter.rb
+- lib/html_pipeline/filter.rb
+- lib/html_pipeline/node_filter.rb
+- lib/html_pipeline/node_filter/absolute_source_filter.rb
+- lib/html_pipeline/node_filter/emoji_filter.rb
+- lib/html_pipeline/node_filter/https_filter.rb
+- lib/html_pipeline/node_filter/image_max_width_filter.rb
+- lib/html_pipeline/node_filter/mention_filter.rb
+- lib/html_pipeline/node_filter/table_of_contents_filter.rb
+- lib/html_pipeline/node_filter/team_mention_filter.rb
+- lib/html_pipeline/sanitization_filter.rb
+- lib/html_pipeline/text_filter.rb
+- lib/html_pipeline/text_filter/image_filter.rb
+- lib/html_pipeline/text_filter/plain_text_input_filter.rb
+- lib/html_pipeline/version.rb
+homepage: https://github.com/gjtorikian/html-pipeline
 licenses:
 - MIT
-metadata: {}
+metadata:
+  funding_uri: https://github.com/sponsors/gjtorikian/
+  rubygems_mfa_required: 'true'
 post_install_message: |
   -------------------------------------------------
   Thank you for installing html-pipeline!
-  You must bundle Filter gem dependencies.
-  See html-pipeline README.md for more details.
-  https://github.com/jch/html-pipeline#dependencies
+  You must bundle filter gem dependencies.
+  See the html-pipeline README.md for more details:
+  https://github.com/gjtorikian/html-pipeline#dependencies
   -------------------------------------------------
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.3.22
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.3.26
+signing_key: 
 specification_version: 4
 summary: Helpers for processing content through a chain of filters
 test_files: []

data/.travis.yml

@@ -1,43 +0,0 @@
-language: ruby
-cache: bundler
-bundler_args: --path ../../vendor/bundle
-
-addons:
-  apt:
-    sources:
-      - libicu-dev
-      - kalakris-cmake
-    packages:
-      - cmake
-
-script: bundle exec rake
-
-gemfile:
-  - gemfiles/rails_6.gemfile
-  - gemfiles/rails_5.gemfile
-  - gemfiles/rails_4.gemfile
-  - gemfiles/rails_3.gemfile
-
-rvm:
-  - 2.4.6
-  - 2.3.8
-  - 2.5.7
-  - ruby-head
-
-matrix:
-  fast_finish: true
-  allow_failures:
-    - rvm: ruby-head
-  exclude:
-    - gemfile: gemfiles/rails_6.gemfile
-      rvm: 2.4.6
-    - gemfile: gemfiles/rails_6.gemfile
-      rvm: 2.3.8
-    - gemfile: gemfiles/rails_4.gemfile
-      rvm: 2.5.7
-    - gemfile: gemfiles/rails_4.gemfile
-      rvm: 2.4.6
-    - gemfile: gemfiles/rails_3.gemfile
-      rvm: 2.5.7
-    - gemfile: gemfiles/rails_3.gemfile
-      rvm: 2.4.6

data/Appraisals

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-appraise 'rails-3' do
-  gem 'rack', '< 2'
-  gem 'rails', '3.2.22.2'
-end
-
-appraise 'rails-4' do
-  gem 'rack', '< 2'
-  gem 'rails', '~> 4.2.6'
-end
-
-appraise 'rails-5' do
-  gem 'rails', '~> 5.0.0'
-end
-
-appraise 'rails-6' do
-  gem 'rails', '~> 6.0.0'
-end

data/CONTRIBUTING.md

@@ -1,60 +0,0 @@
-# Contributing
-
-Thanks for using and improving `HTML::Pipeline`!
-
-- [Submitting a New Issue](#submitting-a-new-issue)
-- [Sending a Pull Request](#sending-a-pull-request)
-
-## Submitting a New Issue
-
-If there's an idea you'd like to propose, or a design change, feel free to file a new issue. 
-
-If you have an implementation question or believe you've found a bug, please provide as many details as possible:
-
-- Input document
-- Output HTML document
-- the exact `HTML::Pipeline` code you are using
-- output of the following from your project
-
-```
-ruby -v
-bundle exec nokogiri -v
-```
-
-## Sending a Pull Request
-
-[Pull requests][pr] are always welcome!
-
-Check out [the project's issues list][issues] for ideas on what could be improved.
-
-Before sending, please add tests and ensure the test suite passes.
-
-### Running the Tests
-
-To run the full suite:
-
-  `bundle exec rake`
-
-To run a specific test file:
-
-  `bundle exec ruby -Itest test/html/pipeline_test.rb`
-
-To run a specific test:
-
-  `bundle exec ruby -Itest test/html/pipeline/markdown_filter_test.rb -n test_disabling_gfm`  
-
-To run the full suite with all [supported rubies][travisyaml] in bash:
-
-```bash
-rubies=(ree-1.8.7-2011.03 1.9.2-p290 1.9.3-p429 2.0.0-p247)
-for r in ${rubies[*]} 
-do 
-  rbenv local $r # switch to your version manager of choice
-  bundle install 
-  bundle exec rake 
-done
-```
-
-[issues]: https://github.com/jch/html-pipeline/issues
-[pr]: https://help.github.com/articles/using-pull-requests
-[travisyaml]: https://github.com/jch/html-pipeline/blob/master/.travis.yml

data/bin/html-pipeline

@@ -1,78 +0,0 @@
-#!/usr/bin/env ruby
-require 'html/pipeline'
-
-require 'optparse'
-
-# Accept "help", too
-.map! { |a| a == 'help' ? '--help' : a }
-
-onParser.new do |opts|
-  opts.banner = <<-HELP.gsub(/^    /, '')
-    Usage: html-pipeline [-h] [-f]
-           html-pipeline [FILTER [FILTER [...]]] < file.md
-       cat file.md | html-pipeline [FILTER [FILTER [...]]]
-  HELP
-
- opts.separator 'Options:'
-
-  opts.on('-f', '--filters', 'List the available filters') do
-    filters = HTML::Pipeline.constants.grep(/\w+Filter$/)
-                            .map { |f| f.to_s.gsub(/Filter$/, '') }
-
-    # Text filter doesn't work, no call method
-    filters -= ['Text']
-
-    abort <<-HELP.gsub(/^      /, '')
-      Available filters:
-        #{filters.join("\n        ")}
-    HELP
-  end
-end.parse!
-
-# Default to a GitHub-ish pipeline
-if ARGV.empty?
-
-  filters = [
-    HTML::Pipeline::MarkdownFilter,
-    HTML::Pipeline::SanitizationFilter,
-    HTML::Pipeline::ImageMaxWidthFilter,
-    HTML::Pipeline::EmojiFilter,
-    HTML::Pipeline::AutolinkFilter,
-    HTML::Pipeline::TableOfContentsFilter
-  ]
-
-  # Add syntax highlighting if rouge is present
-  begin
-    require 'rouge'
-    filters << HTML::Pipeline::SyntaxHighlightFilter
-  rescue LoadError
-  end
-
-else
-
-  def filter_named(name)
-    case name
-    when 'Text'
-      raise NameError # Text filter doesn't work, no call method
-    end
-
-    HTML::Pipeline.const_get("#{name}Filter")
-  rescue NameError => e
-    abort "Unknown filter '#{name}'. List filters with the -f option."
-  end
-
-  filters = []
-  until ARGV.empty?
-    name = ARGV.shift
-    filters << filter_named(name)
-  end
-
-end
-
-context = {
-  asset_root: '/assets',
-  base_url: '/',
-  gfm: true
-}
-
-puts HTML::Pipeline.new(filters, context).call(ARGF.read)[:output]