giblish 0.8.2 → 2.0.0.pre.alpha1

data/lib/giblish/search/textsearcher.rb

@@ -0,0 +1,349 @@
+require "pathname"
+require "json"
+require_relative "searchquery"
+require_relative "../pathtree"
+
+module Giblish
+  # reads all lines in the given file at instantiation and
+  # washes the text from some adoc formatting sequences.
+  class LoadAdocSrcFromFile
+    attr_reader :src_lines
+
+    def initialize(filepath)
+      @src_lines = []
+      File.readlines(filepath.to_s, chomp: true, encoding: "UTF-8").each do |line|
+        @src_lines << wash_line(line)
+      end
+    end
+
+    private
+
+    def wash_line(line)
+      # remove some asciidoctor format sequences
+      # '::', '^|===', '^==', '^--, ':myvar: ...'
+      r = Regexp.new(/(::+|^[=|]+|^--+|^:\w+:.*$)/)
+      line.gsub(r, "")
+    end
+  end
+
+  # Encapsulates raw data and information deducable from one
+  # search query
+  class SearchParameters
+    # a hash with { param => value } of all query parameters from the URI.
+    attr_reader :parameters
+    attr_reader :uri
+
+    def self.from_uri(uri_str, uri_mappings: {"/" => "/var/www/html/"})
+      q = SearchQuery.new(uri: uri_str)
+      SearchParameters.new(query: q, uri_mappings: uri_mappings)
+    end
+
+    def self.from_hash(h, uri_mappings: {"/" => "/var/www/html/"})
+      q = SearchQuery.new(query_params: h)
+      SearchParameters.new(query: q, uri_mappings: uri_mappings)
+    end
+
+    # the fragment of the calling doc's URI
+    # eg: www.mysite.com/my/doc/path/subdir1/doc1.html -> uri_path = my/doc/path/subdir1/doc1.html
+    def uri_path
+      URI(calling_url).path
+    end
+
+    # the URI path to the search asset directory
+    # eg: www.mysite.com/my/doc/path/subdir1/doc1.html could be assets_uri_path = my/doc/path/gibsearch_assets
+    def assets_uri_path
+      @assets_uri_path ||= Pathname.new(uri_path).dirname.join(search_assets_top_rel).cleanpath
+      @assets_uri_path
+    end
+
+    # the URI path to the css file to use for styling the search result
+    # eg: www.mysite.com/my/doc/path/subdir1/doc1.html could be css_path = my/doc/path/web/mystyle.css
+    def css_path
+      return nil if @query.css_path.nil?
+
+      return @query.css_path if @query.css_path.absolute?
+
+      # css paths from the query is relative, add it to the
+      @css_path ||= Pathname.new(uri_path).dirname.join(@query.css_path).cleanpath
+      @css_path
+    end
+
+    # return:: the uri path pointing to the doc repo top dir
+    def uri_path_repo_top
+      Pathname.new(uri_path).join(search_assets_top_rel.dirname).dirname
+    end
+
+    # return:: the absolute Pathname of the file system path to the
+    # search assets top dir.
+    def assets_fs_path
+      uri_to_fs(assets_uri_path)
+    end
+
+    def method_missing(meth, *args, &block)
+      return @query.send(meth, *args, &block) if respond_to_missing?(meth)
+
+      super(meth, args, &block)
+    end
+
+    def respond_to_missing?(meth, include_private = false)
+      @query.respond_to?(meth)
+    end
+
+    # return:: the relative path from the doc top dir to the file
+    def repo_file_path
+      Pathname.new(uri_path).relative_path_from(uri_path_repo_top)
+    end
+
+    # repo_filepath:: the filepath from the repo top to a given file
+    # fragment:: the fragment id or nil
+    #
+    # return:: the access url for a given section in a given src file
+    def url(repo_filepath, fragment = nil)
+      p = Pathname.new(repo_filepath)
+
+      # create result by replacing relevant parts of the original uri
+      res = URI(@query.calling_url)
+      res.query = nil
+      res.fragment = fragment
+      res.path = uri_path_repo_top.join(p.sub_ext(".html")).cleanpath.to_s
+      res
+    end
+
+    private
+
+    # Search input:
+    #
+    # query:: a SearchQuery instance
+    # uri_mappings:: mappings between uri.path prefix and an absolute path in the local
+    #             file system. Ex {"/my/doc" => "/var/www/html/doc/repos"}. The default
+    #             is { "/" => "/var/www/html" }
+    #
+    # ex URI = www.example.com/search/action?calling-uri=www.example.com/my/doc/repo/subdir/file1.html&search-assets-top-rel=../my/docs&search-phrase=hejsan
+    def initialize(query:, uri_mappings: {"/" => "/var/www/html/"})
+      @query = query
+
+      # convert keys and values to Pathnames
+      @uri_mappings = uri_mappings.map { |k, v| [Pathname.new(k).cleanpath, Pathname.new(v).cleanpath] }.to_h
+      validate_parameters
+    end
+
+    # return:: a Pathname where the prefix of an uri path has been replaced with the
+    #          corresponding fs mapping, if one exists. Returns the original pathname
+    #          if no corresponding mapping exists.
+    #          if more than one mapping match, the longest is used.
+    def uri_to_fs(uri_path)
+      up = Pathname.new(uri_path).cleanpath
+      matches = {}
+
+      @uri_mappings.each do |key, value|
+        key_length = key.to_s.length
+        # we must treat '/' specially since its the only case where
+        # the key ends with a '/'
+        s = key.root? ? "" : key
+        tmp = up.sub(s.to_s, value.to_s).cleanpath
+        matches[key_length] = tmp if tmp != up
+      end
+      return up if matches.empty?
+
+      # return longest matching key
+      matches.max { |item| item[0] }[1]
+    end
+
+    # Require that:
+    #
+    # - a relative asset path is included
+    # - a search phrase is included
+    # - the uri_mappings map an absolute uri path to an absolute, and existing file
+    #   system path.
+    def validate_parameters
+      # asset_top_rel
+      raise ArgumentError, "Asset top must be relative, found '#{search_assets_top_rel}'" if search_assets_top_rel.absolute?
+
+      # uri_mapping
+      @uri_mappings.each do |k, v|
+        raise ArgumentError, "The uri path in the uri_mapping must be absolute, found: '#{k}'" unless k.absolute?
+        raise ArgumentError, "The file system directory path must be absolute, found: '#{v}'" unless v.absolute?
+        raise ArgumentError, "The file system diretory does not exist: '#{v}'" unless v.exist?
+        raise ArgumentError, "The uri_mapping must be a directory, found file: '#{v}'" unless v.directory?
+      end
+    end
+  end
+
+  # Provides access to all search related info for one tree
+  # of adoc src docs.
+  class SearchDataRepo
+    attr_reader :search_db, :src_tree, :db_mod_time
+
+    SEARCH_DB_BASENAME = "heading_db.json"
+
+    # assets_uri_path:: a Pathname to the top dir of the search asset folder
+    def initialize(assets_fs_path)
+      @assets_fs_path = assets_fs_path
+      @search_db = read_search_db
+      @src_tree = build_src_tree
+    end
+
+    # find section with closest lower line_no to line_info
+    # NOTE: line_no in is 1-based
+    def in_section(filepath, line_no)
+      i = info(filepath)
+      i[:sections].reverse.find { |section| line_no >= section[:line_no] }
+    end
+
+    # return:: the info from the repo for the given filepath or nil if no info
+    #          exists
+    def info(filepath)
+      @search_db[:fileinfos].find { |info| info[:filepath] == filepath.to_s }
+    end
+
+    def is_stale
+      @db_mod_time != File.stat(db_filepath.to_s).mtime
+    end
+
+    private
+
+    def build_src_tree
+      # setup the tree of source files and pro-actively read in all text
+      # into memory
+      src_tree = PathTree.build_from_fs(@assets_fs_path, prune: false) do |p|
+        p.extname.downcase == ".adoc"
+      end
+      src_tree.traverse_preorder do |level, node|
+        next unless node.leaf?
+
+        node.data = LoadAdocSrcFromFile.new(node.pathname)
+      end
+      src_tree
+    end
+
+    def db_filepath
+      @assets_fs_path.join(SEARCH_DB_BASENAME)
+    end
+
+    def read_search_db
+      # read the heading_db from file
+      @db_mod_time = File.stat(db_filepath.to_s).mtime
+      json = File.read(db_filepath.to_s)
+      JSON.parse(json, symbolize_names: true)
+    end
+  end
+
+  # Caches a number of SearchDataRepo instances in memory and returns the
+  # one corresponding to the given SearchParameters instance.
+  class SearchRepoCache
+    def initialize
+      @repos = {}
+    end
+
+    # search_parameters:: a SearchParameters instance
+    #
+    # returns:: the SearchDataRepo corresponding to the given search parameters
+    def repo(search_parameters)
+      ap = search_parameters.assets_fs_path
+
+      # check if we shall read a new repo from disk
+      if !@repos.key?(ap) || @repos[ap].is_stale
+        # Uncomment for debugging...
+        # puts "read from disk for ap: #{ap}.."
+        # puts "is stale" if @repos.key?(ap) && @repos[ap].is_stale
+        @repos[ap] = SearchDataRepo.new(ap)
+      end
+
+      @repos[ap]
+    end
+  end
+
+  # Provides text search capability for the given source repository.
+  class TextSearcher
+    def initialize(repo_cache)
+      @repo_cache = repo_cache
+    end
+
+    # transform the output from grep_tree to an Array of hashes according to:
+    #
+    # {Pathname("subdir/file1.adoc") => {
+    #   doc_title: "My doc!!",
+    #   sections: [{
+    #     url: URI("http://my.site.com/docs/repo1/file1.html#section_id_1"),
+    #     title: "Purpose",
+    #     lines: [
+    #       "this is the line with matching text",
+    #       "this is another line with matching text"
+    #     ]
+    #   }]
+    # }}
+    # search_params:: a SearchParameters instance
+    def search(search_params)
+      repo = @repo_cache.repo(search_params)
+
+      grep_results = grep_tree(repo, search_params)
+
+      search_result(repo, grep_results, search_params)
+    end
+
+    # result = {
+    #   filepath => [{
+    #     line_no: nil,
+    #     line: ""
+    #   }]
+    # }
+    def grep_tree(repo, search_params)
+      result = Hash.new { |h, k| h[k] = [] }
+
+      # handle case-sensitivity and input as regex pattern or string
+      r_flags = search_params.consider_case? ? 0 : Regexp::IGNORECASE
+      r_str = search_params.as_regexp? ? search_params.search_phrase : Regexp.escape(search_params.search_phrase)
+      r = Regexp.new(r_str, r_flags)
+
+      # find all matching lines in the src tree
+      repo.src_tree.traverse_preorder do |level, node|
+        next unless node.leaf?
+
+        relative_path = node.relative_path_from(repo.src_tree)
+        line_no = 0
+        node.data.src_lines.each do |line|
+          line_no += 1
+          next if line.empty? || !r.match?(line)
+
+          # replace match with an embedded rule that can
+          # be styled
+          result[relative_path] << {
+            line_no: line_no,
+            line: line.gsub(r, '[.red]##*_\0_*##')
+          }
+        end
+      end
+      result
+    end
+
+    # returns:: a hash described in the 'search' method doc
+    def search_result(repo, grep_result, search_params)
+      result = Hash.new { |h, k| h[k] = [] }
+
+      grep_result.each do |filepath, matches|
+        db = repo.info(filepath)
+        next if db.nil?
+
+        sect_to_match = Hash.new { |h, k| h[k] = [] }
+        matches.each do |match|
+          s = repo.in_section(filepath, match[:line_no])
+          sect_to_match[s] << match
+        end
+
+        sections = sect_to_match.collect do |section, matches|
+          {
+            url: search_params.url(filepath, section[:id]),
+            title: section[:title],
+            lines: matches.collect { |match| match[:line].chomp }
+          }
+        end
+
+        result[filepath] = {
+          doc_title: db[:title],
+          sections: sections
+        }
+      end
+      result
+    end
+  end
+end

data/lib/giblish/subtreeinfobuilder.rb

@@ -0,0 +1,77 @@
+require "pathname"
+require_relative "pathtree"
+
+module Giblish
+  class SubtreeSrcItf
+    attr_reader :adoc_source
+    def initialize(dst_node, output_basename)
+      raise NotImplementedError
+    end
+  end
+
+  class SubtreeInfoBuilder
+    attr_accessor :docattr_provider
+
+    DEFAULT_BASENAME = "index"
+
+    # docattr_provider:: an object implementing the DocAttributesBase interface
+    # api_opt_provider:: an object implementing the api_options(dst_top) interface
+    # adoc_src_provider:: a Class or object implementing the SubtreeSrcItf interface
+    # basename:: the name of the output file that is generated in each directory
+    def initialize(docattr_provider = nil, api_opt_provider = nil, adoc_src_provider = nil, basename = DEFAULT_BASENAME)
+      @docattr_provider = docattr_provider
+      @api_opt_provider = api_opt_provider
+      @adoc_src_provider = adoc_src_provider || SubtreeIndexBase
+      @basename = basename
+      @adoc_source = nil
+    end
+
+    def document_attributes(src_node, dst_node, dst_top)
+      @docattr_provider.nil? ? {} : @docattr_provider.document_attributes(src_node, dst_node, dst_top)
+    end
+
+    def api_options(src_node, dst_node, dst_top)
+      @api_opt_provider.nil? ? {} : @api_opt_provider.api_options(dst_top)
+    end
+
+    def adoc_source(src_node, dst_node, dst_top)
+      @adoc_source
+    end
+
+    # Called from TreeConverter during post build phase
+    #
+    # adds a 'index' node for each directory in the source tree
+    # and convert that index using the options from the provider
+    # objects given at instantiation of this object
+    def on_postbuild(src_tree, dst_tree, converter)
+      dst_tree.traverse_preorder do |level, dst_node|
+        # we only care about directories
+        next if dst_node.leaf?
+
+        # get the relative path to the index dir from the top dir
+        index_dir = dst_node.pathname.relative_path_from(dst_tree.pathname).cleanpath
+        Giblog.logger.debug { "Creating #{@basename} under #{index_dir}" }
+
+        # get the adoc source from the provider (Class or instance)
+        @adoc_source = if @adoc_src_provider.is_a?(Class)
+          @adoc_src_provider.new(dst_node, @basename).adoc_source
+        else
+          @adoc_src_provider.adoc_source
+        end
+
+        # add a virtual 'index.adoc' node as the only node in a source tree
+        # with this object as source for conversion options
+        # and adoc_source
+        v_path = Pathname.new("/virtual") / index_dir / "#{@basename}.adoc"
+        v_tree = PathTree.new(v_path, self)
+        src_node = v_tree.node(v_path, from_root: true)
+
+        # add the destination node where the converted file will be stored
+        i_node = dst_node.add_descendants(@basename)
+
+        # do the conversion
+        converter.convert(src_node, i_node, dst_tree)
+      end
+    end
+  end
+end

data/lib/giblish/treeconverter.rb

@@ -0,0 +1,272 @@
+require "asciidoctor"
+require "asciidoctor-pdf"
+require_relative "pathtree"
+require_relative "conversion_info"
+require_relative "utils"
+
+module Giblish
+  # Converts all nodes in the supplied src PathTree from adoc to the format
+  # given by the user.
+  #
+  # Requires that all leaf nodes has a 'data' member that can receive an
+  # 'adoc_source' method that returns a string with the source to be converted.
+  #
+  # implements three phases with user hooks:
+  # pre_build -> build -> post_build
+  #
+  # Prebuild::
+  # add a pre_builder object that responds to:
+  # def run(src_tree, dst_tree, converter)
+  # where
+  # src_tree:: the node in a PathTree corresponding to the top of the
+  # src directory
+  # dst_tree:: the node in a PathTree corresponding to the top of the
+  # dst directory
+  # converter:: the specific converter used to convert the adoc source to
+  # the desired destination format.
+
+  class TreeConverter
+    attr_reader :dst_tree, :pre_builders, :post_builders, :converter
+
+    class << self
+      # register all asciidoctor extensions given at instantiation
+      #
+      # adoc_ext::
+      # { preprocessor: [], ... }
+      #
+      # see https://docs.asciidoctor.org/asciidoctor/latest/extensions/register/
+      def register_adoc_extensions(adoc_ext)
+        return if adoc_ext.nil?
+
+        %i[preprocessor tree_processor postprocessor docinfo_processor block
+          block_macro inline_macro include_processor].each do |e|
+          next unless adoc_ext.key?(e)
+
+          Array(adoc_ext[e])&.each do |c|
+            Giblog.logger.debug { "Register #{c.class} as #{e}" }
+            Asciidoctor::Extensions.register { send(e, c) }
+          end
+        end
+      end
+
+      def unregister_adoc_extenstions
+        Asciidoctor::Extensions.unregister_all
+      end
+    end
+
+    # opts:
+    #  logger: the logger used internally by this instance (default nil)
+    #  adoc_log_level - the log level when logging messages emitted by asciidoctor
+    #  (default Logger::Severity::WARN)
+    #  pre_builders
+    #  post_builders
+    #  adoc_api_opts
+    #  adoc_doc_attribs
+    #  conversion_cb {success: Proc(src,dst,adoc) fail: Proc(src,dst,exc)
+    def initialize(src_top, dst_top, opts = {})
+      # setup logging
+      @logger = opts.fetch(:logger, Giblog.logger)
+      @adoc_log_level = opts.fetch(:adoc_log_level, Logger::Severity::WARN)
+
+      # get the top-most node of the source and destination trees
+      @src_tree = src_top
+      @dst_tree = PathTree.new(dst_top).node(dst_top, from_root: true)
+
+      # setup build-phase callback objects
+      @pre_builders = Array(opts.fetch(:pre_builders, []))
+      @post_builders = Array(opts.fetch(:post_builders, []))
+      @converter = DefaultConverter.new(@logger, opts)
+      @adoc_ext = opts.fetch(:adoc_extensions, nil)
+    end
+
+    # abort_on_exc:: if true, an exception lower down the chain will
+    # abort the conversion and raised to the caller. If false, exceptions
+    # will be swallowed. In both cases, an 'error' log entry is created.
+    def run(abort_on_exc: true)
+      TreeConverter.register_adoc_extensions(@adoc_ext)
+      pre_build(abort_on_exc: abort_on_exc)
+      build(abort_on_exc: abort_on_exc)
+      post_build(abort_on_exc: abort_on_exc)
+    ensure
+      TreeConverter.unregister_adoc_extenstions
+    end
+
+    def pre_build(abort_on_exc: true)
+      @pre_builders.each do |pb|
+        pb.on_prebuild(@src_tree, @dst_tree, @converter)
+      rescue => ex
+        @logger&.error { ex.message.to_s }
+        raise ex if abort_on_exc
+      end
+    end
+
+    def build(abort_on_exc: true)
+      @src_tree.traverse_preorder do |level, n|
+        next unless n.leaf?
+
+        # create the destination node, using the correct suffix depending on conversion backend
+        rel_path = n.relative_path_from(@src_tree)
+        Giblog.logger.debug { "Creating dst node: #{rel_path}" }
+        dst_node = @dst_tree.add_descendants(rel_path)
+
+        # perform the conversion
+        @converter.convert(n, dst_node, @dst_tree)
+      rescue => exc
+        @logger&.error { "#{n.pathname} - #{exc.message}" }
+        raise exc if abort_on_exc
+      end
+    end
+
+    def post_build(abort_on_exc: true)
+      @post_builders.each do |pb|
+        pb.on_postbuild(@src_tree, @dst_tree, @converter)
+      rescue => exc
+        raise exc if abort_on_exc
+        @logger&.error { exc.message.to_s }
+      end
+    end
+
+    # the default callback will tie a 'SuccessfulConversion' instance
+    # to the destination node as its data
+    def self.on_success(src_node, dst_node, dst_tree, doc, adoc_log_str)
+      dst_node.data = DataDelegator.new(SuccessfulConversion.new(
+        src_node: src_node, dst_node: dst_node, dst_top: dst_tree, adoc: doc, adoc_stderr: adoc_log_str
+      ))
+    end
+
+    # the default callback will tie a 'FailedConversion' instance
+    # to the destination node as its data
+    def self.on_failure(src_node, dst_node, dst_tree, ex, adoc_log_str)
+      Giblog.logger.error { ex.message }
+      dst_node.data = DataDelegator.new(FailedConversion.new(
+        src_node: src_node, dst_node: dst_node, dst_top: dst_tree, error_msg: ex.message
+      ))
+    end
+  end
+
+  class DefaultConverter
+    attr_accessor :adoc_api_opts
+    # see https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-reference/
+    DEFAULT_ADOC_DOC_ATTRIBS = {
+      "data-uri" => true,
+      "hide-uri-scheme" => true,
+      "xrefstyle" => "short",
+      "source-highlighter" => "rouge",
+      "source-linenums-option" => true
+    }
+
+    # see https://docs.asciidoctor.org/asciidoctor/latest/api/options/
+    DEFAULT_ADOC_OPTS = {
+      backend: "html5",
+      # base_dir:
+      catalog_assets: false,
+      # converter:
+      doctype: "article",
+      # eruby:
+      # ignore extention stuff
+      header_only: false,
+      # logger:
+      mkdirs: false,
+      parse: true,
+      safe: :unsafe,
+      sourcemap: false,
+      # template stuff TBD,
+      # to_file:
+      # to_dir:
+      standalone: true
+    }
+
+    # opts:
+    #  adoc_log_level
+    #  adoc_api_opts
+    #  adoc_doc_attribs
+    #  conversion_cb {
+    #     success: lambda(src, dst, dst_rel_path, doc, logstr)
+    #     fail: lambda(src,dst,exc)
+    #  }
+    def initialize(logger, opts)
+      @logger = logger
+      @adoc_log_level = opts.fetch(:adoc_log_level, Logger::Severity::WARN)
+      @conv_cb = opts.fetch(:conversion_cb, {
+        success: ->(src, dst, dst_rel_path, doc, logstr) { TreeConverter.on_success(src, dst, dst_rel_path, doc, logstr) },
+        failure: ->(src, dst, dst_rel_path, ex, logstr) { TreeConverter.on_failure(src, dst, dst_rel_path, ex, logstr) }
+      })
+
+      # merge user's options with the default, giving preference
+      # to the user
+      @adoc_api_opts = DEFAULT_ADOC_OPTS.dup
+        .merge!(opts.fetch(:adoc_api_opts, {}))
+      @adoc_api_opts[:attributes] = DEFAULT_ADOC_DOC_ATTRIBS.dup
+        .merge!(opts.fetch(:adoc_doc_attribs, {}))
+    end
+
+    # require the following methods to be available from the src node:
+    # adoc_source
+    #
+    # the following methods will be called if supported:
+    # document_attributes
+    # api_options
+    #
+    # src_node:: the PathTree node containing the info on adoc source and any
+    # added api_options or doc_attributes
+    # dst_node:: the PathTree node where conversion info is to be stored
+    # dst_top:: the PathTree node representing the top dir of the destination
+    # under which all converted files are written.
+    def convert(src_node, dst_node, dst_top)
+      @logger&.info { "Converting #{src_node.pathname} and store result under #{dst_node.parent.pathname}" }
+
+      # merge the common api opts with node specific
+      api_opts = @adoc_api_opts.dup
+      api_opts.merge!(src_node.api_options(src_node, dst_node, dst_top)) if src_node.respond_to?(:api_options)
+      api_opts[:attributes].merge!(src_node.document_attributes(src_node, dst_node, dst_top)) if src_node.respond_to?(:document_attributes)
+
+      # use a new logger instance for each conversion
+      adoc_logger = Giblish::AsciidoctorLogger.new(@logger, @adoc_log_level)
+
+      begin
+        # load the source to enable access to doc properties
+        #
+        # NOTE: the 'parse: false' is needed to prevent preprocessor extensions to be run as part
+        # of loading the document. We want them to run during the 'convert' call later when
+        # doc attribs have been amended.
+        doc = Asciidoctor.load(src_node.adoc_source(src_node, dst_node, dst_top), api_opts.merge(
+          {
+            parse: false,
+            logger: adoc_logger
+          }
+        ))
+
+        # piggy-back our own info on the doc attributes hash so that
+        # asciidoctor extensions can use this info later on
+        doc.attributes["giblish-info"] = {
+          src_node: src_node,
+          dst_node: dst_node,
+          dst_top: dst_top
+        }
+
+        # update the destination node with the correct file suffix. This is dependent
+        # on the type of conversion performed
+        dst_node.name = dst_node.name.sub_ext(doc.attributes["outfilesuffix"])
+        d = dst_node.pathname
+
+        # make sure the dst dir exists
+        d.dirname.mkpath
+
+        # write the converted doc to the file
+        output = doc.convert(api_opts.merge({logger: adoc_logger}))
+        doc.write(output, d.to_s)
+
+        # give user the opportunity to eg store the result of the conversion
+        # as data in the destination node
+        @conv_cb[:success]&.call(src_node, dst_node, dst_top, doc, adoc_logger.in_mem_storage.string)
+        true
+      rescue => ex
+        @logger&.error { "Conversion failed for #{src_node.pathname}" }
+        @logger&.error { ex.message }
+        @logger&.error { ex.backtrace }
+        @conv_cb[:failure]&.call(src_node, dst_node, dst_top, ex, adoc_logger.in_mem_storage.string)
+        false
+      end
+    end
+  end
+end