PluginHost

A simple subclass plugin system.

 Example:
   class Generators < PluginHost
     plugin_path 'app/generators'
   end

   class Generator
     extend Plugin
     PLUGIN_HOST = Generators
   end

   class FancyGenerator < Generator
     register_for :fancy
   end

   Generators[:fancy]  #-> FancyGenerator
   # or
   CodeRay.require_plugin 'Generators/fancy'

Methods

[]
default
extended
host_by_id
host_id
included
inspect
list
load
load_all
map
plugin_hash
plugin_path
register
require_helper

Constants

PluginNotFound	=	Class.new Exception
	Raised if Encoders::[] fails because: a file could not be found the requested Encoder is not registered
HostNotFound	=	Class.new Exception
PLUGIN_HOSTS	=	[]
PLUGIN_HOSTS_BY_ID	=	{}

Public Class methods

extended(mod)

Adds the module/class to the PLUGIN_HOSTS list.

→ show source

# File lib/coderay/helpers/plugin.rb, line 65
    def extended mod
      PLUGIN_HOSTS << mod
    end

host_by_id(host_id)

Find the PluginHost for host_id.

→ show source

# File lib/coderay/helpers/plugin.rb, line 75
    def host_by_id host_id
      unless PLUGIN_HOSTS_BY_ID.default_proc
        ph = Hash.new do |h, a_host_id|
          for host in PLUGIN_HOSTS
            h[host.host_id] = host
          end
          h.fetch a_host_id, nil
        end
        PLUGIN_HOSTS_BY_ID.replace ph
      end
      PLUGIN_HOSTS_BY_ID[host_id]
    end

included(mod)

Warns you that you should not include this module.

→ show source

# File lib/coderay/helpers/plugin.rb, line 70
    def included mod
      warn "#{name} should not be included. Use extend."
    end

Public Instance methods

[](id, *args, &blk)

Returns the Plugin for id.

Example:

 yaml_plugin = MyPluginHost[:yaml]

--- This method is also aliased as load ---

→ show source

# File lib/coderay/helpers/plugin.rb, line 46
  def [] id, *args, &blk
    plugin = validate_id(id)
    begin
      plugin = plugin_hash.[] plugin, *args, &blk
    end while plugin.is_a? Symbol
    plugin
  end

default(id = nil)

Define the default plugin to use when no plugin is found for a given id.

See also map.

 class MyColorHost < PluginHost
   map :navy => :dark_blue
   default :gray
 end

→ show source

# File lib/coderay/helpers/plugin.rb, line 136
  def default id = nil
    if id
      id = validate_id id
      plugin_hash[nil] = id
    else
      plugin_hash[nil]
    end
  end

host_id()

The host’s ID.

If PLUGIN_HOST_ID is not set, it is simply the class name.

→ show source

# File lib/coderay/helpers/plugin.rb, line 102
  def host_id
    if self.const_defined? :PLUGIN_HOST_ID
      self::PLUGIN_HOST_ID
    else
      name
    end
  end

inspect()

Makes a map of all loaded plugins.

→ show source

# File lib/coderay/helpers/plugin.rb, line 176
  def inspect
    map = plugin_hash.dup
    map.each do |id, plugin|
      map[id] = plugin.to_s[/(?>\w+)$/]
    end
    "#{name}[#{host_id}]#{map.inspect}"
  end

list()

Returns an array of all .rb files in the plugin path.

The extension .rb is not included.

→ show source

# File lib/coderay/helpers/plugin.rb, line 167
  def list
    Dir[path_to('*')].select do |file|
      File.basename(file)[/^(?!_)\w+\.rb$/]
    end.map do |file|
      File.basename file, '.rb'
    end
  end

load(id, *args, &blk)

Alias for #[]

load_all()

Loads all plugins using list and load.

→ show source

# File lib/coderay/helpers/plugin.rb, line 36
  def load_all
    for plugin in list
      load plugin
    end
  end

map(hash)

Map a plugin_id to another.

Usage: Put this in a file plugin_path/_map.rb.

 class MyColorHost < PluginHost
   map :navy => :dark_blue,
     :maroon => :brown,
     :luna => :moon
 end

→ show source

# File lib/coderay/helpers/plugin.rb, line 119
  def map hash
    for from, to in hash
      from = validate_id from
      to = validate_id to
      plugin_hash[from] = to unless plugin_hash.has_key? from
    end
  end

plugin_hash()

A Hash of plugion_id => Plugin pairs.

→ show source

# File lib/coderay/helpers/plugin.rb, line 160
  def plugin_hash
    @plugin_hash ||= create_plugin_hash
  end

plugin_path(*args)

The path where the plugins can be found.

→ show source

# File lib/coderay/helpers/plugin.rb, line 91
  def plugin_path *args
    unless args.empty?
      @plugin_path = File.expand_path File.join(*args)
      load_map
    end
    @plugin_path
  end

register(plugin, *ids)

Every plugin must register itself for one or more ids by calling register_for, which calls this method.

See Plugin#register_for.

→ show source

# File lib/coderay/helpers/plugin.rb, line 149
  def register plugin, *ids
    for id in ids
      unless id.is_a? Symbol
        raise ArgumentError,
          "id must be a Symbol, but it was a #{id.class}"
      end
      plugin_hash[validate_id(id)] = plugin
    end
  end

require_helper(plugin_id, helper_name)

→ show source

# File lib/coderay/helpers/plugin.rb, line 57
  def require_helper plugin_id, helper_name
    path = path_to File.join(plugin_id, helper_name)
    require path
  end