module CodeRay::PluginHost

PluginHost

A simple subclass/subfolder plugin system.

Example:

class Generators
  extend 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'
# or
Generators::Fancy

Constants

HostNotFound

PLUGIN_HOSTS

PLUGIN_HOSTS_BY_ID

PluginNotFound

Raised if Encoders::[] fails because:

a file could not be found
the requested Plugin is not registered

Public Class Methods

extended(mod) click to toggle source

Adds the module/class to the PLUGIN_HOSTS list.

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

Public Instance Methods

[](id, *args, &blk) click to toggle source

Returns the Plugin for id.

Example:

yaml_plugin = MyPluginHost[:yaml]

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

Also aliased as: load

all_plugins() click to toggle source

Returns an array of all Plugins.

Note: This loads all plugins using load_all.

# File lib/coderay/helpers/plugin.rb, line 151
def all_plugins
  load_all
  plugin_hash.values.grep(Class)
end

const_missing(const) click to toggle source

Tries to load the missing plugin by translating const to the underscore form (eg. LinesOfCode becomes lines_of_code).

# File lib/coderay/helpers/plugin.rb, line 61
def const_missing const
  id = const.to_s.
    gsub(%r([A-Z]+)([A-Z][a-z])/,'\1_\2').
    gsub(%r([a-z\d])([A-Z])/,'\1_\2').
    downcase
  load id
end

default(id = nil) click to toggle source

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

See also map.

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

MyColorHost.default  # loads and returns the Gray plugin

# File lib/coderay/helpers/plugin.rb, line 114
def default id = nil
  if id
    id = validate_id id
    raise "The default plugin can't be named \"default\"." if id == :default
    plugin_hash[:default] = id
  else
    load :default
  end
end

list() click to toggle source

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

The extension .rb is not included.

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

load(id, *args, &blk) click to toggle source

Alias for: []

load_all() click to toggle source

Loads all plugins using list and load.

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

load_plugin_map() click to toggle source

Loads the map file (see map).

This is done automatically when #plugin_path is called.

# File lib/coderay/helpers/plugin.rb, line 159
def load_plugin_map
  mapfile = path_to '_map'
  @plugin_map_loaded = true
  if File.exist? mapfile
    require mapfile
    true
  else
    false
  end
end

map(hash) click to toggle source

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

# File lib/coderay/helpers/plugin.rb, line 95
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() click to toggle source

A Hash of plugion_id => Plugin pairs.

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

plugin_path(*args) click to toggle source

The path where the plugins can be found.

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

Every plugin must register itself for id by calling register_for, which calls this method.

See CodeRay::Plugin#register_for.

# File lib/coderay/helpers/plugin.rb, line 128
def register plugin, id
  plugin_hash[validate_id(id)] = plugin
end

Protected Instance Methods

make_plugin_hash() click to toggle source

Return a plugin hash that automatically loads plugins.

# File lib/coderay/helpers/plugin.rb, line 173
def make_plugin_hash
  @plugin_map_loaded ||= false
  Hash.new do |h, plugin_id|
    id = validate_id(plugin_id)
    path = path_to id
    begin
      require path
    rescue LoadError => boom
      if @plugin_map_loaded
        if h.has_key?(:default)
          warn '%p could not load plugin %p; falling back to %p' % [self, id, h[:default]]
          h[:default]
        else
          raise PluginNotFound, '%p could not load plugin %p: %s' % [self, id, boom]
        end
      else
        load_plugin_map
        h[plugin_id]
      end
    else
      # Plugin should have registered by now
      if h.has_key? id
        h[id]
      else
        raise PluginNotFound, "No #{self.name} plugin for #{id.inspect} found in #{path}."
      end
    end
  end
end

path_to(plugin_id) click to toggle source

Returns the expected path to the plugin file for the given id.

# File lib/coderay/helpers/plugin.rb, line 204
def path_to plugin_id
  File.join plugin_path, "#{plugin_id}.rb"
end

validate_id(id) click to toggle source

Converts id to a Symbol if it is a String, or returns id if it already is a Symbol.

Raises ArgumentError for all other objects, or if the given String includes non-alphanumeric characters (W).

# File lib/coderay/helpers/plugin.rb, line 213
def validate_id id
  if id.is_a? Symbol or id.nil?
    id
  elsif id.is_a? String
    if id[%r\w+/] == id
      id.downcase.to_sym
    else
      raise ArgumentError, "Invalid id given: #{id}"
    end
  else
    raise ArgumentError, "String or Symbol expected, but #{id.class} given."
  end
end