Class: Giblish::TreeConverter

Inherits:
Object
  • Object
show all
Defined in:
lib/giblish/treeconverter.rb

Overview

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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(src_top, dst_top, opts = {}) ⇒ TreeConverter

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)



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/giblish/treeconverter.rb', line 66

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

Instance Attribute Details

#converter ⇒ Object (readonly)

Returns the value of attribute converter.



29
30
31
 
# File 'lib/giblish/treeconverter.rb', line 29

def converter
  @converter
end

#dst_tree ⇒ Object (readonly)

Returns the value of attribute dst_tree.



29
30
31
 
# File 'lib/giblish/treeconverter.rb', line 29

def dst_tree
  @dst_tree
end

#post_builders ⇒ Object (readonly)

Returns the value of attribute post_builders.



29
30
31
 
# File 'lib/giblish/treeconverter.rb', line 29

def post_builders
  @post_builders
end

#pre_builders ⇒ Object (readonly)

Returns the value of attribute pre_builders.



29
30
31
 
# File 'lib/giblish/treeconverter.rb', line 29

def pre_builders
  @pre_builders
end

Class Method Details

.on_failure(src_node, dst_node, dst_tree, ex, adoc_log_str) ⇒ Object

the default callback will tie a ‘FailedConversion’ instance to the destination node as its data



139
140
141
142
143
144
 
# File 'lib/giblish/treeconverter.rb', line 139

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

.on_success(src_node, dst_node, dst_tree, doc, adoc_log_str) ⇒ Object

the default callback will tie a ‘SuccessfulConversion’ instance to the destination node as its data



131
132
133
134
135
 
# File 'lib/giblish/treeconverter.rb', line 131

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

.register_adoc_extensions(adoc_ext) ⇒ Object

register all asciidoctor extensions given at instantiation

adoc_ext

{ preprocessor: [], … }

see docs.asciidoctor.org/asciidoctor/latest/extensions/register/



38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/giblish/treeconverter.rb', line 38

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

.unregister_adoc_extenstions ⇒ Object 



52
53
54
 
# File 'lib/giblish/treeconverter.rb', line 52

def unregister_adoc_extenstions
  Asciidoctor::Extensions.unregister_all
end

Instance Method Details

#build(abort_on_exc: true) ⇒ Object 



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/giblish/treeconverter.rb', line 103

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

#post_build(abort_on_exc: true) ⇒ Object 



120
121
122
123
124
125
126
127
 
# File 'lib/giblish/treeconverter.rb', line 120

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

#pre_build(abort_on_exc: true) ⇒ Object 



94
95
96
97
98
99
100
101
 
# File 'lib/giblish/treeconverter.rb', line 94

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

#run(abort_on_exc: true) ⇒ Object

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.



85
86
87
88
89
90
91
92
 
# File 'lib/giblish/treeconverter.rb', line 85

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