Object
This class is used by people who use gem plugins (but don’t necessarily make them) to add plugins to their own systems. It provides a way to load plugins, list them, and create them as needed.
It is a singleton so you use like this: GemPlugins::Manager.instance.load
# File lib/gem_plugin.rb, line 69 69: def initialize 70: # plugins that have been loaded 71: @plugins = {} 72: 73: # keeps track of gems which have been loaded already by the manager *and* 74: # where they came from so that they can be referenced later 75: @gems = {} 76: end
While Manager.resource will find arbitrary resources, a special case is when you need to load a set of configuration defaults. GemPlugin normalizes this to be if you have a file “resources/defaults.yaml“ then you’ll be able to load them via Manager.config.
How you use the method is you get the options the user wants set, pass them to Manager.instance.config, and what you get back is a new Hash with the user’s settings overriding the defaults.
opts = Manager.instance.config "mygem", :age => 12, :max_load => .9
In the above case, if defaults had {:age => 14} then it would be changed to 12.
This loads the .yaml file on the fly every time, so doing it a whole lot is very stupid. If you need to make frequent calls to this, call it once with no options (Manager.instance.config) then use the returned defaults directly from then on.
# File lib/gem_plugin.rb, line 229 229: def config(gem_name, options={}) 230: config_file = Manager.instance.resource(gem_name, "/defaults.yaml") 231: if config_file 232: begin 233: defaults = YAML.load_file(config_file) 234: return defaults.merge(options) 235: rescue 236: raise "Error loading config #{config_file} for gem #{gem_name}" 237: end 238: else 239: return options 240: end 241: end
Resolves the given name (should include /category/name) to find the plugin class and create an instance. You can pass a second hash option that is then given to the Plugin to configure it.
# File lib/gem_plugin.rb, line 156 156: def create(name, options = {}) 157: last_slash = name.rindex("/") 158: category = name[0 ... last_slash] 159: plugin = name[last_slash .. 1] 160: 161: map = @plugins[category] 162: if not map 163: raise "Plugin category #{category} does not exist" 164: elsif not map.has_key? plugin 165: raise "Plugin #{plugin} does not exist in category #{category}" 166: else 167: map[plugin].new(options) 168: end 169: end
Responsible for going through the list of available gems and loading any plugins requested. It keeps track of what it’s loaded already and won’t load them again.
It accepts one parameter which is a hash of gem depends that should include or exclude a gem from being loaded. A gem must depend on gem_plugin to be considered, but then each system has to add it’s own INCLUDE to make sure that only plugins related to it are loaded.
An example again comes from Mongrel. In order to load all Mongrel plugins:
GemPlugin::Manager.instance.load "mongrel" => GemPlugin::INCLUDE
Which will load all plugins that depend on mongrel AND gem_plugin. Now, one extra thing we do is we delay loading Rails Mongrel plugins until after rails is configured. Do do this the mongrel_rails script has:
GemPlugin::Manager.instance.load “mongrel” => GemPlugin::INCLUDE, “rails” => GemPlugin::EXCLUDE The only thing to remember is that this is saying “include a plugin if it depends on gem_plugin, mongrel, but NOT rails”. If a plugin also depends on other stuff then it’s loaded just fine. Only gem_plugin, mongrel, and rails are ever used to determine if it should be included.
NOTE: Currently RubyGems will run autorequire on gems that get required AND on their dependencies. This really messes with people running edge rails since activerecord or other stuff gets loaded for just touching a gem plugin. To prevent this load requires the full path to the “init.rb“ file, which avoids the RubyGems autorequire magic.
# File lib/gem_plugin.rb, line 107 107: def load(needs = {}) 108: sdir = File.join(Gem.dir, "specifications") 109: gems = Gem::SourceIndex.from_installed_gems(sdir) 110: needs = needs.merge({"gem_plugin" => INCLUDE}) 111: 112: gems.each do |path, gem| 113: # don't load gems more than once 114: next if @gems.has_key? gem.name 115: check = needs.dup 116: 117: # rolls through the depends and inverts anything it finds 118: gem.dependencies.each do |dep| 119: # this will fail if a gem is depended more than once 120: if check.has_key? dep.name 121: check[dep.name] = !check[dep.name] 122: end 123: end 124: 125: # now since excluded gems start as true, inverting them 126: # makes them false so we'll skip this gem if any excludes are found 127: if (check.select {|name,test| !test}).length == 0 128: # looks like no needs were set to false, so it's good 129: 130: # Previously was set wrong, we already have the correct gem path! 131: #gem_dir = File.join(Gem.dir, "gems", "#{gem.name}-#{gem.version}") 132: gem_dir = File.join(Gem.dir, "gems", path) 133: 134: require File.join(gem_dir, "lib", gem.name, "init.rb") 135: @gems[gem.name] = gem_dir 136: end 137: end 138: 139: return nil 140: end
Simply says whether the given gem has been loaded yet or not.
# File lib/gem_plugin.rb, line 173 173: def loaded?(gem_name) 174: @gems.has_key? gem_name 175: end
Not necessary for you to call directly, but this is how GemPlugin::Base.inherited actually adds a plugin to a category.
# File lib/gem_plugin.rb, line 146 146: def register(category, name, klass) 147: @plugins[category] ||= {} 148: @plugins[category][name.downcase] = klass 149: end
GemPlugins can have a ‘resources’ directory which is packaged with them and can hold any data resources the plugin may need. The main problem is that it’s difficult to figure out where these resources are actually located on the file system. The resource method tries to locate the real path for a given resource path.
Let’s say you have a ‘resources/stylesheets/default.css’ file in your gem distribution, then finding where this file really is involves:
Manager.instance.resource("mygem", "/stylesheets/default.css")
You either get back the full path to the resource or you get a nil if it doesn’t exist.
If you request a path for a GemPlugin that hasn’t been loaded yet then it will throw an PluginNotLoaded exception. The gem may be present on your system in this case, but you just haven’t loaded it with Manager.instance.load properly.
# File lib/gem_plugin.rb, line 196 196: def resource(gem_name, path) 197: if not loaded? gem_name 198: raise PluginNotLoaded.new("Plugin #{gem_name} not loaded when getting resource #{path}") 199: end 200: 201: file = File.join(@gems[gem_name], "resources", path) 202: 203: if File.exist? file 204: return file 205: else 206: return nil 207: end 208: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.