parlement 0.10 → 0.11

data/vendor/plugins/engines/lib/engines/plugin.rb

@@ -0,0 +1,214 @@
+# An instance of Plugin is created for each plugin loaded by Rails, and
+# stored in the <tt>Rails.plugins</tt> PluginList 
+# (see Engines::RailsExtensions::RailsInitializer for more details).
+#
+# Once the engines plugin is loaded, other plugins can take advantage of
+# their own instances by accessing either Engines.current, or the preferred mechanism
+#
+#   Rails.plugins[:plugin_name]
+#
+# Useful properties of this object include Plugin#version, which plugin developers
+# can set in their <tt>init.rb</tt> scripts:
+#
+#    Rails.plugins[:my_plugin].version = "1.4.2"
+#
+# Plugin developers can also access the contents of their <tt>about.yml</tt> files
+# via Plugin#about, which returns a Hash if the <tt>about.yml</tt> file exists for
+# this plugin. Note that if <tt>about.yml</tt> contains a "version" key, it will 
+# automatically be loaded into the <tt>version</tt> attribute described above.
+#
+# If this plugin contains paths in directories other than <tt>app/controllers</tt>,
+# <tt>app/helpers</tt>, <tt>app/models</tt> and <tt>components</tt>, authors can
+# declare this by adding extra paths to #code_paths:
+#
+#    Rails.plugin[:my_plugin].code_paths << "app/sweepers" << "vendor/my_lib"
+#
+# Other properties of the Plugin instance can also be set.
+class Plugin
+  
+  # The name of this plugin
+  attr_accessor :name
+
+  # The directory in which this plugin is located
+  attr_accessor :root
+  
+  # The version of this plugin
+  attr_accessor :version
+  
+  # The about.yml information as a Hash, if it exists
+  attr_accessor :about
+  
+  # Plugins can add code paths to this attribute in init.rb if they 
+  # need plugin directories to be added to the load path, i.e.
+  #
+  #   plugin.code_paths << 'app/other_classes'
+  #
+  # Defaults to ["app/controllers", "app/helpers", "app/models", "components"]
+  # (see #default_code_paths). NOTE: if you want to set this, you must
+  # ensure that the engines plugin is loaded before any plugins which
+  # reference this since it's not available before the engines plugin has worked
+  # its magic.
+  attr_accessor :code_paths
+  
+  # Plugins can add paths to this attribute in init.rb if they need
+  # controllers loaded from additional locations. See also #default_controller_paths, and
+  # the caveat surrounding the #code_paths accessor.
+  attr_accessor :controller_paths
+  
+  # The directory in this plugin to mirror into the shared directory
+  # under +public+. See Engines.initialize_base_public_directory
+  # for more information.
+  #
+  # Defaults to "assets" (see default_public_directory).
+  attr_accessor :public_directory
+  
+  protected
+  
+    # The default set of code paths which will be added to $LOAD_PATH
+    # and Dependencies.load_paths
+    def default_code_paths
+      # lib will actually be removed from the load paths when we call
+      # uniq! in #inject_into_load_paths, but it's important to keep it
+      # around (for the documentation tasks, for instance).
+      %w(app/controllers app/helpers app/models components lib)
+    end
+    
+    # The default set of code paths which will be added to the routing system
+    def default_controller_paths
+      %w(app/controllers components)
+    end
+
+    # Attempts to detect the directory to use for public files.
+    # If +assets+ exists in the plugin, this will be used. If +assets+ is missing
+    # but +public+ is found, +public+ will be used.
+    def default_public_directory
+      %w(assets public).select { |dir| File.directory?(File.join(root, dir)) }.first || "assets"
+    end
+
+  public
+  
+  # Creates a new Plugin instance, and loads any other data from <tt>about.yml</tt>
+  def initialize(name, path)
+    @name = name
+    @root = path
+    
+    @code_paths = default_code_paths
+    @controller_paths = default_controller_paths
+    @public_directory = default_public_directory
+    
+    load_about_information
+  end
+  
+  # Load the information from <tt>about.yml</tt>. This Hash is then accessible
+  # from #about.
+  #
+  # If <tt>about.yml</tt> includes a "version", this will be assigned
+  # automatically into #version.
+  def load_about_information
+    about_path = File.join(self.root, 'about.yml')
+    if File.exist?(about_path)
+      @about = YAML.load(File.open(about_path).read)
+      @about.stringify_keys!
+      @version = @about["version"]
+    end
+  end
+  
+  # Load the plugin. Since Rails takes care of evaluating <tt>init.rb</tt> and
+  # adding +lib+ to the <tt>$LOAD_PATH</tt>, we don't need to do that here (see
+  # Engines::RailsExtensions::RailsInitializer.load_plugins_with_engine_additions).
+  # 
+  # Here we add controller/helper code to the appropriate load paths (see 
+  # #inject_into_load_path) and mirror the plugin assets into the shared public
+  # directory (#mirror_public_assets).
+  def load
+    logger.debug "Plugin '#{name}': starting load."
+    
+    inject_into_load_path
+    mirror_public_assets
+    
+    logger.debug "Plugin '#{name}': loaded."
+  end
+  
+  # Adds all directories in the +app+ and +lib+ directories within the engine
+  # to the three relevant load paths mechanism that Rails might use:
+  #
+  # * <tt>$LOAD_PATH</tt>
+  # * <tt>Dependencies.load_paths</tt>
+  # * <tt>ActionController::Routing.controller_paths</tt>
+  #
+  def inject_into_load_path
+
+    load_path_index = $LOAD_PATH.index(Engines.rails_final_load_path)
+    dependency_index = ::Dependencies.load_paths.index(Engines.rails_final_dependency_load_path)
+    
+    # Add relevant paths under the engine root to the load path
+    code_paths.map { |p| File.join(root, p) }.each do |path| 
+      if File.directory?(path)
+        # Add to the load paths
+        $LOAD_PATH.insert(load_path_index + 1, path)
+        # Add to the dependency system, for autoloading.
+        ::Dependencies.load_paths.insert(dependency_index + 1, path)
+      end
+    end
+    
+    # Add controllers to the Routing system specifically. We actually add our paths
+    # to the configuration too, since routing is started AFTER plugins are. Plugins
+    # which are loaded by engines specifically (i.e. because of the '*' in 
+    # +config.plugins+) will need their paths added directly to the routing system, 
+    # since at that point it has already been configured.
+    controller_paths.map { |p| File.join(root, p) }.each do |path|
+      if File.directory?(path)
+        ActionController::Routing.controller_paths << path
+        Rails.configuration.controller_paths << path
+      end
+    end
+
+    $LOAD_PATH.uniq!
+    ::Dependencies.load_paths.uniq!
+    ActionController::Routing.controller_paths.uniq!
+    Rails.configuration.controller_paths.uniq!
+  end
+
+  # Replicates the subdirectories under the plugins's +assets+ (or +public+) directory into
+  # the corresponding public directory. See also Plugin#public_directory for more.
+  def mirror_public_assets
+  
+    begin 
+      source = File.join(root, self.public_directory)
+      # if there is no public directory, just return after this file
+      return if !File.exist?(source)
+
+      logger.debug "Attempting to copy plugin plugin asset files from '#{source}' to '#{Engines.public_directory}'"
+
+      Engines.mirror_files_from(source, File.join(Engines.public_directory, name))
+      
+    rescue Exception => e
+      logger.warn "WARNING: Couldn't create the public file structure for plugin '#{name}'; Error follows:"
+      logger.warn e
+    end
+  end
+
+  # The path to this plugin's public files
+  def public_asset_directory
+    "#{File.basename(Engines.public_directory)}/#{name}"
+  end
+
+  # The directory containing this plugin's migrations (<tt>plugin/db/migrate</tt>)
+  def migration_directory
+    File.join(self.root, 'db', 'migrate')
+  end
+  
+  # Returns the version number of the latest migration for this plugin. Returns
+  # nil if this plugin has no migrations.
+  def latest_migration
+    migrations = Dir[migration_directory+"/*.rb"]
+    return nil if migrations.empty?
+    migrations.map { |p| File.basename(p) }.sort.last.match(/0*(\d+)\_/)[1].to_i
+  end
+  
+  # Migrate this plugin to the given version. See Engines::PluginMigrator for more
+  # information.   
+  def migrate(version = nil)
+    Engines::PluginMigrator.migrate_plugin(self, version)
+  end  
+end

data/vendor/plugins/engines/lib/engines/plugin_list.rb

@@ -0,0 +1,31 @@
+# The PluginList class is an array, enhanced to allow access to loaded plugins
+# by name, and iteration over loaded plugins in order of priority. This array is used
+# by Engines::RailsExtensions::RailsInitializer to create the Rails.plugins array.
+#
+# Each loaded plugin has a corresponding Plugin instance within this array, and 
+# the order the plugins were loaded is reflected in the entries in this array.
+#
+# For more information, see the Rails module.
+class PluginList < Array
+  # Finds plugins with the set with the given name (accepts Strings or Symbols), or
+  # index. So, Rails.plugins[0] returns the first-loaded Plugin, and Rails.plugins[:engines]
+  # returns the Plugin instance for the engines plugin itself.
+  def [](name_or_index)
+    if name_or_index.is_a?(Fixnum)
+      super
+    else
+      self.find { |plugin| plugin.name.to_s == name_or_index.to_s }
+    end
+  end
+  
+  # Go through each plugin, highest priority first (last loaded first). Effectively,
+  # this is like <tt>Rails.plugins.reverse</tt>, except when given a block, when it behaves
+  # like <tt>Rails.plugins.reverse.each</tt>.
+  def by_precedence(&block)
+    if block_given?
+      reverse.each { |x| yield x }
+    else 
+      reverse
+    end
+  end
+end

data/vendor/plugins/engines/lib/engines/plugin_migrator.rb

@@ -0,0 +1,60 @@
+# The PluginMigrator class contains the logic to run migrations from
+# within plugin directories. The directory in which a plugin's migrations
+# should be is determined by the Plugin#migration_directory method.
+#
+# To migrate a plugin, you can simple call the migrate method (Plugin#migrate)
+# with the version number that plugin should be at. The plugin's migrations
+# will then be used to migrate up (or down) to the given version.
+#
+# For more information, see Engines::RailsExtensions::Migrations
+class Engines::PluginMigrator < ActiveRecord::Migrator
+
+  # We need to be able to set the 'current' engine being migrated.
+  cattr_accessor :current_plugin
+
+  # Runs the migrations from a plugin, up (or down) to the version given
+  def self.migrate_plugin(plugin, version)
+    self.current_plugin = plugin
+    migrate(plugin.migration_directory, version)
+  end
+  
+  # Returns the name of the table used to store schema information about
+  # installed plugins.
+  #
+  # See Engines.schema_info_table for more details.
+  def self.schema_info_table_name
+    ActiveRecord::Base.wrapped_table_name Engines.schema_info_table
+  end
+
+  # Returns the current version of the given plugin
+  def self.current_version(plugin=current_plugin)
+    result = ActiveRecord::Base.connection.select_one(<<-ESQL
+      SELECT version FROM #{schema_info_table_name} 
+      WHERE plugin_name = '#{plugin.name}'
+    ESQL
+    )
+    if result
+      result["version"].to_i
+    else
+      # There probably isn't an entry for this engine in the migration info table.
+      # We need to create that entry, and set the version to 0
+      ActiveRecord::Base.connection.execute(<<-ESQL
+        INSERT INTO #{schema_info_table_name} (version, plugin_name) 
+        VALUES (0,'#{plugin.name}')
+      ESQL
+      )      
+      0
+    end
+  end
+
+  # Sets the version of the plugin in Engines::PluginMigrator.current_plugin to
+  # the given version.
+  def set_schema_version(version)
+    ActiveRecord::Base.connection.update(<<-ESQL
+      UPDATE #{self.class.schema_info_table_name} 
+      SET version = #{down? ? version.to_i - 1 : version.to_i} 
+      WHERE plugin_name = '#{self.current_plugin.name}'
+    ESQL
+    )
+  end
+end

data/vendor/plugins/engines/lib/engines/rails_extensions/active_record.rb

@@ -0,0 +1,19 @@
+# Here we add a single helpful method to ActiveRecord::Base. This method may be deprecated
+# in the future, since support for the Module#config mechanism which required it has
+# also been dropped.
+module Engines::RailsExtensions::ActiveRecord
+  # NOTE: Currently the Migrations system will ALWAYS wrap given table names
+  # in the prefix/suffix, so any table name set via ActiveRecord::Base#set_table_name, 
+  # for instance will always get wrapped in the process of migration. For this 
+  # reason, whatever value you give to the config will be wrapped when set_table_name 
+  # is used in the model.
+  #
+  # This method is useful for determining the actual name (including prefix and 
+  # suffix) that Rails will use for a model, given a particular set_table_name
+  # parameter.
+  def wrapped_table_name(name)
+    table_name_prefix + name + table_name_suffix
+  end
+end
+
+::ActiveRecord::Base.extend(Engines::RailsExtensions::ActiveRecord)

data/vendor/plugins/engines/lib/engines/rails_extensions/dependencies.rb

@@ -0,0 +1,143 @@
+# One of the magic features that that engines plugin provides is the ability to
+# override selected methods in controllers and helpers from your application.
+# This is achieved by trapping requests to load those files, and then mixing in
+# code from plugins (in the order the plugins were loaded) before finally loading
+# any versions from the main +app+ directory.
+#
+# The behaviour of this extension is output to the log file for help when
+# debugging.
+#
+# == Example
+#
+# A plugin contains the following controller in <tt>plugin/app/controllers/my_controller.rb</tt>:
+#
+#   class MyController < ApplicationController
+#     def index
+#       @name = "HAL 9000"
+#     end
+#     def list
+#       @robots = Robot.find(:all)
+#     end
+#   end
+#
+# In one application that uses this plugin, we decide that the name used in the
+# index action should be "Robbie", not "HAL 9000". To override this single method,
+# we create the corresponding controller in our application 
+# (<tt>RAILS_ROOT/app/controllers/my_controller.rb</tt>), and redefine the method:
+#
+#   class MyController < ApplicationController
+#     def index
+#       @name = "Robbie"
+#     end
+#   end
+#
+# The list method remains as it was defined in the plugin controller.
+#
+# The same basic principle applies to helpers, and also views and partials (although
+# view overriding is performed in Engines::RailsExtensions::Templates; see that
+# module for more information).
+#
+# === What about models?
+#
+# Unfortunately, it's not possible to provide this kind of magic for models.
+# The only reason why it's possible for controllers and helpers is because
+# they can be recognised by their filenames ("whatever_controller", "jazz_helper"),
+# whereas models appear the same as any other typical Ruby library ("node",
+# "user", "image", etc.). 
+#
+# If mixing were allowed in models, it would mean code mixing for *every* 
+# file that was loaded via +require_or_load+, and this could result in
+# problems where, for example, a Node model might start to include 
+# functionality from another file called "node" somewhere else in the
+# <tt>$LOAD_PATH</tt>.
+#
+# One way to overcome this is to provide model functionality as a module in
+# a plugin, which developers can then include into their own model
+# implementations.
+#
+# Another option is to provide an abstract model (see the ActiveRecord::Base
+# documentation) and have developers subclass this model in their own
+# application if they must.
+#
+# ---
+#
+# The Engines::RailsExtensions::Dependencies module includes a method to
+# override Dependencies.require_or_load, which is called to load code needed
+# by Rails as it encounters constants that aren't defined.
+#
+# This method is enhanced with the code-mixing features described above.
+#
+module Engines::RailsExtensions::Dependencies
+  def self.included(base) #:nodoc:
+    base.class_eval { alias_method_chain :require_or_load, :engine_additions }
+  end
+  
+  # Attempt to load the given file from any plugins, as well as the application.
+  # This performs the 'code mixing' magic, allowing application controllers and
+  # helpers to override single methods from those in plugins.
+  # If the file can be found in any plugins, it will be loaded first from those
+  # locations. Finally, the application version is loaded, using Ruby's behaviour
+  # to replace existing methods with their new definitions.
+  #
+  # If <tt>Engines.disable_code_mixing == true</tt>, the first controller/helper on the
+  # <tt>$LOAD_PATH</tt> will be used (plugins' +app+ directories are always lower on the
+  # <tt>$LOAD_PATH</tt> than the main +app+ directory).
+  #
+  # If <tt>Engines.disable_application_code_loading == true</tt>, controllers will
+  # not be loaded from the main +app+ directory *if* they are present in any
+  # plugins.
+  #
+  # Returns true if the file could be loaded (from anywhere); false otherwise -
+  # mirroring the behaviour of +require_or_load+ from Rails (which mirrors
+  # that of Ruby's own +require+, I believe).
+  def require_or_load_with_engine_additions(file_name, const_path=nil)
+    return require_or_load_without_engine_additions(file_name, const_path) if Engines.disable_code_mixing
+
+    file_loaded = false
+
+    # try and load the plugin code first
+    # can't use model, as there's nothing in the name to indicate that the file is a 'model' file
+    # rather than a library or anything else.
+    ['controller', 'helper'].each do |file_type| 
+      # if we recognise this type
+      # (this regexp splits out the module/filename from any instances of app/#{type}, so that
+      #  modules are still respected.)
+      if file_name =~ /^(.*app\/#{file_type}s\/)?(.*_#{file_type})(\.rb)?$/
+        base_name = $2
+        # ... go through the plugins from first started to last, so that
+        # code with a high precedence (started later) will override lower precedence
+        # implementations
+        Rails.plugins.each do |plugin|
+          plugin_file_name = File.expand_path(File.join(plugin.root, 'app', "#{file_type}s", base_name))
+          logger.debug("checking plugin '#{plugin.name}' for '#{base_name}'")
+          if File.file?("#{plugin_file_name}.rb")
+            logger.debug("==> loading from plugin '#{plugin.name}'")
+            file_loaded = true if require_or_load_without_engine_additions(plugin_file_name, const_path)
+          end
+        end
+        
+        # finally, load any application-specific controller classes using the 'proper'
+        # rails load mechanism, EXCEPT when we're testing engines and could load this file
+        # from an engine
+        if Engines.disable_application_code_loading
+          logger.debug("loading from application disabled.")
+        else
+          # Ensure we are only loading from the /app directory at this point
+          app_file_name = File.join(RAILS_ROOT, 'app', "#{file_type}s", "#{base_name}")
+          if File.file?("#{app_file_name}.rb")
+            logger.debug("loading from application: #{base_name}")
+            file_loaded = true if require_or_load_without_engine_additions(app_file_name, const_path)
+          else
+            logger.debug("(file not found in application)")
+          end
+        end        
+      end 
+    end
+    
+    # if we managed to load a file, return true. If not, default to the original method.
+    # Note that this relies on the RHS of a boolean || not to be evaluated if the LHS is true.
+    file_loaded || require_or_load_without_engine_additions(file_name, const_path)
+  end
+end
+
+::Dependencies.send(:include, Engines::RailsExtensions::Dependencies)

data/vendor/plugins/engines/lib/engines/rails_extensions/migrations.rb

@@ -0,0 +1,155 @@
+# Contains the enhancements to Rails' migrations system to support the 
+# Engines::PluginMigrator. See Engines::RailsExtensions::Migrations for more
+# information.
+
+require "engines/plugin_migrator"
+
+# = Plugins and Migrations: Background
+#
+# Rails uses migrations to describe changes to the databases as your application
+# evolves. Each change to your application - adding and removing models, most
+# commonly - might require tweaks to your schema in the form of new tables, or new
+# columns on existing tables, or possibly the removal of tables or columns. Migrations
+# can even include arbitrary code to *transform* data as the underlying schema
+# changes.
+# 
+# The point is that at any particular stage in your application's development, 
+# migrations serve to transform the database into a state where it is compatible
+# and appropriate at that time.
+# 
+# == What about plugins?
+# 
+# If you want to share models using plugins, chances are that you might also
+# want to include the corresponding migrations to create tables for those models.
+# With the engines plugin installed, plugins can carry migration data easily:
+# 
+#   vendor/
+#     |
+#     plugins/
+#       |
+#       my_plugin/
+#         |- init.rb
+#         |- lib/
+#         |- db/
+#             |-migrate/
+#                 |- 001_do_something.rb
+#                 |- 002_and_something_else.rb
+#                 |- ...
+# 
+# When you install a plugin which contains migrations, you are undertaking a
+# further step in the development of your application, the same as the addition
+# of any other code. With this in mind, you may want to 'roll back' the
+# installation of this plugin at some point, and the database should be able
+# to migrate back to the point without this plugin in it too.
+#
+# == An example
+#
+# For example, our current application is at version 14 (according to the
+# +schema_info+ table), when we decide that we want to add a tagging plugin. The
+# tagging plugin chosen includes migrations to create the tables it requires
+# (say, _tags_ and _taggings_, for instance), along with the models and helpers
+# one might expect.
+#
+# After installing this plugin, these tables should be created in our database.
+# Rather than running the migrations directly from the plugin, they should be
+# integrated into our main migration stream in order to accurately reflect the
+# state of our application's database *at this moment in time*.
+#
+#   $ script/generate plugin_migration
+#         exists  db/migrate
+#         create  db/migrate/015_migrate_tagging_plugin_to_version_3.rb
+#
+# This migration will take our application to version 15, and contains the following, 
+# typical migration code:
+# 
+#   class MigrateTaggingPluginToVersion3 < ActiveRecord::Migration
+#     def self.up
+#       Rails.plugins[:tagging].migrate(3)
+#     end
+#     def self.down
+#       Rails.plugins[:tagging].migrate(0)
+#     end
+#   end
+#
+# When we migrate our application up, using <tt>rake db:migrate</tt> as normal,
+# the plugin will be migrated up to its latest version (3 in this example). If we
+# ever decide to migrate the application back to the state it was in at version 14,
+# the plugin migrations will be taken back down to version 0 (which, typically,
+# would remove all tables the plugin migrations define).
+#
+# == Upgrading plugins
+#
+# It might happen that later in an application's life, we update to a new version of
+# the tagging plugin which requires some changes to our database. The tagging plugin
+# provides these changes in the form of its own migrations. 
+#
+# In this case, we just need to re-run the plugin_migration generator to create a 
+# new migration from the current revision to the newest one:
+#
+#   $ script/generate plugin_migration
+#        exists db/migrate
+#        create db/migrate/023_migrate_tagging_plugin_to_version_5.rb
+#
+# The contents of this migration are:
+#
+#   class MigrateTaggingPluginToVersion3 < ActiveRecord::Migration
+#     def self.up
+#       Rails.plugins[:tagging].migrate(5)
+#     end
+#     def self.down
+#       Rails.plugins[:tagging].migrate(3)
+#     end
+#   end
+#
+# Notice that if we were to migrate down to revision 22 or lower, the tagging plugin
+# will be migrated back down to version 3 - the version we were previously at.
+#
+#
+# = Creating migrations in plugins
+#
+# In order to use the plugin migration functionality that engines provides, a plugin 
+# only needs to provide regular migrations in a <tt>db/migrate</tt> folder within it.
+#
+# = Explicitly migrating plugins
+#
+# It's possible to migrate plugins within your own migrations, or any other code.
+# Simply get the Plugin instance, and its Plugin#migrate method with the version
+# you wish to end up at:
+#
+#   Rails.plugins[:whatever].migrate(version)
+#
+# ---
+#
+# The Engines::RailsExtensions::Migrations module defines extensions for Rails' 
+# migration systems. Specifically:
+#
+# * Adding a hook to initialize_schema_information to create the plugin schema
+#   info table.
+#
+module Engines::RailsExtensions::Migrations
+  def self.included(base) # :nodoc:
+    base.class_eval { alias_method_chain :initialize_schema_information, :engine_additions }
+  end
+
+  # Create the schema tables, and ensure that the plugin schema table
+  # is also initialized. The plugin schema info table is defined by
+  # Engines::PluginMigrator.schema_info_table_name.
+  def initialize_schema_information_with_engine_additions
+    initialize_schema_information_without_engine_additions
+    
+    # create the plugin schema stuff.    
+    begin
+      execute <<-ESQL
+        CREATE TABLE #{Engines::PluginMigrator.schema_info_table_name} 
+          (plugin_name #{type_to_sql(:string)}, version #{type_to_sql(:integer)})
+      ESQL
+    rescue ActiveRecord::StatementInvalid
+      # Schema has been initialized
+    end
+  end
+end
+
+::ActiveRecord::ConnectionAdapters::SchemaStatements.send(:include, Engines::RailsExtensions::Migrations)
+
+# Set ActiveRecord to ignore the plugin schema table by default
+::ActiveRecord::SchemaDumper.ignore_tables << Engines.schema_info_table