class Giblish::DocConverter

Base class for document converters. It contains a hash of conversion options used by derived classes

Constants

COMMON_CONVERTER_OPTS

a common set of converter options used for all output formats

DEFAULT_ATTRIBUTES

the giblish attribute defaults used if nothing else is required by the user

Attributes

converter_options[R]

setup common options that are used regardless of the specific output format used

paths[RW]

the path manager used by this converter

Public Class Methods

new(paths, deployment_info, options) click to toggle source
# File lib/giblish/docconverter.rb, line 32
def initialize(paths, deployment_info, options)
  @paths = paths
  @deployment_info = deployment_info
  @user_style = options[:userStyle]
  @converter_options = COMMON_CONVERTER_OPTS.dup

  # use the default options and override them with options set by
  # the user if applicable
  @converter_options[:attributes] = DEFAULT_ATTRIBUTES.dup
  @converter_options[:attributes].merge!(options[:attributes]) unless options[:attributes].nil?
  @converter_options[:backend] = options[:backend]

  # give derived classes the opportunity to add options and attributes
  add_backend_options(@converter_options)
  add_backend_attributes(@converter_options[:attributes])
end

Public Instance Methods

convert(filepath, logger: nil) click to toggle source

Public: Convert one single adoc file using the specific conversion options.

filepath - a pathname with the absolute path to the input file to convert

Returns: The resulting Asciidoctor::Document object

# File lib/giblish/docconverter.rb, line 55
def convert(filepath, logger: nil)
  raise ArgumentError, "Trying to invoke convert with non-pathname!" unless filepath.is_a?(Pathname)

  Giblog.logger.info { "Processing: #{filepath}" }

  # update the relevant options for each specific document
  set_common_doc_specific_options(filepath, logger)

  # give derived classes the opportunity to set doc specific attributes
  add_doc_specific_attributes(filepath, true, @converter_options[:attributes])

  Giblog.logger.debug { "converter_options: #{@converter_options}" }

  # do the actual conversion
  doc = Asciidoctor.convert_file filepath, @converter_options

  # bail out if asciidoctor failed to convert the doc
  if logger&.max_severity && logger.max_severity > Logger::Severity::WARN
    raise "Failed to convert the file #{filepath}"
  end

  doc
end
convert_str(src_str, dst_dir, basename, logger: nil) click to toggle source

converts the supplied string to the file dst_dir/basename.<backend-ext>

the supplied string must pass asciidoctor without any error to stderr, otherwise, nothing will be written to disk. Returns: whether any errors occured during conversion (true) or not (false).

# File lib/giblish/docconverter.rb, line 87
def convert_str(src_str, dst_dir, basename, logger: nil)
  index_opts = @converter_options.dup

  # use the same options as when converting all docs
  # in the tree but make sure we don't write to file
  # by trial and error, the following dirs seem to be
  # necessary to change
  index_opts[:to_dir] = dst_dir.to_s
  index_opts[:base_dir] = dst_dir.to_s
  index_opts.delete_if { |k, _v| %i[to_file].include? k }

  # give derived classes the opportunity to set doc specific attributes
  index_filepath = dst_dir + "#{basename}.#{index_opts[:fileext]}"
  add_doc_specific_attributes(index_filepath, false, index_opts[:attributes])

  # load and convert the document using the converter options
  begin
    conv_error = false
    # set a specific logger instance to-be-used by asciidoctor
    index_opts[:logger] = logger unless logger.nil?
    doc = Asciidoctor.load src_str, index_opts
    output = doc.convert index_opts

    if logger&.max_severity && logger.max_severity > Logger::Severity::WARN
      raise "Failed to convert string to asciidoc!! "\
            "Will _not_ generate #{index_filepath}"
    end

    # write the converted document to an index file located at the
    # destination root
    doc.write output, index_filepath.to_s
  rescue StandardError => e
    puts e.backtrace
    Giblog.logger.error(e)
    conv_error = true
  end

  conv_error
end

Protected Instance Methods

add_backend_attributes(backend_attributes) click to toggle source

Hook for specific converters to inject their own attributes valid for all conversions. backend_attributes - the attribute dict from the backend implementation

# File lib/giblish/docconverter.rb, line 142
def add_backend_attributes(backend_attributes)
  @converter_options[:attributes].merge!(backend_attributes)
end
add_backend_options(backend_options) click to toggle source

Hook for specific converters to inject their own options. The following options must be provided by the derived class:

:fileext - a string with the filename extention to use for the
           generated file

backend_options - the option dict from the backend implementation

# File lib/giblish/docconverter.rb, line 135
def add_backend_options(backend_options)
  @converter_options.merge!(backend_options)
end
add_doc_specific_attributes(filepath, is_src, attributes) click to toggle source

Hook for specific converters to inject attributes on a per-doc basis

# File lib/giblish/docconverter.rb, line 148
def add_doc_specific_attributes(filepath, is_src, attributes); end

Private Instance Methods

set_common_doc_specific_options(src_filepath, logger) click to toggle source
# File lib/giblish/docconverter.rb, line 152
def set_common_doc_specific_options(src_filepath, logger)
  # create an asciidoc doc object and convert to requested
  # output using current conversion options
  @converter_options[:to_dir] = @paths.adoc_output_dir(src_filepath).to_s
  @converter_options[:base_dir] =
    Giblish::PathManager.closest_dir(src_filepath).to_s
  @converter_options[:to_file] =
    Giblish::PathManager.get_new_basename(src_filepath,
                                          @converter_options[:fileext])
  @converter_options[:logger] = logger unless logger.nil?
end