diff options
author | Rick Olson <technoweenie@gmail.com> | 2007-11-08 05:29:44 +0000 |
---|---|---|
committer | Rick Olson <technoweenie@gmail.com> | 2007-11-08 05:29:44 +0000 |
commit | f1b1af88b530c101dc4bf6157bbd1f9c39a670d7 (patch) | |
tree | 76fc9e3e3ed72d6867ab5408decfd8651f5a49e8 /railties/lib/rails | |
parent | c443a6199a9245047f8f4f114b933c785bd3fa55 (diff) | |
download | rails-f1b1af88b530c101dc4bf6157bbd1f9c39a670d7.tar.gz rails-f1b1af88b530c101dc4bf6157bbd1f9c39a670d7.tar.bz2 rails-f1b1af88b530c101dc4bf6157bbd1f9c39a670d7.zip |
Refactor Plugin Loader. Add plugin lib paths early, and add lots of tests. Closes #9795 [lazyatom]
git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8115 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
Diffstat (limited to 'railties/lib/rails')
-rw-r--r-- | railties/lib/rails/plugin.rb | 83 | ||||
-rw-r--r-- | railties/lib/rails/plugin/loader.rb | 230 | ||||
-rw-r--r-- | railties/lib/rails/plugin/locator.rb | 81 |
3 files changed, 250 insertions, 144 deletions
diff --git a/railties/lib/rails/plugin.rb b/railties/lib/rails/plugin.rb new file mode 100644 index 0000000000..2feb90bf14 --- /dev/null +++ b/railties/lib/rails/plugin.rb @@ -0,0 +1,83 @@ +module Rails + + # The Plugin class should be an object which provides the following methods: + # + # * +name+ - used during initialisation to order the plugin (based on name and + # the contents of <tt>config.plugins</tt>) + # * +valid?+ - returns true if this plugin can be loaded + # * +load_paths+ - each path within the returned array will be added to the $LOAD_PATH + # * +load+ - finally 'load' the plugin. + # + # These methods are expected by the Rails::Plugin::Locator and Rails::Plugin::Loader classes. + # The default implementation returns the <tt>lib</tt> directory as its </tt>load_paths</tt>, + # and evaluates <tt>init.rb</tt> when <tt>load</tt> is called. + class Plugin + include Comparable + + attr_reader :directory, :name + + def initialize(directory) + @directory = directory + @name = File.basename(@directory) rescue nil + @loaded = false + end + + def valid? + File.directory?(directory) && (has_lib_directory? || has_init_file?) + end + + # Returns a list of paths this plugin wishes to make available in $LOAD_PATH + def load_paths + report_nonexistant_or_empty_plugin! unless valid? + has_lib_directory? ? [lib_path] : [] + end + + # Evaluates a plugin's init.rb file + def load(initializer) + report_nonexistant_or_empty_plugin! unless valid? + evaluate_init_rb(initializer) + @loaded = true + end + + def loaded? + @loaded + end + + def <=>(other_plugin) + name <=> other_plugin.name + end + + private + + def report_nonexistant_or_empty_plugin! + raise LoadError, "Can not find the plugin named: #{name}" + end + + def lib_path + File.join(directory, 'lib') + end + + def init_path + File.join(directory, 'init.rb') + end + + def has_lib_directory? + File.directory?(lib_path) + end + + def has_init_file? + File.file?(init_path) + end + + def evaluate_init_rb(initializer) + if has_init_file? + silence_warnings do + # Allow plugins to reference the current configuration object + config = initializer.configuration + + eval(IO.read(init_path), binding, init_path) + end + end + end + end +end
\ No newline at end of file diff --git a/railties/lib/rails/plugin/loader.rb b/railties/lib/rails/plugin/loader.rb index 016bcc6c50..dcc62d50b6 100644 --- a/railties/lib/rails/plugin/loader.rb +++ b/railties/lib/rails/plugin/loader.rb @@ -1,146 +1,150 @@ +require "rails/plugin" + module Rails - module Plugin + class Plugin class Loader - include Comparable - attr_reader :initializer, :directory, :name - - class << self - def load(*args) - new(*args).load - end - end - - def initialize(initializer, directory) + attr_reader :initializer + + # Creates a new Plugin::Loader instance, associated with the given + # Rails::Initializer. This default implementation automatically locates + # all plugins, and adds all plugin load paths, when it is created. The plugins + # are then fully loaded (init.rb is evaluated) when load_plugins is called. + # + # It is the loader's responsibilty to ensure that only the plugins specified + # in the configuration are actually loaded, and that the order defined + # is respected. + def initialize(initializer) @initializer = initializer - @directory = directory - @name = File.basename(directory).to_sym end - - def load - return false if loaded? - report_nonexistant_or_empty_plugin! - add_to_load_path! - register_plugin_as_loaded - evaluate - true + + # Returns the plugins to be loaded, in the order they should be loaded. + def plugins + @plugins ||= all_plugins.select { |plugin| should_load?(plugin) }.sort { |p1, p2| order_plugins(p1, p2) } end - - def loaded? - initializer.loaded_plugins.include?(name) + + # Returns all the plugins that could be found by the current locators. + def all_plugins + @all_plugins ||= locate_plugins + @all_plugins end - - def plugin_path? - File.directory?(directory) && (has_lib_directory? || has_init_file?) + + def load_plugins + plugins.each do |plugin| + plugin.load(initializer) + register_plugin_as_loaded(plugin) + end + ensure_all_registered_plugins_are_loaded! end - def enabled? - !explicit_plugin_loading_order? || registered? - end + # Adds the load paths for every plugin into the $LOAD_PATH. Plugin load paths are + # added *after* the application's <tt>lib</tt> directory, to ensure that an application + # can always override code within a plugin. + # + # Plugin load paths are also added to Dependencies.load_paths, and Dependencies.load_once_paths. + def add_plugin_load_paths + plugins.each do |plugin| + plugin.load_paths.each do |path| + $LOAD_PATH.insert(application_lib_index + 1, path) + Dependencies.load_paths << path + Dependencies.load_once_paths << path + end + end + $LOAD_PATH.uniq! + end - def explicitly_enabled? - !explicit_plugin_loading_order? || explicitly_registered? - end + protected - def registered? - explicit_plugin_loading_order? && registered_plugins_names_plugin?(name) - end + # The locate_plugins method uses each class in config.plugin_locators to + # find the set of all plugins available to this Rails application. + def locate_plugins + configuration.plugin_locators.map { |locator| + locator.new(initializer).plugins + }.flatten + # TODO: sorting based on config.plugins + end - def explicitly_registered? - explicit_plugin_loading_order? && registered_plugins.include?(name) - end - - def plugin_does_not_exist!(plugin_name = name) - raise LoadError, "Can not find the plugin named: #{plugin_name}" - end - - private - # The plugins that have been explicitly listed with config.plugins. If this list is nil - # then it means the client does not care which plugins or in what order they are loaded, - # so we load all in alphabetical order. If it is an empty array, we load no plugins, if it is - # non empty, we load the named plugins in the order specified. - def registered_plugins - config.plugins + def register_plugin_as_loaded(plugin) + initializer.loaded_plugins << plugin end - - def registered_plugins_names_plugin?(plugin_name) - registered_plugins.include?(plugin_name) || registered_plugins.include?(:all) + + def configuration + initializer.configuration end - def explicit_plugin_loading_order? - !registered_plugins.nil? + def should_load?(plugin) + # uses Plugin#name and Plugin#valid? + enabled?(plugin) && plugin.valid? end - - def report_nonexistant_or_empty_plugin! - plugin_does_not_exist! unless plugin_path? + + def order_plugins(plugin_a, plugin_b) + if !explicit_plugin_loading_order? + plugin_a <=> plugin_b + else + if !explicitly_enabled?(plugin_a) && !explicitly_enabled?(plugin_b) + plugin_a <=> plugin_b + else + effective_order_of(plugin_a) <=> effective_order_of(plugin_b) + end + end end - def lib_path - File.join(directory, 'lib') + def effective_order_of(plugin) + if explicitly_enabled?(plugin) + registered_plugin_names.index(plugin.name) + else + registered_plugin_names.index('all') + end end - - def init_path - File.join(directory, 'init.rb') + + def application_lib_index + $LOAD_PATH.index(File.join(RAILS_ROOT, 'lib')) || 0 + end + + def enabled?(plugin) + !explicit_plugin_loading_order? || registered?(plugin) end - - def has_lib_directory? - File.directory?(lib_path) + + def explicit_plugin_loading_order? + !registered_plugin_names.nil? end - - def has_init_file? - File.file?(init_path) + + def registered?(plugin) + explicit_plugin_loading_order? && registered_plugins_names_plugin?(plugin) end - - def add_to_load_path! - # Add lib to load path *after* the application lib, to allow - # application libraries to override plugin libraries. - if has_lib_directory? - application_lib_index = $LOAD_PATH.index(application_library_path) || 0 - $LOAD_PATH.insert(application_lib_index + 1, lib_path) - Dependencies.load_paths << lib_path - Dependencies.load_once_paths << lib_path - end + + def explicitly_enabled?(plugin) + !explicit_plugin_loading_order? || explicitly_registered?(plugin) end - - def application_library_path - File.join(RAILS_ROOT, 'lib') + + def explicitly_registered?(plugin) + explicit_plugin_loading_order? && registered_plugin_names.include?(plugin.name) end - - # Allow plugins to reference the current configuration object - def config - initializer.configuration + + def registered_plugins_names_plugin?(plugin) + registered_plugin_names.include?(plugin.name) || registered_plugin_names.include?('all') end - - def register_plugin_as_loaded - initializer.loaded_plugins << name + + # The plugins that have been explicitly listed with config.plugins. If this list is nil + # then it means the client does not care which plugins or in what order they are loaded, + # so we load all in alphabetical order. If it is an empty array, we load no plugins, if it is + # non empty, we load the named plugins in the order specified. + def registered_plugin_names + configuration.plugins ? configuration.plugins.map(&:to_s) : nil end - - # Evaluate in init.rb - def evaluate - silence_warnings { eval(IO.read(init_path), binding, init_path) } if has_init_file? + + def loaded?(plugin_name) + initializer.loaded_plugins.detect { |plugin| plugin.name == plugin_name.to_s } end - - def <=>(other_plugin_loader) + + def ensure_all_registered_plugins_are_loaded! if explicit_plugin_loading_order? - if non_existent_plugin = [self, other_plugin_loader].detect { |plugin| !registered_plugins_names_plugin?(plugin.name) } - plugin_does_not_exist!(non_existent_plugin.name) - end - - if !explicitly_enabled? && !other_plugin_loader.explicitly_enabled? - name.to_s <=> other_plugin_loader.name.to_s - elsif registered_plugins.include?(:all) && (!explicitly_enabled? || !other_plugin_loader.explicitly_enabled?) - effective_index = explicitly_enabled? ? registered_plugins.index(name) : registered_plugins.index(:all) - other_effective_index = other_plugin_loader.explicitly_enabled? ? - registered_plugins.index(other_plugin_loader.name) : registered_plugins.index(:all) - - effective_index <=> other_effective_index - else - registered_plugins.index(name) <=> registered_plugins.index(other_plugin_loader.name) + if configuration.plugins.detect {|plugin| plugin != :all && !loaded?(plugin) } + missing_plugins = configuration.plugins - (plugins + [:all]) + raise LoadError, "Could not locate the following plugins: #{missing_plugins.to_sentence}" end - - else - name.to_s <=> other_plugin_loader.name.to_s end end + end end end
\ No newline at end of file diff --git a/railties/lib/rails/plugin/locator.rb b/railties/lib/rails/plugin/locator.rb index 6c4f2605bb..b27e904b12 100644 --- a/railties/lib/rails/plugin/locator.rb +++ b/railties/lib/rails/plugin/locator.rb @@ -1,15 +1,23 @@ module Rails - module Plugin + class Plugin + + # The Plugin::Locator class should be subclasses to provide custom plugin-finding + # abilities to Rails (i.e. loading plugins from Gems, etc). Each subclass should implement + # the <tt>located_plugins</tt> method, which return an array of Plugin objects that have been found. class Locator include Enumerable + attr_reader :initializer def initialize(initializer) @initializer = initializer end + # This method should return all the plugins which this Plugin::Locator can find + # These will then be used by the current Plugin::Loader, which is responsible for actually + # loading the plugins themselves def plugins - located_plugins.select(&:enabled?).sort + raise "The `plugins' method must be defined by concrete subclasses of #{self.class}" end def each(&block) @@ -19,41 +27,52 @@ module Rails def plugin_names plugins.map(&:name) end - - private - def located_plugins - raise "The `located_plugins' method must be defined by concrete subclasses of #{self.class}" - end end + # The Rails::Plugin::FileSystemLocator will try to locate plugins by examining the directories + # the the paths given in configuration.plugin_paths. Any plugins that can be found are returned + # in a list. + # + # The criteria for a valid plugin in this case is found in Rails::Plugin#valid?, although + # other subclasses of Rails::Plugin::Locator can of course use different conditions. class FileSystemLocator < Locator - private - def located_plugins - initializer.configuration.plugin_paths.flatten.inject([]) do |plugins, path| - plugins.concat locate_plugins_under(path) - plugins - end.flatten - end + + # Returns all the plugins which can be loaded in the filesystem, under the paths given + # by configuration.plugin_paths. + def plugins + initializer.configuration.plugin_paths.flatten.inject([]) do |plugins, path| + plugins.concat locate_plugins_under(path) + plugins + end.flatten + end + + private + + # Attempts to create a plugin from the given path. If the created plugin is valid? + # (see Rails::Plugin#valid?) then the plugin instance is returned; otherwise nil. + def create_plugin(path) + plugin = Rails::Plugin.new(path) + plugin.valid? ? plugin : nil + end - # This starts at the base path looking for directories that pass the plugin_path? test of the Plugin::Loader. - # Since plugins can be nested arbitrarily deep within an unspecified number of intermediary directories, - # this method runs recursively until it finds a plugin directory. - # - # e.g. - # - # locate_plugins_under('vendor/plugins/acts/acts_as_chunky_bacon') - # => 'acts_as_chunky_bacon' - def locate_plugins_under(base_path) - Dir.glob(File.join(base_path, '*')).inject([]) do |plugins, path| - plugin_loader = initializer.configuration.plugin_loader.new(initializer, path) - if plugin_loader.plugin_path? && plugin_loader.enabled? - plugins << plugin_loader - elsif File.directory?(path) - plugins.concat locate_plugins_under(path) - end - plugins + # This starts at the base path looking for valid plugins (see Rails::Plugin#valid?). + # Since plugins can be nested arbitrarily deep within an unspecified number of intermediary + # directories, this method runs recursively until it finds a plugin directory, e.g. + # + # locate_plugins_under('vendor/plugins/acts/acts_as_chunky_bacon') + # => <Rails::Plugin name: 'acts_as_chunky_bacon' ... > + # + def locate_plugins_under(base_path) + Dir.glob(File.join(base_path, '*')).inject([]) do |plugins, path| + if plugin = create_plugin(path) + plugins << plugin + elsif File.directory?(path) + plugins.concat locate_plugins_under(path) end + plugins end + end + end end end
\ No newline at end of file |