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
setup common options that are used regardless of the specific output format used
the path manager used by this converter
Public Class Methods
# 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
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
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
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
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
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
# 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