Module: CodeRay::PluginHost

Included in:
Encoders, Scanners, Styles
Defined in:
lib/coderay/helpers/plugin.rb

Overview

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'

Constant Summary collapse

PluginNotFound =

Raised if Encoders::[] fails because:

  • a file could not be found

  • the requested Encoder is not registered

Class.new Exception
HostNotFound = 
Class.new Exception
PLUGIN_HOSTS = 
[]
PLUGIN_HOSTS_BY_ID =

dummy hash

{}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(mod) ⇒ Object

Adds the module/class to the PLUGIN_HOSTS list.



65
66
67
 
# File 'lib/coderay/helpers/plugin.rb', line 65

def extended mod
  PLUGIN_HOSTS << mod
end

.host_by_id(host_id) ⇒ Object

Find the PluginHost for host_id.



75
76
77
78
79
80
81
82
83
84
85
86
 
# 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) ⇒ Object

Warns you that you should not #include this module.



70
71
72
 
# File 'lib/coderay/helpers/plugin.rb', line 70

def included mod
  warn "#{name} should not be included. Use extend."
end

Instance Method Details

#[](id, *args, &blk) ⇒ Object Also known as: load

Returns the Plugin for id.

Example:

yaml_plugin = MyPluginHost[:yaml]



46
47
48
49
50
51
52
 
# 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) ⇒ Object

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



136
137
138
139
140
141
142
143
 
# 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 ⇒ Object

The host’s ID.

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



102
103
104
105
106
107
108
 
# 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 ⇒ Object

Makes a map of all loaded plugins.



176
177
178
179
180
181
182
 
# 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 ⇒ Object

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

The extension .rb is not included.



167
168
169
170
171
172
173
 
# 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_all ⇒ Object

Loads all plugins using list and load.



36
37
38
39
40
 
# File 'lib/coderay/helpers/plugin.rb', line 36

def load_all
  for plugin in list
    load plugin
  end
end

#map(hash) ⇒ Object

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



119
120
121
122
123
124
125
 
# 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 ⇒ Object

A Hash of plugion_id => Plugin pairs.



160
161
162
 
# File 'lib/coderay/helpers/plugin.rb', line 160

def plugin_hash
  @plugin_hash ||= create_plugin_hash
end

#plugin_path(*args) ⇒ Object

The path where the plugins can be found.



91
92
93
94
95
96
97
 
# 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) ⇒ Object

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

See Plugin#register_for.



149
150
151
152
153
154
155
156
157
 
# 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) ⇒ Object 



57
58
59
60
 
# 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