asciidoctor-doctest 1.5.0

data/lib/asciidoctor/doctest/core_ext.rb

@@ -0,0 +1,49 @@
+module Enumerable
+
+  ##
+  # Sends a message to each element and collects the result.
+  #
+  # @example
+  #   [1, 2, 3].map_send(:+, 3) #=> [4, 5, 6]
+  #
+  # @param method_name [Symbol] name of the public method to call.
+  # @param args arguments to pass to the method.
+  # @param block [Proc] block to pass to the method.
+  # @return [Enumerable]
+  #
+  def map_send(method_name, *args, &block)
+    map { |e| e.public_send(method_name, *args, &block) }
+  end
+end
+
+class Module
+
+  ##
+  # Makes +new_name+ a new copy of the class method +old_name+.
+  #
+  # @param new_name [Symbol] name of the new class method to create.
+  # @param old_name [Symbol] name of the existing class method to alias.
+  #
+  def alias_class_method(new_name, old_name)
+    singleton_class.send(:alias_method, new_name, old_name)
+  end
+end
+
+class String
+
+  ##
+  # Appends (concatenates) the given object to +str+.
+  #
+  # @param obj [String, Integer] the string, or codepoint to append.
+  # @param separator [String, nil] the separator to append when this +str+ is
+  #        not empty.
+  # @return [String] self
+  #
+  def concat(obj, separator = nil)
+    if separator && !self.empty?
+      self << separator << obj
+    else
+      self << obj
+    end
+  end
+end

data/lib/asciidoctor/doctest/generator.rb

@@ -0,0 +1,63 @@
+require 'asciidoctor'
+require 'colorize'
+
+module Asciidoctor
+  module DocTest
+    module Generator
+
+      ##
+      # Generates missing, or rewrite existing output examples from the
+      # input examples converted using the +renderer+.
+      #
+      # @param output_suite [BaseExamplesSuite] an instance of
+      #        {BaseExamplesSuite} subclass to read and generate the output
+      #        examples.
+      #
+      # @param input_suite [BaseExamplesSuite] an instance of
+      #        {BaseExamplesSuite} subclass to read the reference input
+      #        examples.
+      #
+      # @param renderer [#render]
+      #
+      # @param pattern [String] glob-like pattern to select examples to
+      #        (re)generate (see {BaseExample#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)
+        updated = []
+
+        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).colorize(color)}\n" if log_os
+          end
+
+          if input.empty?
+            log["Unknown %s, doesn't exist in input examples!"]
+          else
+            rendered = output_suite.convert_example(input, output.opts, renderer)
+            if output.empty?
+              log['Generating %s', :magenta]
+              updated << rendered
+            elsif rendered == output
+              log['Unchanged %s', :green]
+            elsif rewrite
+              log['Rewriting %s', :red]
+              updated << rendered
+            else
+              log['Skipping %s', :yellow]
+            end
+          end
+        end
+
+        output_suite.update_examples updated unless updated.empty?
+      end
+    end
+  end
+end

data/lib/asciidoctor/doctest/generator_task.rb

@@ -0,0 +1,111 @@
+require 'active_support/core_ext/string/strip'
+require 'asciidoctor/doctest/generator'
+require 'asciidoctor/doctest/core_ext'
+require 'rake/tasklib'
+
+module Asciidoctor
+  module DocTest
+    ##
+    # Rake task for generating output examples.
+    # @see Generator
+    class GeneratorTask < Rake::TaskLib
+
+      # List of values representing +true+.
+      TRUE_VALUES = %w[yes y true]
+
+      # This attribute is used only for the default {#input_suite}.
+      # @return (see DocTest.examples_path)
+      attr_accessor :examples_path
+
+      # @return [Boolean] whether to rewrite an already existing testing
+      #   example. May be overriden with +FORCE+ variable on the command line
+      #   (default: false).
+      attr_accessor :force
+
+      # @return [BaseExamplesSuite] an instance of {BaseExamplesSuite} subclass
+      #         to read the reference input examples
+      #         (default: +Asciidoc::ExamplesSuite.new(examples_path: examples_path)+).
+      attr_accessor :input_suite
+
+      # @return [BaseExamplesSuite] an instance of {BaseExamplesSuite} subclass
+      #         to read and generate the output examples.
+      attr_accessor :output_suite
+
+      # @return [#to_sym] name of the task.
+      attr_accessor :name
+
+      # @return [String] glob pattern to select examples to (re)generate.
+      #   May be overriden with +PATTERN+ variable on the command line
+      #   (default: *:*).
+      attr_accessor :pattern
+
+      # @return [Hash] options for Asciidoctor renderer.
+      # @see AsciidocRenderer#initialize
+      attr_accessor :renderer_opts
+
+      # @return [String] title of the task's description.
+      attr_accessor :title
+
+
+      ##
+      # @param name [#to_sym] name of the task.
+      # @yield The block to configure this task.
+      def initialize(name)
+        @name = name
+        @examples_path = DocTest.examples_path
+        @force = false
+        @input_suite = nil
+        @output_suite = nil
+        @renderer_opts = {}
+        @pattern = '*:*'
+        @title = "Generate testing examples #{pattern}#{" for #{name}" if name != :generate}."
+
+        yield self
+
+        fail 'The output_suite is not provided!' unless @output_suite
+        if @output_suite.examples_path.first == DocTest::BUILTIN_EXAMPLES_PATH
+          fail "The examples_path in output suite is invalid: #{@output_suite.examples_path}"
+        end
+
+        @input_suite ||= Asciidoc::ExamplesSuite.new(examples_path: @examples_path)
+        @renderer ||= AsciidocRenderer.new(renderer_opts)
+
+        define
+      end
+
+      def pattern
+        ENV['PATTERN'] || @pattern
+      end
+
+      def force?
+        return TRUE_VALUES.include?(ENV['FORCE'].downcase) if ENV.key? 'FORCE'
+        !!force
+      end
+
+      private
+
+      def define
+        desc description
+
+        task name.to_sym do
+          puts title
+          Generator.generate! output_suite, input_suite, @renderer,
+                              pattern: pattern, rewrite: force?
+        end
+        self
+      end
+
+      def description
+        <<-EOS.strip_heredoc
+          #{title}
+
+          Options (environment variables):
+            PATTERN   glob pattern to select examples to (re)generate. [default: #{@pattern}]
+                      E.g. *:*, block_toc:basic, block*:*, *list:with*, ...
+            FORCE     overwrite existing examples (yes/no)? [default: #{@force ? 'yes' : 'no'}]
+
+        EOS
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+require 'asciidoctor/doctest/base_example'
+require 'asciidoctor/doctest/html/html_beautifier'
+require 'asciidoctor/doctest/html/normalizer'
+require 'nokogiri'
+
+module Asciidoctor::DocTest
+  module HTML
+    ##
+    # Subclass of {BaseExample} for HTML-based backends.
+    class Example < BaseExample
+
+      def content_normalized
+        Nokogiri::HTML.fragment(content).normalize!.to_s
+      end
+
+      def to_s
+        HtmlBeautifier.beautify content_normalized
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+require 'active_support/core_ext/array/wrap'
+require 'active_support/core_ext/object/blank'
+require 'asciidoctor/doctest/base_examples_suite'
+require 'asciidoctor/doctest/core_ext'
+require 'asciidoctor/doctest/html/example'
+require 'asciidoctor/doctest/html/normalizer'
+require 'nokogiri'
+
+module Asciidoctor::DocTest
+  module HTML
+    ##
+    # Subclass of {BaseExamplesSuite} for HTML-based backends.
+    #
+    # @example Format of the example's header
+    #   <!-- .example-name
+    #     Any text that is not the example's name or an option and doesn't
+    #     start with // is considered as a description.
+    #     :option-1: value 1
+    #     :option-2: value 1
+    #     :option-2: value 2
+    #     :boolean-option:
+    #   -->
+    #   <p>The example's content in <strong>HTML</strong>.</p>
+    #
+    #   <div class="note">The trailing new line (below this) will be removed.</div>
+    #
+    class ExamplesSuite < BaseExamplesSuite
+
+      def initialize(file_ext: '.html', paragraph_xpath: './p/node()', **kwargs)
+        super file_ext: file_ext, **kwargs
+        @paragraph_xpath = paragraph_xpath
+      end
+
+      def parse(input, group_name)
+        examples = []
+        current = create_example(nil)
+        in_comment = false
+
+        input.each_line do |line|
+          line.chomp!
+          if line =~ /^<!--\s*\.([^ \n]+)/
+            name = $1
+            current.content.chomp!
+            examples << (current = create_example([group_name, name]))
+            in_comment = true
+          elsif in_comment
+            if line =~ /^\s*:([^:]+):(.*)/
+              current[$1.to_sym] = $2.blank? ? true : $2.strip
+            elsif !line.start_with?('//')
+              desc = line.rstrip.chomp('-->').strip
+              (current.desc ||= '').concat(desc, "\n") unless desc.empty?
+            end
+          else
+            current.content.concat(line, "\n")
+          end
+          in_comment &= !line.end_with?('-->')
+        end
+
+        examples
+      end
+
+      def serialize(examples)
+        Array.wrap(examples).map { |exmpl|
+          header = [ ".#{exmpl.local_name}", exmpl.desc.presence ].compact
+
+          exmpl.opts.each do |name, vals|
+            Array.wrap(vals).each do |val|
+              header << (val == true ? ":#{name}:" : ":#{name}: #{val}")
+            end
+          end
+          header_str = header.one? ? (header.first + ' ') : (header.join("\n") + "\n")
+
+          [ "<!-- #{header_str}-->", exmpl.content.presence ].compact.join("\n") + "\n"
+        }.join("\n")
+      end
+
+      def create_example(*args)
+        Example.new(*args)
+      end
+
+      def convert_example(example, opts, renderer)
+        header_footer = !!opts[:header_footer] || example.name.start_with?('document')
+
+        html = renderer.render(example.to_s, header_footer: header_footer)
+        html = parse_html(html, !header_footer)
+
+        # When asserting inline examples, ignore paragraph "wrapper".
+        includes = opts[:include] || (@paragraph_xpath if example.name.start_with? 'inline_')
+
+        Array.wrap(includes).each do |xpath|
+          # XPath returns NodeSet, but we need DocumentFragment, so convert it again.
+          html = parse_html(html.xpath(xpath).to_html)
+        end
+
+        Array.wrap(opts[:exclude]).each do |xpath|
+          html.xpath(xpath).remove
+        end
+
+        html.normalize!
+
+        create_example example.name, content: html.to_s, opts: opts
+      end
+
+      private
+
+      def parse_html(str, fragment = true)
+        fragment ? ::Nokogiri::HTML.fragment(str) : ::Nokogiri::HTML.parse(str)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+require 'htmlbeautifier'
+
+module HtmlBeautifier
+
+  ##
+  # Beautifies the +input+ HTML.
+  #
+  # @param input [String, #to_html]
+  # @return [String] a beautified copy of the +input+.
+  #
+  def self.beautify(input)
+    input = input.to_html unless input.is_a? String
+    output = []
+    Beautifier.new(output).scan(input)
+    output.join
+  end
+end

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

@@ -0,0 +1,118 @@
+require 'active_support/core_ext/object/try'
+require 'nokogiri'
+
+module Asciidoctor::DocTest
+  module HTML
+    ##
+    # Module to be included into +Nokogiri::HTML::Document+
+    # or +DocumentFragment+ to add {#normalize!} feature.
+    #
+    # @example
+    #   Nokogiri::HTML.parse(str).normalize!
+    #   Nokogiri::HTML.fragment(str).normalize!
+    module Normalizer
+
+      ##
+      # Normalizes the HTML document or fragment so it can be easily compared
+      # with another HTML.
+      #
+      # What does it actually do?
+      #
+      # * sorts element attributes by name
+      # * sorts inline CSS declarations inside a +style+ attribute by name
+      # * removes all blank text nodes (i.e. node that contain just whitespaces)
+      # * strips nonsignificant leading and trailing whitespaces around text
+      # * strips nonsignificant repeated whitespaces
+      #
+      # @return [Object] self
+      #
+      def normalize!
+        traverse do |node|
+          case node.type
+
+          when Nokogiri::XML::Node::ELEMENT_NODE
+            sort_element_attrs! node
+            sort_element_style_attr! node
+
+          when Nokogiri::XML::Node::TEXT_NODE
+            # Remove text node that contains whitespaces only.
+            if node.blank?
+              node.remove
+
+            elsif !preformatted_block? node
+              strip_redundant_spaces! node
+              strip_spaces_around_text! node
+            end
+          end
+        end
+        self
+      end
+
+      private
+
+      # Sorts attributes of the element +node+ by name.
+      def sort_element_attrs!(node)
+        node.attributes.sort_by(&:first).each do |name, value|
+          node.delete(name)
+          node[name] = value
+        end
+      end
+
+      # Sorts CSS declarations in style attribute of the element +node+ by name.
+      def sort_element_style_attr!(node)
+        return unless node.has_attribute? 'style'
+        decls = node['style'].scan(/([\w-]+):\s*([^;]+);?/).sort_by(&:first)
+        node['style'] = decls.map { |name, val| "#{name}: #{val};" }.join(' ')
+      end
+
+      # Note: muttable methods like +gsub!+ doesn't work on node content.
+
+      # Strips repeated whitespaces in the text +node+.
+      def strip_redundant_spaces!(node)
+        node.content = node.content.gsub("\n", ' ').gsub(/(\s)+/, '\1')
+      end
+
+      # Strips nonsignificant leading and trailing whitespaces in the text +node+.
+      def strip_spaces_around_text!(node)
+        node.content = node.content.lstrip if text_block_boundary? node, :left
+        node.content = node.content.rstrip if text_block_boundary? node, :right
+      end
+
+      ##
+      # Returns +true+ if the text +node+ is the first (+:left+), or the last
+      # (+:right+) inline element of the nearest block element ancestor or
+      # direct sibling of +<br>+ element.
+      #
+      # @return [Boolean]
+      #
+      def text_block_boundary?(node, side)
+        method = { left: :previous_sibling, right: :next_sibling }[side]
+
+        return true if node.send(method).try(:name) == 'br'
+        loop do
+          if (sibling = node.send(method))
+            return false if sibling.text? || inline_element?(sibling)
+          end
+          node = node.parent
+          return true unless inline_element? node
+        end
+      end
+
+      HTML_INLINE_ELEMENTS = Nokogiri::HTML::ElementDescription::HTML_INLINE.flatten
+
+      # @return [Boolean] true if the +node+ represents an inline HTML element.
+      def inline_element?(node)
+        node.element? && HTML_INLINE_ELEMENTS.include?(node.name)
+      end
+
+      # @return [Boolean] true if the +node+ is descendant of +<pre>+ node.
+      def preformatted_block?(node)
+        node.path =~ %r{/pre/}
+      end
+    end
+  end
+end
+
+[Nokogiri::HTML::Document, Nokogiri::HTML::DocumentFragment].each do |klass|
+  klass.send :include, Asciidoctor::DocTest::HTML::Normalizer
+end