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) 


54
55
56
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 54

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



60
61
62
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 60

def base_dir
  File.expand_path(attr('docdir', "", true))
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) 


88
89
90
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 88

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



84
85
86
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 84

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 



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 150

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 



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
140
141
142
143
144
145
146
147
148
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 92

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

  end

  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

  cmd_path
end

#global_attr(name, default_value = nil) ⇒ Object 



33
34
35
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 33

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

#global_opt(opt) ⇒ Object 



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

def global_opt(opt)
  global_attr("#{opt}-option")
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

#opt(opt) ⇒ Object 



37
38
39
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 37

def opt(opt)
  attr("#{opt}-option")
end

#resolve_path(target, start = base_dir) ⇒ Object

Raises:

  • (NotImplementedError) 


166
167
168
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 166

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



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

def should_process?(image_file, image_metadata)
  true
end

#to_s ⇒ Object

Alias for code



65
66
67
 
# File 'lib/asciidoctor-diagram/diagram_source.rb', line 65

def to_s
  code
end