feat(plugin): introduce simple event-based plugin system

Author: okuramasafumi

lib/rdoc.rb

@@ -208,4 +208,6 @@ def self.home
   autoload :Extend,         "#{__dir__}/rdoc/code_object/extend"
   autoload :Require,        "#{__dir__}/rdoc/code_object/require"
 
+  autoload :BasePlugin,     "#{__dir__}/rdoc/base_plugin"
+  autoload :EventRegistry,  "#{__dir__}/rdoc/event_registry"
 end

lib/rdoc/base_plugin.rb

@@ -0,0 +1,20 @@
+module RDoc
+  class BasePlugin
+    # Register a literner for the given event
+
+    def self.listens_to(event_name, &block)
+      rdoc.event_registry.register(event_name, block)
+    end
+
+    # Activate the plugin with the given RDoc instance
+    # Without calling this, plugins won't work
+
+    def self.activate_with(rdoc = ::RDoc::RDoc.current)
+      @@rdoc = rdoc
+    end
+
+    def self.rdoc
+      @@rdoc
+    end
+  end
+end

lib/rdoc/event_registry.rb

@@ -0,0 +1,26 @@
+module RDoc
+  class EventRegistry
+    EVENT_TYPES = %i[
+      rdoc_start
+      sample
+      rdoc_store_complete
+    ]
+
+    attr_reader :environment
+
+    def initialize
+      @registry = EVENT_TYPES.map { |event_name| [event_name, []] }.to_h
+      @environment = {}
+    end
+
+    def register(event_name, handler)
+      @registry[event_name] << handler
+    end
+
+    def trigger(event_name, *args)
+      @registry[event_name].each do |handler|
+        handler.call(@environment, *args)
+      end
+    end
+  end
+end

lib/rdoc/options.rb

@@ -268,6 +268,11 @@ class RDoc::Options
 
   attr_accessor :pipe
 
+  ##
+  # Currently enabled plugins
+
+  attr_reader :plugins
+
   ##
   # Array of directories to search for files to satisfy an :include:
 
@@ -395,6 +400,7 @@ def init_ivars # :nodoc:
     @coverage_report = false
     @op_dir = nil
     @page_dir = nil
+    @plugins = []
     @pipe = false
     @output_decoration = true
     @rdoc_include = []
@@ -436,6 +442,7 @@ def init_with map # :nodoc:
     @main_page      = map['main_page']
     @markup         = map['markup']
     @op_dir         = map['op_dir']
+    @plugins        = map['plugins']
     @show_hash      = map['show_hash']
     @tab_width      = map['tab_width']
     @template_dir   = map['template_dir']
@@ -503,6 +510,7 @@ def == other # :nodoc:
       @main_page      == other.main_page      and
       @markup         == other.markup         and
       @op_dir         == other.op_dir         and
+      @plugins        == other.plugins        and
       @rdoc_include   == other.rdoc_include   and
       @show_hash      == other.show_hash      and
       @static_path    == other.static_path    and
@@ -868,6 +876,12 @@ def parse argv
 
       opt.separator nil
 
+      opt.on("--plugins=PLUGINS", "-P", Array, "Use plugins") do |value|
+        @plugins.concat value
+      end
+
+      opt.separator nil
+
       opt.on("--tab-width=WIDTH", "-w", Integer,
              "Set the width of tab characters.") do |value|
         raise OptionParser::InvalidArgument,
@@ -1344,6 +1358,16 @@ def visibility= visibility
     end
   end
 
+  # Load plugins specified with options
+  # Currently plugin search logic is very simple, but it's not practical.
+  # TODO: We will improve this later.
+
+  def load_plugins
+    @plugins.each do |plugin_name|
+      require_relative "./#{plugin_name}.rb"
+    end
+  end
+
   ##
   # Displays a warning using Kernel#warn if we're being verbose
 

lib/rdoc/rdoc.rb

@@ -71,6 +71,11 @@ class RDoc::RDoc
 
   attr_accessor :store
 
+  ##
+  # Event registry for RDoc plugins
+
+  attr_accessor :event_registry
+
   ##
   # Add +klass+ that can generate output after parsing
 
@@ -105,6 +110,7 @@ def initialize
     @options       = nil
     @stats         = nil
     @store         = nil
+    @event_registry = ::RDoc::EventRegistry.new
   end
 
   ##
@@ -449,6 +455,9 @@ def document options
     end
     @options.finish
 
+    ::RDoc::BasePlugin.activate_with(self)
+    @options.load_plugins
+
     @store = RDoc::Store.new(@options)
 
     if @options.pipe then
@@ -469,6 +478,7 @@ def document options
     @options.default_title = "RDoc Documentation"
 
     @store.complete @options.visibility
+    @event_registry.trigger :rdoc_store_complete, @store
 
     @stats.coverage_level = @options.coverage_report
 

test/rdoc/test_rdoc_options.rb

@@ -75,6 +75,7 @@ def test_to_yaml
       'markup'                => 'rdoc',
       'output_decoration'     => true,
       'page_dir'              => nil,
+      'plugins'               => [],
       'rdoc_include'          => [],
       'show_hash'             => false,
       'static_path'           => [],