asciidoctor-doctest 1.5.0

data/lib/asciidoctor/doctest/asciidoc_renderer.rb

@@ -0,0 +1,103 @@
+require 'active_support/core_ext/array/wrap'
+require 'asciidoctor'
+require 'asciidoctor/converter/template'
+
+module Asciidoctor
+  module DocTest
+    ##
+    # This class is basically a wrapper for +Asciidoctor.render+ that allows to
+    # preset and validate some common parameters.
+    class AsciidocRenderer
+
+      attr_reader :backend_name, :converter, :template_dirs
+
+      ##
+      # @param backend_name [#to_s] the name of the tested backend.
+      #
+      # @param converter [Class, Asciidoctor::Converter::Base, nil]
+      #        the backend's converter class (or its instance). If not
+      #        specified, the default converter for the specified backend will
+      #        be used.
+      #
+      # @param template_dirs [Array<String>, String] path of the directory (or
+      #        multiple directories) where to look for the backend's templates.
+      #        Relative paths are referenced from the working directory.
+      #
+      # @param templates_fallback [Boolean] allow to fall back to using an
+      #        appropriate built-in converter when there is no required
+      #        template in the tested backend?
+      #        This is actually a default behaviour in Asciidoctor, but since
+      #        it's inappropriate for testing of custom backends, it's disabled
+      #        by default.
+      #
+      # @raise [ArgumentError] if some path from the +template_dirs+ doesn't
+      #        exist or is not a directory.
+      #
+      def initialize(backend_name: nil, converter: nil, template_dirs: [],
+                     templates_fallback: false)
+
+        @backend_name = backend_name.freeze
+        @converter = converter
+        @converter ||= TemplateConverterAdapter unless template_dirs.empty? || templates_fallback
+
+        template_dirs = Array.wrap(template_dirs).freeze
+
+        unless template_dirs.all? { |path| Dir.exist? path }
+          fail ArgumentError, "Templates directory '#{path}' doesn't exist!"
+        end
+        @template_dirs = template_dirs unless template_dirs.empty?
+      end
+
+      ##
+      # Renders the given +text+ in AsciiDoc syntax with Asciidoctor using the
+      # tested backend.
+      #
+      # @param text [#to_s] the input text in AsciiDoc syntax.
+      # @param opts [Hash] options to pass to Asciidoctor.
+      # @return [String] rendered input.
+      #
+      def render(text, opts = {})
+        renderer_opts = {
+          safe: :safe,
+          backend: backend_name,
+          converter: converter,
+          template_dirs: template_dirs
+        }.merge(opts)
+
+        Asciidoctor.render(text.to_s, renderer_opts)
+      end
+    end
+
+    ##
+    # @private
+    # Adapter for +Asciidoctor::Converter::TemplateConverter+.
+    class TemplateConverterAdapter < SimpleDelegator
+
+      # Placeholder to be written in a rendered output in place of the node's
+      # content that cannot be rendered due to missing template.
+      NOT_FOUND_MARKER = '--TEMPLATE NOT FOUND--'
+
+      def initialize(backend, opts = {})
+        super Asciidoctor::Converter::TemplateConverter.new(backend, opts[:template_dirs], opts)
+      end
+
+      ##
+      # Delegates to the template converter and returns results, or prints
+      # warning and returns {NOT_FOUND_MARKER} if there is no template to
+      # handle the specified +template_name+.
+      def convert(node, template_name = nil, opts = {})
+        template_name ||= node.node_name
+
+        if handles? template_name
+          super
+        else
+          warn "Could not find a custom template to handle template_name: #{template_name}"
+          NOT_FOUND_MARKER
+        end
+      end
+
+      # Alias for backward compatibility.
+      alias_method :convert_with_options, :convert
+    end
+  end
+end

data/lib/asciidoctor/doctest/base_example.rb

@@ -0,0 +1,161 @@
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/object/deep_dup'
+require 'active_support/core_ext/object/instance_variables'
+
+module Asciidoctor
+  module DocTest
+    ##
+    # This class represents a single test example.
+    class BaseExample
+
+      NAME_SEPARATOR = ':'
+
+      # @return [String] the first part of the name.
+      attr_accessor :group_name
+
+      # @return [String] the second part of the name.
+      attr_accessor :local_name
+
+      # @return [String] raw content.
+      attr_accessor :content
+
+      # @return [String] description.
+      attr_accessor :desc
+
+      # @return [Hash] options.
+      attr_accessor :opts
+
+      ##
+      # @param name (see #name=)
+      # @param content [String]
+      # @param desc [String] description
+      # @param opts [Hash] options
+      #
+      def initialize(name, content: '', desc: '', opts: {})
+        self.name = name
+        @content = content
+        @desc = desc
+        @opts = opts
+      end
+
+      ##
+      # @return [String] the name in format +group_name:local_name+.
+      def name
+        [@group_name, @local_name].join(NAME_SEPARATOR)
+      end
+
+      ##
+      # @param name [String, Array<String>] a String in format
+      #        +group_name:local_name+, or an Array with the group_name and the
+      #        local_name.
+      def name=(*name)
+        name.flatten!
+        @group_name, @local_name = name.one? ? name.first.split(NAME_SEPARATOR, 2) : name
+      end
+
+      ##
+      # @param pattern [String] the glob pattern (e.g. +block_*:with*+).
+      # @return [Boolean] +true+ if the name matches against the +pattern+,
+      #         +false+ otherwise.
+      def name_match?(pattern)
+        globs = pattern.split(NAME_SEPARATOR, 2)
+        [group_name, local_name].zip(globs).all? do |name, glob|
+          File.fnmatch? glob || '*', name.to_s
+        end
+      end
+
+      ##
+      # Returns value(s) of the named option.
+      #
+      # @param name [#to_sym] the option name.
+      # @return [Array<String>, Boolean] the option value.
+      #
+      def [](name)
+        @opts[name.to_sym]
+      end
+
+      ##
+      # Sets or unsets the option.
+      #
+      # @param name [#to_sym] the option name.
+      # @param value [Array<String>, Boolean, String, nil] the option value;
+      #        +Array+ and +Boolean+ are just assigned to the option, +nil+
+      #        removes the option and others are added to the option as an
+      #        array item.
+      #
+      def []=(name, value)
+        case value
+        when nil
+          @opts.delete(name.to_sym)
+        when Array, TrueClass, FalseClass
+          @opts[name.to_sym] = value.deep_dup
+        else
+          (@opts[name.to_sym] ||= []) << value.dup
+        end
+      end
+
+      ##
+      # @return [Boolean] +true+ when the content is blank, +false+ otherwise.
+      def empty?
+        content.blank?
+      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 The default implementation returns content as-is; subclasses
+      # should override this method.
+      #
+      # @return [String] a human-readable (formatted) version of the content.
+      #
+      def to_s
+        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+.
+      def ==(other)
+        [:group_name, :local_name, :content_normalized].all? do |name|
+          other.respond_to?(name) &&
+            public_send(name) == other.public_send(name)
+        end
+      end
+
+      ##
+      # @param other [Object] the object to compare with.
+      # @return [Boolean] +true+ if +self+ and +other+ are instances of the same
+      #         class and all their attributes are equal (compared using +==+),
+      #         otherwise +false+.
+      def eql?(other)
+        self.class == other.class &&
+          instance_variables == other.instance_variables
+      end
+
+      # :nocov:
+      def hash
+        self.class.hash ^ instance_variables.hash
+      end
+      # :nocov:
+
+      private
+
+      def initialize_copy(source)
+        instance_variables.each do |name|
+          instance_variable_set name, instance_variable_get(name).deep_dup
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/doctest/base_examples_suite.rb

@@ -0,0 +1,188 @@
+require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/array/wrap'
+require 'active_support/core_ext/class/attribute'
+require 'pathname'
+
+module Asciidoctor
+  module DocTest
+    ##
+    # @abstract
+    # This is a base class that should be extended for specific example
+    # formats.
+    class BaseExamplesSuite
+
+      attr_reader :examples_path, :file_ext
+
+      ##
+      # @param file_ext [String] the filename extension (e.g. +.adoc+) of the
+      #        examples group files.
+      #
+      # @param examples_path [String, Array<String>] path of the directory (or
+      #        multiple directories) where to look for the examples.
+      #
+      def initialize(file_ext:, examples_path: DocTest.examples_path)
+        @file_ext = file_ext.freeze
+        @examples_path = Array.wrap(examples_path).freeze
+        @examples_cache = {}
+      end
+
+      ##
+      # Parses group of examples from the +input+ and returns array of the
+      # parsed examples.
+      #
+      # @abstract
+      # @param input [#each_line] the file content to parse.
+      # @param group_name [String] the examples group name.
+      # @return [Array<BaseExample>] parsed examples.
+      # :nocov:
+      def parse(input, group_name)
+        fail NotImplementedError
+      end
+      # :nocov:
+
+      ##
+      # Serializes the given examples into string.
+      #
+      # @abstract
+      # @param examples [Array<BaseExample>]
+      # @return [String]
+      # :nocov:
+      def serialize(examples)
+        fail NotImplementedError
+      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 [#render]
+      # @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
+      # suite.
+      #
+      # When some example is missing in this or the +other_suite+, it's
+      # substituted with an empty example of the corresponding type and name.
+      # In the case of missing example from this suite, the pair is placed at
+      # the end of the examples group.
+      #
+      # @param other_suite [BaseExamplesSuite]
+      # @return [Enumerator]
+      #
+      def pair_with(other_suite)
+        Enumerator.new do |y|
+          group_names.each do |group_name|
+            theirs_by_name = other_suite.read_examples(group_name).index_by(&:name)
+
+            read_examples(group_name).each do |ours|
+              theirs = theirs_by_name.delete(ours.name)
+              theirs ||= other_suite.create_example(ours.name)
+              y.yield ours, theirs
+            end
+
+            theirs_by_name.each_value do |theirs|
+              y.yield create_example(theirs.name), theirs
+            end
+          end
+        end
+      end
+
+      ##
+      # Reads the named examples group from file(s). When multiple matching
+      # files are found on the {#examples_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}).
+      #
+      # @param group_name [String] the examples group name.
+      # @return [Array<Example>] an array of parsed examples, or an empty array
+      #         if no file found.
+      #
+      def read_examples(group_name)
+        @examples_cache[group_name] ||= read_files(group_name)
+          .map { |data| parse(data, group_name) }
+          .flatten
+          .uniq(&:name)
+      end
+
+      ##
+      # Writes the given examples into file(s)
+      # +{examples_path.first}/{group_name}{file_ext}+. Already existing files
+      # will be overwritten!
+      #
+      # @param examples [Array<BaseExample>]
+      #
+      def write_examples(examples)
+        examples.group_by(&:group_name).each do |group_name, exmpls|
+          path = file_path(@examples_path.first, group_name)
+          File.write(path, serialize(exmpls))
+        end
+      end
+
+      ##
+      # Replaces existing examples with the given ones.
+      #
+      # @param examples [Array<BaseExample] the updated examples.
+      # @see #write_examples
+      #
+      def update_examples(examples)
+        examples.group_by(&:group_name).each do |group, exmpls|
+          # replace cached examples with the given ones and preserve original order
+          updated_group = [ read_examples(group), exmpls ]
+            .map_send(:index_by, &:local_name)
+            .reduce(:merge)
+            .values
+
+          write_examples updated_group
+          @examples_cache.delete(group)  # flush cache
+        end
+      end
+
+      ##
+      # Returns names of all the example groups (files with {#file_ext})
+      # found on the {#examples_path}.
+      #
+      # @return [Array<String>]
+      #
+      def group_names
+        @examples_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 }
+        }.sort
+      end
+
+      private
+
+      def read_files(file_name)
+        @examples_path
+          .map { |dir| file_path(dir, file_name) }
+          .select(&:readable?)
+          .map(&:read)
+      end
+
+      def file_path(base_dir, file_name)
+        Pathname.new(base_dir).join(file_name).sub_ext(@file_ext)
+      end
+    end
+  end
+end