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
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 46 def attr(name, default_value = nil, inherit = diagram_type) raise NotImplementedError.new end
@return [String] the base directory against which relative paths in this diagram should be resolved @abstract
# File lib/asciidoctor-diagram/diagram_source.rb, line 52 def base_dir attr('docdir', nil, true) || Dir.pwd end
@return [String] the String representation of the source code for the diagram @abstract
# File lib/asciidoctor-diagram/diagram_source.rb, line 21 def code @code ||= load_code end
# File lib/asciidoctor-diagram/diagram_source.rb, line 80 def config raise NotImplementedError.new end
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 76 def create_image_metadata {} end
# File lib/asciidoctor-diagram/diagram_source.rb, line 11 def diagram_type raise NotImplementedError.new end
# File lib/asciidoctor-diagram/diagram_source.rb, line 141 def ensure_gem(name, version) begin gem_var = "gem-#{name}" unless config.key? gem_var gem(name, version) config[gem_var] = true end rescue Gem::LoadError => e msg = "You are using functionality that requires the optional gem dependency `#{e.name}` which could not be loaded. Add `gem '#{e.name}', '#{e.requirement}'` to your Gemfile." err = Gem::LoadError.new(msg) err.name = e.name err.requirement = e.requirement raise err end end
# File lib/asciidoctor-diagram/diagram_source.rb, line 84 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
# File lib/asciidoctor-diagram/diagram_source.rb, line 29 def global_attr(name, default_value = nil) attr(name) || attr(name, default_value, 'diagram') end
# File lib/asciidoctor-diagram/diagram_source.rb, line 15 def image_name raise NotImplementedError.new end
# File lib/asciidoctor-diagram/diagram_source.rb, line 25 def load_code raise NotImplementedError.new end
# File lib/asciidoctor-diagram/diagram_source.rb, line 157 def resolve_path target, start = base_dir raise NotImplementedError.new end
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 67 def should_process?(image_file, image_metadata) true end
Alias for code
# File lib/asciidoctor-diagram/diagram_source.rb, line 57 def to_s code end