asciidoctor-doctest 1.5.2.0 → 2.0.0.beta.1

data/lib/asciidoctor/doctest/{base_example.rb → example.rb}

@@ -6,7 +6,7 @@ module Asciidoctor
   module DocTest
     ##
     # This class represents a single test example.
-    class BaseExample
+    class Example
 
       NAME_SEPARATOR = ':'
 
@@ -101,39 +101,18 @@ module Asciidoctor
       end
 
       ##
-      # @note The default implementation returns content as-is; subclasses
-      #   should override this method.
-      #
-      # @return [String] copy of the content in a form that is suitable for
-      #         semantic comparison with another content.
-      #
-      def content_normalized
-        content.dup
-      end
-
-      ##
-      # @note (see #content_normalized)
-      #
-      # @return [String] copy of the content in a human-readable (formatted)
-      #         shape for pretty print.
-      #
-      def content_pretty
-        content.dup
-      end
-
-      ##
-      # @return (see #content_pretty)
+      # @return [String] a copy of the content.
       def to_s
-        content_pretty
+        content.dup
       end
 
       ##
       # @param other the object to compare with.
       # @return [Boolean] +true+ if +self+ and +other+ equals in attributes
-      #         +group_name+, +local_name+ and +content_normalized+ (compared
-      #         using +==+), otherwise +false+.
+      #         +group_name+, +local_name+ and +content+ (compared using +==+),
+      #         otherwise +false+.
       def ==(other)
-        [:group_name, :local_name, :content_normalized].all? do |name|
+        [:group_name, :local_name, :content].all? do |name|
           other.respond_to?(name) &&
             public_send(name) == other.public_send(name)
         end

data/lib/asciidoctor/doctest/factory.rb

@@ -0,0 +1,36 @@
+module Asciidoctor::DocTest
+  module Factory
+
+    ##
+    # Registers the given class in the factory under the specified name.
+    #
+    # @param name [#to_sym] the name under which to register the class.
+    # @param klass [Class] the class to register.
+    # @param default_opts [Hash] default options to be passed into the class'
+    #        initializer. May be overriden by +opts+ passed to {.create}.
+    # @return [self]
+    #
+    def register(name, klass, default_opts = {})
+      @factory_registry ||= {}
+      @factory_registry[name.to_sym] = ->(opts) { klass.new(default_opts.merge(opts)) }
+      self
+    end
+
+    ##
+    # @param name [#to_sym] name of the class to create.
+    # @param opts [Hash] options to be passed into the class' initializer.
+    # @return [Object] a new instance of the class registered under the
+    #   specified name.
+    # @raise ArgumentError if no class was found for the given name.
+    #
+    def create(name, opts = {})
+      @factory_registry ||= {}
+
+      if (obj = @factory_registry[name.to_sym])
+        obj.call(opts)
+      else
+        fail ArgumentError, "No class registered with name: #{name}"
+      end
+    end
+  end
+end

data/lib/asciidoctor/doctest/generator.rb

@@ -5,62 +5,69 @@ using Corefines::String::color
 
 module Asciidoctor
   module DocTest
-    module Generator
+    class Generator
 
       ##
-      # Generates missing, or rewrite existing output examples from the
-      # input examples converted using the +renderer+.
+      # @param input_suite [IO::Base] an instance of {IO::Base} subclass to
+      #        read the reference input examples.
       #
-      # @param output_suite [BaseExamplesSuite] an instance of
-      #        {BaseExamplesSuite} subclass to read and generate the output
-      #        examples.
+      # @param output_suite [IO::Base] an instance of {IO::Base} subclass to
+      #        read and generate the output examples.
       #
-      # @param input_suite [BaseExamplesSuite] an instance of
-      #        {BaseExamplesSuite} subclass to read the reference input
-      #        examples.
+      # @param converter [#call] a callable that accepts a string content of
+      #        an input example and a hash with options for the converter, and
+      #        returns the converted content.
       #
-      # @param renderer [#convert]
+      # @param io [#<<] output stream where to write log messages.
+      #
+      def initialize(input_suite, output_suite, converter, io = $stdout)
+        @input_suite = input_suite
+        @output_suite = output_suite
+        @converter = converter
+        @io = io
+      end
+
+      ##
+      # Generates missing, or rewrite existing output examples from the
+      # input examples converted using the +converter+.
       #
       # @param pattern [String] glob-like pattern to select examples to
-      #        (re)generate (see {BaseExample#name_match?}).
+      #        (re)generate (see {Example#name_match?}).
       #
       # @param rewrite [Boolean] whether to rewrite an already existing
       #        example.
       #
-      # @param log_os [#<<] output stream where to write log messages.
-      #
-      def self.generate!(output_suite, input_suite, renderer, pattern: '*:*',
-                         rewrite: false, log_os: $stdout)
+      def generate!(pattern: '*:*', rewrite: false)
         updated = []
 
-        input_suite.pair_with(output_suite).each do |input, output|
+        @input_suite.pair_with(@output_suite).each do |input, output|
           next unless input.name_match? pattern
 
           log = ->(msg, color = :default) do
-            log_os << " --> #{(msg % input.name).color(color)}\n" if log_os
+            @io << " --> #{(msg % input.name).color(color)}\n" if @io
           end
 
           if input.empty?
             log["Unknown %s, doesn't exist in input examples!"]
           else
-            rendered = output_suite.convert_example(input, output.opts, renderer)
-            rendered.desc = output.desc
+            actual, expected = @converter.convert_examples(input, output)
+            generated = output.dup.tap { |ex| ex.content = actual }
 
             if output.empty?
               log['Generating %s', :magenta]
-              updated << rendered
-            elsif rendered == output
+              updated << generated
+            elsif actual == expected
               log['Unchanged %s', :green]
             elsif rewrite
               log['Rewriting %s', :red]
-              updated << rendered
+              updated << generated
             else
               log['Skipping %s', :yellow]
             end
           end
         end
 
-        output_suite.update_examples updated unless updated.empty?
+        @output_suite.update_examples updated unless updated.empty?
       end
     end
   end

data/lib/asciidoctor/doctest/html/converter.rb

@@ -0,0 +1,64 @@
+require 'asciidoctor/doctest/html_normalizer'
+require 'corefines'
+require 'htmlbeautifier'
+require 'nokogiri'
+
+using Corefines::Object::then
+
+module Asciidoctor::DocTest
+  module HTML
+    class Converter < AsciidocConverter
+
+      def initialize(paragraph_xpath: './p/node()', **opts)
+        @paragraph_xpath = paragraph_xpath
+        super opts
+      end
+
+      def convert_examples(input_exmpl, output_exmpl)
+        opts = output_exmpl.opts.dup
+
+        # The header & footer are excluded by default; always enable for document examples.
+        opts[:header_footer] ||= input_exmpl.name.start_with?('document')
+
+        # When asserting inline examples, defaults to ignore paragraph "wrapper".
+        opts[:include] ||= (@paragraph_xpath if input_exmpl.name.start_with? 'inline_')
+
+        actual = convert(input_exmpl.content, header_footer: opts[:header_footer])
+          .then { |s| parse_html s, !opts[:header_footer] }
+          .then { |h| find_nodes h, opts[:include] }
+          .then { |h| remove_nodes h, opts[:exclude] }
+          .then { |h| normalize(h) }
+
+        expected = normalize(output_exmpl.content)
+
+        [actual, expected]
+      end
+
+      protected
+
+      def normalize(content)
+        content = parse_html(content) if content.is_a? String
+        HtmlBeautifier.beautify(content.normalize!)
+      end
+
+      def find_nodes(html, xpaths)
+        Array(xpaths).reduce(html) do |htm, xpath|
+          # XPath returns NodeSet, but we need DocumentFragment, so convert it again.
+          parse_html htm.xpath(xpath).to_html
+        end
+      end
+
+      def remove_nodes(html, xpaths)
+        return html unless xpaths
+
+        Array(xpaths).each_with_object(html.clone) do |xpath, htm|
+          htm.xpath(xpath).remove
+        end
+      end
+
+      def parse_html(str, fragment = true)
+        fragment ? ::Nokogiri::HTML.fragment(str) : ::Nokogiri::HTML.parse(str)
+      end
+    end
+  end
+end

data/lib/asciidoctor/doctest/{html/normalizer.rb → html_normalizer.rb}

@@ -3,8 +3,8 @@ require 'nokogiri'
 
 using Corefines::Object::try
 
-module Asciidoctor::DocTest
-  module HTML
+module Asciidoctor
+  module DocTest
     ##
     # Module to be included into +Nokogiri::HTML::Document+
     # or +DocumentFragment+ to add {#normalize!} feature.
@@ -12,7 +12,7 @@ module Asciidoctor::DocTest
     # @example
     #   Nokogiri::HTML.parse(str).normalize!
     #   Nokogiri::HTML.fragment(str).normalize!
-    module Normalizer
+    module HtmlNormalizer
 
       ##
       # Normalizes the HTML document or fragment so it can be easily compared
@@ -116,5 +116,5 @@ module Asciidoctor::DocTest
 end
 
 [Nokogiri::HTML::Document, Nokogiri::HTML::DocumentFragment].each do |klass|
-  klass.send :include, Asciidoctor::DocTest::HTML::Normalizer
+  klass.send :include, Asciidoctor::DocTest::HtmlNormalizer
 end

data/lib/asciidoctor/doctest/io.rb

@@ -0,0 +1,14 @@
+require 'asciidoctor/doctest/io/base'
+require 'asciidoctor/doctest/io/asciidoc'
+require 'asciidoctor/doctest/io/xml'
+require 'asciidoctor/doctest/factory'
+
+module Asciidoctor::DocTest
+  module IO
+    extend Factory
+
+    register :asciidoc, Asciidoc, file_ext: '.adoc'
+    register :xml, XML, file_ext: '.xml'
+    register :html, XML, file_ext: '.html'
+  end
+end

data/lib/asciidoctor/doctest/{asciidoc/examples_suite.rb → io/asciidoc.rb}

@@ -1,4 +1,4 @@
-require 'asciidoctor/doctest/base_examples_suite'
+require 'asciidoctor/doctest/io/base'
 require 'corefines'
 
 using Corefines::Enumerable::map_send
@@ -6,9 +6,9 @@ using Corefines::Object[:blank?, :presence]
 using Corefines::String::concat!
 
 module Asciidoctor::DocTest
-  module Asciidoc
+  module IO
     ##
-    # Subclass of {BaseExamplesSuite} for reference input examples.
+    # Subclass of {IO::Base} for reference input examples.
     #
     # @example Format of the example's header
     #   // .example-name
@@ -22,11 +22,7 @@ module Asciidoctor::DocTest
     #
     #   NOTE: The trailing new line (below this) will be removed.
     #
-    class ExamplesSuite < BaseExamplesSuite
-
-      def initialize(file_ext: '.adoc', **kwargs)
-        super
-      end
+    class Asciidoc < Base
 
       def parse(input, group_name)
         examples = []

data/lib/asciidoctor/doctest/{base_examples_suite.rb → io/base.rb}

@@ -4,28 +4,28 @@ require 'pathname'
 using Corefines::Object::blank?
 using Corefines::Enumerable::index_by
 
-module Asciidoctor
-  module DocTest
+module Asciidoctor::DocTest
+  module IO
     ##
     # @abstract
     # This is a base class that should be extended for specific example
     # formats.
-    class BaseExamplesSuite
+    class Base
 
-      attr_reader :examples_path, :file_ext
+      attr_reader :path, :file_ext
 
       ##
+      # @param path [String, Array<String>] path of the directory (or multiple
+      #        directories) where to look for the examples.
+      #
       # @param file_ext [String] the filename extension (e.g. +.adoc+) of the
       #        examples group files. Must not be +nil+ or blank. (required)
       #
-      # @param examples_path [String, Array<String>] path of the directory (or
-      #        multiple directories) where to look for the examples.
-      #
-      def initialize(file_ext: nil, examples_path: DocTest.examples_path)
+      def initialize(path: DocTest.examples_path, file_ext: nil)
         fail ArgumentError, 'file_ext must not be blank or nil' if file_ext.blank?
 
+        @path = Array(path).freeze
         @file_ext = file_ext.strip.freeze
-        @examples_path = Array(examples_path).freeze
         @examples_cache = {}
       end
 
@@ -36,7 +36,7 @@ module Asciidoctor
       # @abstract
       # @param input [#each_line] the file content to parse.
       # @param group_name [String] the examples group name.
-      # @return [Array<BaseExample>] parsed examples.
+      # @return [Array<Example>] parsed examples.
       # :nocov:
       def parse(input, group_name)
         fail NotImplementedError
@@ -47,7 +47,7 @@ module Asciidoctor
       # Serializes the given examples into string.
       #
       # @abstract
-      # @param examples [Array<BaseExample>]
+      # @param examples [Array<Example>]
       # @return [String]
       # :nocov:
       def serialize(examples)
@@ -55,30 +55,6 @@ module Asciidoctor
       end
       # :nocov:
 
-      ##
-      # Returns a new example based on the given input example.
-      # This method should render (AsciiDoc) content of the given example using
-      # the preconfigured +renderer+ and eventually apply some transformations.
-      #
-      # XXX describe it better...
-      #
-      # @abstract
-      # @param example [BaseExample] the input example to convert.
-      # @param opts [Hash] the options to pass to a new example.
-      # @param renderer [#convert]
-      # @return [BaseExample]
-      # :nocov:
-      def convert_example(example, opts, renderer)
-        fail NotImplementedError
-      end
-      # :nocov:
-
-      ##
-      # (see BaseExample#initialize)
-      def create_example(*args)
-        BaseExample.new(*args)
-      end
-
       ##
       # Returns enumerator that yields pairs of the examples from this suite
       # and the +other_suite+ (examples with the same name) in order of this
@@ -89,7 +65,7 @@ module Asciidoctor
       # In the case of missing example from this suite, the pair is placed at
       # the end of the examples group.
       #
-      # @param other_suite [BaseExamplesSuite]
+      # @param other_suite [Base]
       # @return [Enumerator]
       #
       def pair_with(other_suite)
@@ -112,9 +88,9 @@ module Asciidoctor
 
       ##
       # Reads the named examples group from file(s). When multiple matching
-      # files are found on the {#examples_path}, it merges them together. If
+      # files are found on the {#path}, it merges them together. If
       # two files defines example with the same name, then the first wins (i.e.
-      # first on the {#examples_path}).
+      # first on the {#path}).
       #
       # @param group_name [String] the examples group name.
       # @return [Array<Example>] an array of parsed examples, or an empty array
@@ -129,14 +105,14 @@ module Asciidoctor
 
       ##
       # Writes the given examples into file(s)
-      # +{examples_path.first}/{group_name}{file_ext}+. Already existing files
-      # will be overwritten!
+      # +{path.first}/{group_name}{file_ext}+. Already existing files will
+      # be overwritten!
       #
-      # @param examples [Array<BaseExample>]
+      # @param examples [Array<Example>]
       #
       def write_examples(examples)
         examples.group_by(&:group_name).each do |group_name, exmpls|
-          path = file_path(@examples_path.first, group_name)
+          path = file_path(@path.first, group_name)
           File.write(path, serialize(exmpls))
         end
       end
@@ -144,7 +120,7 @@ module Asciidoctor
       ##
       # Replaces existing examples with the given ones.
       #
-      # @param examples [Array<BaseExample] the updated examples.
+      # @param examples [Array<Example] the updated examples.
       # @see #write_examples
       #
       def update_examples(examples)
@@ -162,12 +138,12 @@ module Asciidoctor
 
       ##
       # Returns names of all the example groups (files with {#file_ext})
-      # found on the {#examples_path}.
+      # found on the {#path}.
       #
       # @return [Array<String>]
       #
       def group_names
-        @examples_path.reduce(Set.new) { |acc, path|
+        @path.reduce(Set.new) { |acc, path|
           acc | Pathname.new(path).each_child
             .select { |p| p.file? && p.extname == @file_ext }
             .map { |p| p.sub_ext('').basename.to_s }
@@ -176,6 +152,12 @@ module Asciidoctor
 
       protected
 
+      ##
+      # (see Example#initialize)
+      def create_example(*args)
+        DocTest::Example.new(*args)
+      end
+
       ##
       # Converts the given options into the format used in examples file.
       #
@@ -207,7 +189,7 @@ module Asciidoctor
       private
 
       def read_files(file_name)
-        @examples_path
+        @path
           .map { |dir| file_path(dir, file_name) }
           .select(&:readable?)
           .map(&:read)