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)



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

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 = Gran::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.



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

def converter
  @converter
end

#dst_tree ⇒ Object (readonly)

Returns the value of attribute dst_tree.



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

def dst_tree
  @dst_tree
end

#post_builders ⇒ Object (readonly)

Returns the value of attribute post_builders.



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

def post_builders
  @post_builders
end

#pre_builders ⇒ Object (readonly)

Returns the value of attribute pre_builders.



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

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, wrapped in NodeDataProvider to allow dynamic addition of other providers (e.g., history)



143
144
145
146
147
148
149
 
# File 'lib/giblish/treeconverter.rb', line 143

def self.on_failure(src_node, dst_node, dst_tree, ex, adoc_log_str)
  Giblog.logger.error { ex.message }
  conversion_info = FailedConversion.new(
    src_node: src_node, dst_node: dst_node, dst_top: dst_tree, error_msg: ex.message
  )
  dst_node.data = NodeDataProvider.new(conversion_info)
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, wrapped in NodeDataProvider to allow dynamic addition of other providers (e.g., history)



133
134
135
136
137
138
 
# File 'lib/giblish/treeconverter.rb', line 133

def self.on_success(src_node, dst_node, dst_tree, doc, adoc_log_str)
  conversion_info = SuccessfulConversion.new(
    src_node: src_node, dst_node: dst_node, dst_top: dst_tree, adoc: doc, adoc_stderr: adoc_log_str
  )
  dst_node.data = NodeDataProvider.new(conversion_info)
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/



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

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 



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

def unregister_adoc_extenstions
  Asciidoctor::Extensions.unregister_all
end

Instance Method Details

#build(abort_on_exc: true) ⇒ Object 



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

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 



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

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 



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

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.



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

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