Files

Class Index [+]

Quicksearch

CodeRay::PluginHost

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'

Constants

PluginNotFound

Raised if Encoders::[] fails because:

  • a file could not be found

  • the requested Encoder is not registered

HostNotFound
PLUGIN_HOSTS
PLUGIN_HOSTS_BY_ID

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 65
65:     def extended mod
66:       PLUGIN_HOSTS << mod
67:     end
host_by_id(host_id) click to toggle source

Find the PluginHost for host_id.

    # File lib/coderay/helpers/plugin.rb, line 75
75:     def host_by_id host_id
76:       unless PLUGIN_HOSTS_BY_ID.default_proc
77:         ph = Hash.new do |h, a_host_id|
78:           for host in PLUGIN_HOSTS
79:             h[host.host_id] = host
80:           end
81:           h.fetch a_host_id, nil
82:         end
83:         PLUGIN_HOSTS_BY_ID.replace ph
84:       end
85:       PLUGIN_HOSTS_BY_ID[host_id]
86:     end
included(mod) click to toggle source

Warns you that you should not # this module.

    # File lib/coderay/helpers/plugin.rb, line 70
70:     def included mod
71:       warn "#{name} should not be included. Use extend."
72:     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 46
46:   def [] id, *args, &blk
47:     plugin = validate_id(id)
48:     begin
49:       plugin = plugin_hash.[] plugin, *args, &blk
50:     end while plugin.is_a? Symbol
51:     plugin
52:   end
Also aliased as: load
default(id = nil) click to toggle source

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
     # File lib/coderay/helpers/plugin.rb, line 136
136:   def default id = nil
137:     if id
138:       id = validate_id id
139:       plugin_hash[nil] = id
140:     else
141:       plugin_hash[nil]
142:     end
143:   end
host_id() click to toggle source

The host’s ID.

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

     # File lib/coderay/helpers/plugin.rb, line 102
102:   def host_id
103:     if self.const_defined? :PLUGIN_HOST_ID
104:       self::PLUGIN_HOST_ID
105:     else
106:       name
107:     end
108:   end
inspect() click to toggle source

Makes a map of all loaded plugins.

     # File lib/coderay/helpers/plugin.rb, line 176
176:   def inspect
177:     map = plugin_hash.dup
178:     map.each do |id, plugin|
179:       map[id] = plugin.to_s[/(?>\w+)$/]
180:     end
181:     "#{name}[#{host_id}]#{map.inspect}"
182:   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 167
167:   def list
168:     Dir[path_to('*')].select do |file|
169:       File.basename(file)[/^(?!_)\w+\.rb$/]
170:     end.map do |file|
171:       File.basename file, '.rb'
172:     end
173:   end
load(id, *args, &blk) click to toggle source

Alias for +[]+.

Alias for: []
load_all() click to toggle source

Loads all plugins using list and load.

    # File lib/coderay/helpers/plugin.rb, line 36
36:   def load_all
37:     for plugin in list
38:       load plugin
39:     end
40:   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 119
119:   def map hash
120:     for from, to in hash
121:       from = validate_id from
122:       to = validate_id to
123:       plugin_hash[from] = to unless plugin_hash.has_key? from
124:     end
125:   end
plugin_hash() click to toggle source

A Hash of plugion_id => Plugin pairs.

     # File lib/coderay/helpers/plugin.rb, line 160
160:   def plugin_hash
161:     @plugin_hash ||= create_plugin_hash
162:   end
plugin_path(*args) click to toggle source

The path where the plugins can be found.

    # File lib/coderay/helpers/plugin.rb, line 91
91:   def plugin_path *args
92:     unless args.empty?
93:       @plugin_path = File.expand_path File.join(*args)
94:       load_map
95:     end
96:     @plugin_path
97:   end
register(plugin, *ids) click to toggle source

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

See Plugin#register_for.

     # File lib/coderay/helpers/plugin.rb, line 149
149:   def register plugin, *ids
150:     for id in ids
151:       unless id.is_a? Symbol
152:         raise ArgumentError,
153:           "id must be a Symbol, but it was a #{id.class}"
154:       end
155:       plugin_hash[validate_id(id)] = plugin
156:     end
157:   end
require_helper(plugin_id, helper_name) click to toggle source
    # File lib/coderay/helpers/plugin.rb, line 57
57:   def require_helper plugin_id, helper_name
58:     path = path_to File.join(plugin_id, helper_name)
59:     require path
60:   end

Protected Instance Methods

create_plugin_hash() click to toggle source

Created a new plugin list and stores it to @plugin_hash.

     # File lib/coderay/helpers/plugin.rb, line 186
186:   def create_plugin_hash
187:     @plugin_hash =
188:       Hash.new do |h, plugin_id|
189:         id = validate_id(plugin_id)
190:         path = path_to id
191:         begin
192:           require path
193:         rescue LoadError => boom
194:           if h.has_key? nil  # default plugin
195:             h[id] = h[nil]
196:           else
197:             raise PluginNotFound, 'Could not load plugin %p: %s' % [id, boom]
198:           end
199:         else
200:           # Plugin should have registered by now
201:           unless h.has_key? id
202:             raise PluginNotFound,
203:               "No #{self.name} plugin for #{id.inspect} found in #{path}."
204:           end
205:         end
206:         h[id]
207:       end
208:   end
fetch(id, *args, &blk) click to toggle source

Returns the Plugin for id. Use it like Hash#fetch.

Example:

 yaml_plugin = MyPluginHost[:yaml, :default]
     # File lib/coderay/helpers/plugin.rb, line 227
227:   def fetch id, *args, &blk
228:     plugin_hash.fetch validate_id(id), *args, &blk
229:   end
load_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 213
213:   def load_map
214:     mapfile = path_to '_map'
215:     if File.exist? mapfile
216:       require mapfile
217:     elsif $VERBOSE
218:       warn 'no _map.rb found for %s' % name
219:     end
220:   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 232
232:   def path_to plugin_id
233:     File.join plugin_path, "#{plugin_id}.rb"
234:   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 241
241:   def validate_id id
242:     if id.is_a? Symbol or id.nil?
243:       id
244:     elsif id.is_a? String
245:       if id[/\w+/] == id
246:         id.downcase.to_sym
247:       else
248:         raise ArgumentError, "Invalid id: '#{id}' given."
249:       end
250:     else
251:       raise ArgumentError,
252:         "String or Symbol expected, but #{id.class} given."
253:     end
254:   end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.