module Asciidoctor::Diagram::DiagramSource

This module describes the duck-typed interface that diagram sources must implement. Implementations may include this module but it is not required.

Public Instance Methods

attr(name, default_value = nil, inherit = diagram_type) click to toggle source

Get the value for the specified attribute. First look in the attributes on this document and return the value of the attribute if found. Otherwise, if this document is a child of the Document document, look in the attributes of the Document document and return the value of the attribute if found. Otherwise, return the default value, which defaults to nil.

@param name [String, Symbol, Array] the name(s) of the attribute to lookup @param default_value [Object] the value to return if the attribute is not found @inherit [Boolean, String] indicates whether to check for the attribute on the AsciiDoctor::Document if not found on this document.

When a non-nil String is given the an attribute name "#{inherit}-#{name}" is looked for on the document.

@return the value of the attribute or the default value if the attribute is not found in the attributes of this node or the document node @abstract

# File lib/asciidoctor-diagram/diagram_source.rb, line 42
def attr(name, default_value = nil, inherit = diagram_type)
  raise NotImplementedError.new
end
base_dir() click to toggle source

@return [String] the base directory against which relative paths in this diagram should be resolved @abstract

# File lib/asciidoctor-diagram/diagram_source.rb, line 48
def base_dir
  attr('docdir', nil, true) || Dir.pwd
end
code() click to toggle source

@return [String] the String representation of the source code for the diagram @abstract

# File lib/asciidoctor-diagram/diagram_source.rb, line 21
def code
  raise NotImplementedError.new
end
config() click to toggle source
# File lib/asciidoctor-diagram/diagram_source.rb, line 76
def config
  raise NotImplementedError.new
end
create_image_metadata() click to toggle source

Creates an image metadata Hash that will be stored to disk alongside the generated image file. The contents of this Hash are reread during subsequent document processing and then passed to the should_process? method where it can be used to determine if the diagram should be regenerated or not. The default implementation returns an empty Hash. @return [Hash] a Hash containing metadata

# File lib/asciidoctor-diagram/diagram_source.rb, line 72
def create_image_metadata
  {}
end
diagram_type() click to toggle source
# File lib/asciidoctor-diagram/diagram_source.rb, line 11
def diagram_type
  raise NotImplementedError.new
end
find_command(cmd, options = {}) click to toggle source
# File lib/asciidoctor-diagram/diagram_source.rb, line 80
def find_command(cmd, options = {})
  attr_names = options[:attrs] || options.fetch(:alt_attrs, []) + [cmd]
  cmd_names = [cmd] + options.fetch(:alt_cmds, [])

  cmd_var = 'cmd-' + attr_names[0]

  if config.key? cmd_var
    cmd_path = config[cmd_var]
  else
    logger.debug "Finding '#{cmd}' in attributes"
    cmd_path = attr_names.map { |attr_name|
                           attr = attr(attr_name, nil, true)
                           if logger.debug? && attr
                             logger.debug "Found value '#{attr}' in attribute '#{attr_name}'" if attr
                           end
                           attr
                         }
                         .reject { |attr| attr.nil? }
                         .map { |attr|
                           expanded = File.expand_path(attr)
                           if logger.debug? && attr != expanded
                             logger.debug "Expanded '#{attr}' to '#{expanded}'"
                           end
                           expanded
                         }
                         .select { |path|
                           executable = File.executable?(path)
                           if logger.debug?
                             logger.debug "Is '#{path}' executable? #{executable}"
                           end
                           executable
                         }
                         .first

    unless cmd_path
      logger.debug "Finding '#{cmd}' in environment"
      cmd_path = cmd_names.map { |c|
                       path = ::Asciidoctor::Diagram::Which.which(c, :path => options[:path])
                       if logger.debug? && path
                         logger.debug "Found '#{path}' in environment"
                       end
                       path
                     }
                     .reject { |path| path.nil? }
                     .first
    end

    config[cmd_var] = cmd_path

    if cmd_path.nil? && options.fetch(:raise_on_error, true)
      raise "Could not find the #{cmd_names.map { |c| "'#{c}'" }.join(', ')} executable in PATH; add it to the PATH or specify its location using the '#{attr_names[0]}' document attribute"
    end
  end

  cmd_path
end
global_attr(name, default_value = nil) click to toggle source
# File lib/asciidoctor-diagram/diagram_source.rb, line 25
def global_attr(name, default_value = nil)
  attr(name) || attr(name, default_value, 'diagram')
end
image_name() click to toggle source
# File lib/asciidoctor-diagram/diagram_source.rb, line 15
def image_name
  raise NotImplementedError.new
end
resolve_path(target, start = base_dir) click to toggle source
# File lib/asciidoctor-diagram/diagram_source.rb, line 137
def resolve_path target, start = base_dir
  raise NotImplementedError.new
end
should_process?(image_file, image_metadata) click to toggle source

Determines if the diagram should be regenerated or not. The default implementation of this method simply returns true.

@param image_file [String] the path to the previously generated version of the image @param image_metadata [Hash] the image metadata Hash that was stored during the previous diagram generation pass @return [Boolean] true if the diagram should be regenerated; false otherwise

# File lib/asciidoctor-diagram/diagram_source.rb, line 63
def should_process?(image_file, image_metadata)
  true
end
to_s() click to toggle source

Alias for code

# File lib/asciidoctor-diagram/diagram_source.rb, line 53
def to_s
  code
end