Module: Docscribe::Plugin::Registry

Defined in:
lib/docscribe/plugin/registry.rb

Overview

Global plugin registry.

Plugins are registered once at boot time (e.g. in a file loaded via ‘plugins.require:` in docscribe.yml) and called for every file Docscribe processes.

Thread safety: registration is expected to happen before any parallel rewriting begins.

Defined Under Namespace

Classes: Entry

Class Method Summary collapse

Class Method Details

.clear! ⇒ void

Note:

module_function: when included, also defines #clear! (instance visibility: private)

This method returns an undefined value.

Remove all registered plugins.

Primarily used in tests to reset state between examples.



132
133
134
135
136
 
# File 'lib/docscribe/plugin/registry.rb', line 132

def clear!
  @tag_entries.clear
  @collector_entries.clear
  @order_seq = 0
end

.collector_entries ⇒ Array<Entry>

Note:

module_function: when included, also defines #collector_entries (instance visibility: private)

All registered collector plugin entries (plugin + priority metadata).

Returns:



122
123
124
 
# File 'lib/docscribe/plugin/registry.rb', line 122

def collector_entries
  @collector_entries.dup
end

.collector_plugins ⇒ Array<#collect>

Note:

module_function: when included, also defines #collector_plugins (instance visibility: private)

All registered collector plugins in registration order.

Returns:

  • (Array<#collect>) 


106
107
108
 
# File 'lib/docscribe/plugin/registry.rb', line 106

def collector_plugins
  @collector_entries.map(&:plugin)
end

.create_entry(plugin, priority) ⇒ Entry

Note:

module_function: when included, also defines #create_entry (instance visibility: private)

Create a new Entry with the next order number.

Parameters:

  • plugin (Object)
  • priority (Integer)

Returns:



72
73
74
75
 
# File 'lib/docscribe/plugin/registry.rb', line 72

def create_entry(plugin, priority)
  @order_seq += 1
  Entry.new(plugin: plugin, priority: priority, order: @order_seq)
end

.parse_priority(priority) ⇒ Integer

Note:

module_function: when included, also defines #parse_priority (instance visibility: private)

Parse and validate plugin priority.

Parameters:

  • priority (Object)

Returns:

  • (Integer)

Raises:

  • (ArgumentError)
  • (StandardError) 


60
61
62
63
64
 
# File 'lib/docscribe/plugin/registry.rb', line 60

def parse_priority(priority)
  Integer(priority)
rescue StandardError
  raise ArgumentError, "priority must be an Integer-like value, got: #{priority.inspect}"
end

.register(plugin, priority: 0) ⇒ void

Note:

module_function: when included, also defines #register (instance visibility: private)

This method returns an undefined value.

Register a plugin.

Routes to the appropriate list based on plugin type:

  • subclass of Base::TagPlugin => tag plugin

  • subclass of Base::CollectorPlugin => collector plugin

  • responds to #call => tag plugin (duck typing)

  • responds to #collect => collector plugin (duck typing)

Parameters:

  • plugin (Object) —

    plugin instance

  • priority (Integer) (defaults to: 0) —

    plugin priority (higher wins for conflicts)

Raises:

  • (ArgumentError) —

    if plugin type cannot be determined

  • (StandardError) 


47
48
49
50
51
 
# File 'lib/docscribe/plugin/registry.rb', line 47

def register(plugin, priority: 0)
  prio = parse_priority(priority)
  entry = create_entry(plugin, prio)
  route_entry(entry, plugin)
end

.route_entry(entry, plugin) ⇒ void

Note:

module_function: when included, also defines #route_entry (instance visibility: private)

This method returns an undefined value.

Route entry to tag or collector list.

Parameters:

  • entry (Entry)
  • plugin (Object)

Raises:

  • (ArgumentError) 


84
85
86
87
88
89
90
91
92
 
# File 'lib/docscribe/plugin/registry.rb', line 84

def route_entry(entry, plugin)
  if plugin.is_a?(Base::CollectorPlugin) || plugin.respond_to?(:collect)
    @collector_entries << entry
  elsif plugin.is_a?(Base::TagPlugin) || plugin.respond_to?(:call)
    @tag_entries << entry
  else
    raise ArgumentError, 'Plugin must respond to #call (TagPlugin) or #collect (CollectorPlugin)'
  end
end

.tag_entries ⇒ Array<Entry>

Note:

module_function: when included, also defines #tag_entries (instance visibility: private)

All registered tag plugin entries (plugin + priority metadata).

Returns:



114
115
116
 
# File 'lib/docscribe/plugin/registry.rb', line 114

def tag_entries
  @tag_entries.dup
end

.tag_plugins ⇒ Array<#call>

Note:

module_function: when included, also defines #tag_plugins (instance visibility: private)

All registered tag plugins in registration order.

Returns:

  • (Array<#call>) 


98
99
100
 
# File 'lib/docscribe/plugin/registry.rb', line 98

def tag_plugins
  @tag_entries.map(&:plugin)
end