Module: Asciidoctor::Diagram::DiagramSource

Includes:
Logging
Included in:
BasicSource, ReaderSource, ServerSource
Defined in:
lib/asciidoctor-diagram/diagram_source.rb

Overview

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

Instance Method Summary collapse

Instance Method Details

#attr(name, default_value = nil, inherit = diagram_type) ⇒ Object

This method is abstract.

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.

Parameters:

  • name (String, Symbol, Array) —

    the name(s) of the attribute to lookup

  • default_value (Object) (defaults to: nil) —

    the value to return if the attribute is not found

Returns:

  • 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

Raises:

  • (NotImplementedError) 


46
47
48
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 46

def attr(name, default_value = nil, inherit = diagram_type)
  raise NotImplementedError.new
end

#base_dir ⇒ String

This method is abstract.

Returns the base directory against which relative paths in this diagram should be resolved.

Returns:

  • (String) —

    the base directory against which relative paths in this diagram should be resolved



52
53
54
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 52

def base_dir
  attr('docdir', nil, true) || Dir.pwd
end

#code ⇒ String

This method is abstract.

Returns the String representation of the source code for the diagram.

Returns:

  • (String) —

    the String representation of the source code for the diagram



21
22
23
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 21

def code
  @code ||= load_code
end

#config ⇒ Object

Raises:

  • (NotImplementedError) 


80
81
82
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 80

def config
  raise NotImplementedError.new
end

#create_image_metadata ⇒ Hash

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.

Returns:

  • (Hash) —

    a Hash containing metadata



76
77
78
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 76

def create_image_metadata
  {}
end

#diagram_type ⇒ Object

Raises:

  • (NotImplementedError) 


11
12
13
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 11

def diagram_type
  raise NotImplementedError.new
end

#ensure_gem(name, version) ⇒ Object 



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# 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

#find_command(cmd, options = {}) ⇒ Object 



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# 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

#global_attr(name, default_value = nil) ⇒ Object 



29
30
31
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 29

def global_attr(name, default_value = nil)
  attr(name) || attr(name, default_value, 'diagram')
end

#image_name ⇒ Object

Raises:

  • (NotImplementedError) 


15
16
17
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 15

def image_name
  raise NotImplementedError.new
end

#load_code ⇒ Object

Raises:

  • (NotImplementedError) 


25
26
27
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 25

def load_code
  raise NotImplementedError.new
end

#resolve_path(target, start = base_dir) ⇒ Object

Raises:

  • (NotImplementedError) 


157
158
159
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 157

def resolve_path target, start = base_dir
  raise NotImplementedError.new
end

#should_process?(image_file, image_metadata) ⇒ Boolean

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

Parameters:

  • image_file (String) —

    the path to the previously generated version of the image

  • image_metadata (Hash) —

    the image metadata Hash that was stored during the previous diagram generation pass

Returns:

  • (Boolean) —

    true if the diagram should be regenerated; false otherwise



67
68
69
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 67

def should_process?(image_file, image_metadata)
  true
end

#to_s ⇒ Object

Alias for code



57
58
59
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 57

def to_s
  code
end