Module: Doing::Plugins

Defined in:
lib/doing/plugin_manager.rb

Overview

Plugin handling

Class Method Summary collapse

Class Method Details

.available_plugins(type: :export) ⇒ Array

Return array of available plugin names

Parameters:

  • type (Symbol) (defaults to: :export) —

    Plugin type (:import, :export)

Returns:

  • (Array) —

    Array of plugin names (String)



171
172
173
174
 
# File 'lib/doing/plugin_manager.rb', line 171

def available_plugins(type: :export)
  type = valid_type(type)
  plugins[type].keys.sort
end

.list_plugins(options = {}) ⇒ Object

List available plugins to stdout

Parameters:

  • options (Hash) (defaults to: {}) —

    additional options

Options Hash (options):

  • :column (Boolean) —

    display results in a single column

  • :type (String) —

    Plugin type: all, import, or export



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/doing/plugin_manager.rb', line 147

def list_plugins(options = {})
  separator = options[:column] ? "\n" : "\t"
  type = options[:type].nil? || options[:type] =~ /all/i ? 'all' : valid_type(options[:type])

  case type
  when :import
    puts plugin_names(type: :import, separator: separator)
  when :export
    puts plugin_names(type: :export, separator: separator)
  else
    print 'Import plugins: '
    puts plugin_names(type: :import, separator: ', ')
    print 'Export plugins: '
    puts plugin_names(type: :export, separator: ', ')
  end
end

.load_plugins(add_dir = nil) ⇒ Object

Load plugins from plugins folder



28
29
30
31
32
33
34
35
36
 
# File 'lib/doing/plugin_manager.rb', line 28

def load_plugins(add_dir = nil)
  plugins_path(add_dir).each do |plugin_search_path|
    Dir.glob(File.join(plugin_search_path, '**', '*.rb')).sort.each do |plugin|
      require plugin
    end
  end

  plugins
end

.plugin_names(type: :export, separator: '|') ⇒ String

Return string version of plugin names

Parameters:

  • type (defaults to: :export) —

    Plugin type (:import, :export)

  • separator (defaults to: '|') —

    The separator to join names with

Returns:

  • (String) —

    Plugin names joined with separator



184
185
186
187
 
# File 'lib/doing/plugin_manager.rb', line 184

def plugin_names(type: :export, separator: '|')
  type = valid_type(type)
  available_plugins(type: type).join(separator)
end

.plugin_regex(type: :export) ⇒ Regexp

Return a regular expression of all plugin triggers for type

Parameters:

  • type (Symbol) (defaults to: :export) —

    The type :import or :export

Returns:

  • (Regexp) —

    regular expression



198
199
200
201
202
203
204
205
 
# File 'lib/doing/plugin_manager.rb', line 198

def plugin_regex(type: :export)
  type = valid_type(type)
  pattern = []
  plugins[type].each do |_, options|
    pattern << options[:trigger].normalize_trigger
  end
  Regexp.new("^(?:#{pattern.sort.uniq.join('|')})$", true)
end

.plugin_templates(type: :export) ⇒ Array

Return array of available template names

Parameters:

  • type (Symbol) (defaults to: :export) —

    Plugin type (:import, :export)

Returns:

  • (Array) —

    Array of template names (String)



215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/doing/plugin_manager.rb', line 215

def plugin_templates(type: :export)
  type = valid_type(type)
  templates = []
  plugs = plugins[type].clone
  plugs.delete_if { |_t, o| o[:templates].nil? }.each do |_, options|
    options[:templates].each do |t|
      out = t[:name]
      out += " (#{t[:format]})" if t.key?(:format)
      templates << out
    end
  end

  templates.sort.uniq
end

.plugins ⇒ Hash

Storage for registered plugins. Hash with :import and :export keys containing hashes of available plugins.

Returns:

  • (Hash) —

    registered plugins



18
19
20
21
22
23
 
# File 'lib/doing/plugin_manager.rb', line 18

def plugins
  @plugins ||= {
    import: {},
    export: {}
  }
end

.plugins_path(add_dir = nil) ⇒ Array

Setup the plugin search path

Parameters:

  • add_dir (String) (defaults to: nil) —

    optional additional path to include

Returns:

  • (Array) —

    Returns an Array of plugin search paths



45
46
47
48
49
 
# File 'lib/doing/plugin_manager.rb', line 45

def plugins_path(add_dir = nil)
  paths = Array(File.join(File.dirname(__FILE__), 'plugins'))
  paths << File.join(add_dir) if add_dir
  paths.map { |d| File.expand_path(d) }
end

.register(title, type, klass) ⇒ Boolean

Register a plugin

Parameters:

  • title (String|Array) —

    The name of the plugin (can be an array of names)

  • type (Symbol) —

    The plugin type (:import, :export)

  • klass (Class) —

    The class responding to :render or :import

Returns:

  • (Boolean) —

    Success boolean



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/doing/plugin_manager.rb', line 63

def register(title, type, klass)
  type = validate_plugin(title, type, klass)
  return unless type

  if title.is_a?(Array)
    title.each { |t| register(t, type, klass) }
    return
  end

  settings = if klass.respond_to? :settings
               klass.settings
             else
               { trigger: title.normalize_trigger, config: {} }
             end

  plugins[type] ||= {}
  plugins[type][title] = {
    trigger: settings[:trigger].normalize_trigger || title.normalize_trigger,
    class: klass,
    templates: settings[:templates] || nil,
    config: settings[:config] || {}
  }

  return unless ENV['DOING_PLUGIN_DEBUG']

  Doing.logger.debug('Plugin Manager:', "Registered #{type} plugin \"#{title}\"")
end

.template_for_trigger(trigger, type: :export, save_to: nil) ⇒ String

Find and return the appropriate template for a trigger string. Outputs a string that can be written out to the terminal for redirection

Parameters:

  • trigger (String) —

    The trigger to test

  • type (Symbol) (defaults to: :export) —

    the plugin type (:import, :export)

  • save_to (String) (defaults to: nil) —

    if a path is specified, write the template to that path. Nil for STDOUT

Returns:

  • (String) —

    string content of template for trigger

Raises:



265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/doing/plugin_manager.rb', line 265

def template_for_trigger(trigger, type: :export, save_to: nil)
  plugins[valid_type(type)].clone.delete_if { |_t, o| o[:templates].nil? }.each do |_, options|
    options[:templates].each do |t|
      next unless trigger =~ /^(?:#{t[:trigger].normalize_trigger})$/

      tpl = options[:class].template(trigger)
      return tpl unless save_to

      raise PluginException.new('No default filename defined', :export, t[:name]) unless t.key?(:filename)

      return save_template(tpl, save_to, t[:filename])
    end
  end
  raise Errors::InvalidArgument, "No template type matched \"#{trigger}\""
end

.template_regex(type: :export) ⇒ Regexp

Return a regular expression of all template triggers for type

Parameters:

  • type (Symbol) (defaults to: :export) —

    The type :import or :export

Returns:

  • (Regexp) —

    regular expression



239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/doing/plugin_manager.rb', line 239

def template_regex(type: :export)
  type = valid_type(type)
  pattern = []
  plugs = plugins[type].clone
  plugs.delete_if { |_, o| o[:templates].nil? }.each do |_, options|
    options[:templates].each do |t|
      pattern << t[:trigger].normalize_trigger
    end
  end
  Regexp.new("^(?:#{pattern.join('|')})$", true)
end

.user_home ⇒ Object

Return the user's home directory



8
9
10
 
# File 'lib/doing/plugin_manager.rb', line 8

def user_home
  @user_home ||= Util.user_home
end

.valid_type(type, default: nil) ⇒ Symbol

Converts a partial symbol to a valid plugin type, e.g. :imp => :import

Parameters:

  • type (Symbol) —

    the symbol to test

  • default (Symbol) (defaults to: nil) —

    fallback value

Returns:

  • (Symbol) —

    :import or :export



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/doing/plugin_manager.rb', line 124

def valid_type(type, default: nil)
  type ||= default

  t = type.to_s
  type = case t
         when /^i(m(p(o(r(t)?)?)?)?)?$/
           :import
         when /^e(x(p(o(r(t)?)?)?)?)?$/
           :export
         else
           raise Errors::InvalidPluginType.new('Invalid plugin type', 'unrecognized')
         end

  type.to_sym
end

.validate_plugin(title, type, klass) ⇒ Object

Verifies that a plugin is properly configured with necessary methods for its type. If the plugin fails validation, a PluginUncallable exception will be raised.

Parameters:

  • title (String) —

    The title

  • type (Symbol) —

    type, :import or :export

  • klass (Class) —

    Plugin class



102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/doing/plugin_manager.rb', line 102

def validate_plugin(title, type, klass)
  type = valid_type(type)
  if type == :import && !klass.respond_to?(:import)
    raise Errors::PluginUncallable.new('Import plugins must respond to :import', type, title)
  end

  if type == :export && !klass.respond_to?(:render)
    raise Errors::PluginUncallable.new('Export plugins must respond to :render', type, title)
  end

  type
end