ioquatix-engines 2.1.0

data/about.yml

@@ -0,0 +1,7 @@
+author: Samuel Williams
+email: samuel.williams@oriontransfer.co.nz
+homepage: http://wiki.oriontransfer.org/?rails:engines
+summary: Gemified version of engines plugin. Enhances the plugin mechanism to perform more flexible sharing.
+description: The Rails Engines plugin was originally created by James Adam and allows the sharing of almost any type of code or asset that you could use in a Rails application, including controllers, models, stylesheets, and views.
+license: MIT
+version: 2.1.0

data/bin/rails_engines

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+
+require 'fileutils'
+require 'optparse'
+
+class Array
+  # Not optimized at all!
+  def matches_sequence? other
+    return true if other.size == 0
+    
+    i = index(other.first)
+    
+    if i
+      other.each_with_index do |v,p|
+        return false if self[i+p] != v
+      end
+      
+      return i
+    else
+      return false
+    end
+  end
+end
+
+def insert_lines(lines_to_insert, options)
+  lines_to_insert = lines_to_insert.collect { |l| l.chomp + "\n" }
+  
+  target_file = File.join(options[:into])
+  
+  lines = File.readlines(target_file)
+  
+  return if lines.matches_sequence?(lines_to_insert)
+  
+  if options[:after]
+    if options[:after].is_a?(String)
+      after_line = options[:after] + "\n"
+    else
+      after_line = lines.find { |l| l =~ options[:after] }
+      raise "couldn't find a line matching #{options[:after].inspect} in #{target_file}" unless after_line
+    end
+    index = lines.index(after_line)
+    raise "couldn't find line '#{after_line}' in #{target_file}" unless index
+    lines[index+1,0] = lines_to_insert
+  else
+    lines << line
+  end
+  
+  File.open(target_file, 'w') { |f| f.write lines.join }
+end
+
+OPTIONS = {
+  :Setup => false
+}
+
+ARGV.options do |o|
+  script_name = File.basename($0)
+
+  o.set_summary_indent('  ')
+  o.banner = "Usage: #{script_name} [options]"
+  o.define_head "This script is used to set up the engines plugin for rails."
+
+  o.separator ""
+  o.separator "Help and Copyright information"
+
+  o.on("--setup [rails root path]") { |path| OPTIONS[:Setup] = path || "./" }
+
+  o.on_tail("--copy", "Display copyright information") {
+    puts "#{script_name} v#{Engines::VERSION::STRING}. Released under the MIT license."
+    puts "See http://wiki.oriontransfer.org/?rails:engines for more information."
+
+    exit
+  }
+
+  o.on_tail("-h", "--help", "Show this help message.") { puts o; exit }
+
+  o
+end.parse!
+
+if OPTIONS[:Setup]
+  config_path = File.join(OPTIONS[:Setup], "config", "environment.rb")
+  abort "#{config_path} does not exist. Is #{OPTIONS[:Setup]} a rails root directory?" unless File.exist? config_path
+
+  rake_text = <<EOF
+
+require RAILS_ROOT + "/config/environment"
+
+if defined? Engines
+  Engines.load_plugin_tasks
+end
+
+EOF
+
+  rake_path = File.join(OPTIONS[:Setup], "lib", "tasks", "load_plugin_tasks.rake")
+  unless File.exists?(rake_path)
+    File.open(rake_path, "w") { |f| f.write(rake_text) }
+  else
+    puts "#{rake_path} already exists, not overwriting."
+  end
+
+  insert_lines(["gem 'ioquatix-engines', Rails::VERSION::STRING", "require 'engines'"],
+               :into => 'config/environment.rb',
+               :after => "require File.join(File.dirname(__FILE__), 'boot')")
+end

data/generators/plugin_migration/USAGE

@@ -0,0 +1,45 @@
+Description:
+  The plugin migration generator assists in working with schema additions 
+  required by plugins. Instead of running migrations from plugins directly,
+  the generator creates a regular Rails migration which will be responsible
+  for migrating the plugins from their current version to the latest version
+  installed.
+  
+  This is important because the set of application migrations remains an
+  accurate record of the state of the database, even as plugins are installed
+  and removed during the development process.
+
+Example:
+  ./script/generate plugin_migration [<plugin_name> <another_plugin_name> ...]
+
+  This will generate:
+
+    RAILS_ROOT
+      |- db
+          |-migrate
+              |- xxx_plugin_migrations.rb
+
+  which contains the migrations for the given plugin(s).
+  
+  
+Advanced Usage:
+
+There may be situations where you need *complete* control over the migrations
+of plugins in your application, migrating a certainly plugin down to X, and
+another plugin up to Y, where neither X or Y are the latest migrations for those
+plugins.
+
+For those unfortunate few, I have two pieces of advice:
+
+ 1. Why? This is a code smell [http://c2.com/xp/CodeSmell.html].
+ 
+ 2. Well, OK. Don't panic. You can completely control plugin migrations by
+    creating your own migrations. To manually migrate a plugin to a specific
+    version, simply use
+    
+      Engines.plugins[:your_plugin_name].migrate(version)
+      
+    where version is the integer of the migration this plugin should end
+    up at.
+    
+With great power comes great responsibility. Use this wisely.

data/generators/plugin_migration/plugin_migration_generator.rb

@@ -0,0 +1,78 @@
+# Generates a migration which migrates all plugins to their latest versions
+# within the database.
+class PluginMigrationGenerator < Rails::Generator::Base
+  
+  def initialize(runtime_args, runtime_options={})
+    super
+    @options = {:assigns => {}}
+    ensure_schema_table_exists    
+    get_plugins_to_migrate(runtime_args)
+    
+    if @plugins_to_migrate.empty?
+      puts "All plugins are migrated to their latest versions"
+      exit(0)
+    end
+
+    @options[:migration_file_name] = build_migration_name
+    @options[:assigns][:class_name] = build_migration_name.classify
+  end
+  
+  def manifest
+    record do |m|
+      m.migration_template 'plugin_migration.erb', 'db/migrate', @options
+    end
+  end
+  
+  protected
+
+    # Create the schema table if it doesn't already exist.
+    def ensure_schema_table_exists
+      ActiveRecord::Base.connection.initialize_schema_migrations_table
+    end
+
+    # Determine all the plugins which have migrations that aren't present
+    # according to the plugin schema information from the database.
+    def get_plugins_to_migrate(plugin_names)
+
+      # First, grab all the plugins which exist and have migrations
+      @plugins_to_migrate = if plugin_names.empty?
+        Engines.plugins
+      else
+        plugin_names.map do |name| 
+          Engines.plugins[name] ? Engines.plugins[name] : raise("Cannot find the plugin '#{name}'")
+        end
+      end
+      
+      @plugins_to_migrate.reject! { |p| p.latest_migration.nil? }
+      
+      # Then find the current versions from the database    
+      @current_versions = {}
+      @plugins_to_migrate.each do |plugin|
+        @current_versions[plugin.name] = Engines::Plugin::Migrator.current_version(plugin)
+      end
+
+      # Then find the latest versions from their migration directories
+      @new_versions = {}      
+      @plugins_to_migrate.each do |plugin|
+        @new_versions[plugin.name] = plugin.latest_migration
+      end
+      
+      # Remove any plugins that don't need migration
+      @plugins_to_migrate.map { |p| p.name }.each do |name|
+        @plugins_to_migrate.delete(Engines.plugins[name]) if @current_versions[name] == @new_versions[name]
+      end
+      
+      @options[:assigns][:plugins] = @plugins_to_migrate
+      @options[:assigns][:new_versions] = @new_versions
+      @options[:assigns][:current_versions] = @current_versions
+    end
+
+    # Construct a unique migration name based on the plugins involved and the
+    # versions they should reach after this migration is run. The name constructed
+    # needs to be lowercase
+    def build_migration_name
+      @plugins_to_migrate.map do |plugin| 
+        "#{plugin.name}_to_version_#{@new_versions[plugin.name]}" 
+      end.join("_and_").downcase
+    end  
+end

data/generators/plugin_migration/templates/plugin_migration.erb

@@ -0,0 +1,13 @@
+class <%= class_name %> < ActiveRecord::Migration
+  def self.up
+  <%- plugins.each do |plugin| -%>
+    Engines.plugins["<%= plugin.name %>"].migrate(<%= new_versions[plugin.name] %>)
+  <%- end -%>
+  end
+
+  def self.down
+  <%- plugins.each do |plugin| -%>
+    Engines.plugins["<%= plugin.name %>"].migrate(<%= current_versions[plugin.name] %>)
+  <%- end -%>
+  end
+end

data/lib/engines.rb

@@ -0,0 +1,185 @@
+begin
+  require 'rails/version'
+  
+  unless Rails::VERSION::STRING == "2.1.0"
+    raise "This version of the engines plugin requires Rails 2.1.0! Sorry!"
+  end
+end
+
+require 'set'
+require 'active_support'
+require File.join(File.dirname(__FILE__), 'engines/version')
+require File.join(File.dirname(__FILE__), 'engines/plugin')
+require File.join(File.dirname(__FILE__), 'engines/plugin/list')
+require File.join(File.dirname(__FILE__), 'engines/assets')
+require File.join(File.dirname(__FILE__), 'engines/rails_extensions/routing')
+
+# == Parameters
+#
+# The Engines module has a number of public configuration parameters:
+#
+# [+public_directory+]  The directory into which plugin assets should be
+#                       mirrored. Defaults to <tt>RAILS_ROOT/public/plugin_assets</tt>.
+# [+schema_info_table+] The table to use when storing plugin migration 
+#                       version information. Defaults to +plugin_schema_info+.
+#
+# Additionally, there are a few flags which control the behaviour of
+# some of the features the engines plugin adds to Rails:
+#
+# [+disable_application_view_loading+] A boolean flag determining whether
+#                                      or not views should be loaded from 
+#                                      the main <tt>app/views</tt> directory.
+#                                      Defaults to false; probably only 
+#                                      useful when testing your plugin.
+# [+disable_application_code_loading+] A boolean flag determining whether
+#                                      or not to load controllers/helpers 
+#                                      from the main +app+ directory,
+#                                      if corresponding code exists within 
+#                                      a plugin. Defaults to false; again, 
+#                                      probably only useful when testing 
+#                                      your plugin.
+# [+disable_code_mixing+] A boolean flag indicating whether all plugin
+#                         copies of a particular controller/helper should 
+#                         be loaded and allowed to override each other, 
+#                         or if the first matching file should be loaded 
+#                         instead. Defaults to false.
+#
+module Engines
+  # The set of all loaded plugins
+  mattr_accessor :plugins
+  self.plugins = Engines::Plugin::List.new  
+  
+  # List of extensions to load, can be changed in init.rb before calling Engines.init
+  mattr_accessor :rails_extensions
+  self.rails_extensions = %w(action_mailer asset_helpers dependencies)
+  
+  # The name of the public directory to mirror public engine assets into.
+  # Defaults to <tt>RAILS_ROOT/public/plugin_assets</tt>.
+  mattr_accessor :public_directory
+  self.public_directory = File.join(RAILS_ROOT, 'public', 'plugin_assets')
+
+  # The table in which to store plugin schema information. Defaults to
+  # "plugin_schema_info".
+  mattr_accessor :schema_info_table
+  self.schema_info_table = "plugin_schema_info"
+
+  #--
+  # These attributes control the behaviour of the engines extensions
+  #++
+  
+  # Set this to true if views should *only* be loaded from plugins
+  mattr_accessor :disable_application_view_loading
+  self.disable_application_view_loading = false
+  
+  # Set this to true if controller/helper code shouldn't be loaded 
+  # from the application
+  mattr_accessor :disable_application_code_loading
+  self.disable_application_code_loading = false
+  
+  # Set this ti true if code should not be mixed (i.e. it will be loaded
+  # from the first valid path on $LOAD_PATH)
+  mattr_accessor :disable_code_mixing
+  self.disable_code_mixing = false
+  
+  # This is used to determine which files are candidates for the "code
+  # mixing" feature that the engines plugin provides, where classes from
+  # plugins can be loaded, and then code from the application loaded
+  # on top of that code to override certain methods.
+  mattr_accessor :code_mixing_file_types
+  self.code_mixing_file_types = %w(controller helper)
+  
+  class << self
+    def init
+      load_extensions
+      Engines::Assets.initialize_base_public_directory
+    end
+    
+    def load_plugin_tasks
+      # Load any rake tasks that may not have been loaded from external plugins.
+      Engines.plugins.each do |plugin|
+        Dir["#{plugin.tasks_path}/**/*.rake"].sort.each { |ext| load ext }
+      end
+    end
+    
+    def logger
+      RAILS_DEFAULT_LOGGER
+    end
+    
+    def load_extensions
+      rails_extensions.each { |name| require "engines/rails_extensions/#{name}" }
+      # load the testing extensions, if we are in the test environment.
+      require "engines/testing" if RAILS_ENV == "test"
+    end
+    
+    def select_existing_paths(paths)
+      paths.select { |path| File.directory?(path) }
+    end  
+  
+    # The engines plugin will, by default, mix code from controllers and helpers,
+    # allowing application code to override specific methods in the corresponding
+    # controller or helper classes and modules. However, if other file types should
+    # also be mixed like this, they can be added by calling this method. For example,
+    # if you want to include "things" within your plugin and override them from
+    # your applications, you should use the following layout:
+    #
+    #   app/
+    #    +-- things/
+    #    |       +-- one_thing.rb
+    #    |       +-- another_thing.rb
+    #   ...
+    #   vendor/
+    #       +-- plugins/
+    #                +-- my_plugin/
+    #                           +-- app/
+    #                                +-- things/
+    #                                        +-- one_thing.rb
+    #                                        +-- another_thing.rb
+    #
+    # The important point here is that your "things" are named <whatever>_thing.rb,
+    # and that they are placed within plugin/app/things (the pluralized form of 'thing').
+    # 
+    # It's important to note that you'll also want to ensure that the "things" are
+    # on your load path in your plugin's init.rb:
+    #
+    #   Engines.plugins[:my_plugin].code_paths << "app/things"
+    #
+    def mix_code_from(*types)
+      self.code_mixing_file_types += types.map { |x| x.to_s.singularize }
+    end
+    
+    # A general purpose method to mirror a directory (+source+) into a destination
+    # directory, including all files and subdirectories. Files will not be mirrored
+    # if they are identical already (checked via FileUtils#identical?).
+    def mirror_files_from(source, destination)
+      return unless File.directory?(source)
+      
+      # TODO: use Rake::FileList#pathmap?
+      source_files = Dir[source + "/**/*"]
+      source_dirs = source_files.select { |d| File.directory?(d) }
+      source_files -= source_dirs
+      
+      source_dirs.each do |dir|
+        # strip down these paths so we have simple, relative paths we can
+        # add to the destination
+        target_dir = File.join(destination, dir.gsub(source, ''))
+        
+        begin
+          FileUtils.mkdir_p(target_dir)
+        rescue Exception => e
+          raise "Could not create directory #{target_dir}: \n" + e
+        end
+      end
+      
+      source_files.each do |file|
+        begin
+          target = File.join(destination, file.gsub(source, ''))
+          unless File.exist?(target) && FileUtils.identical?(file, target)
+            FileUtils.cp(file, target)
+          end
+        rescue Exception => e
+          raise "Could not copy #{file} to #{target}: \n" + e
+        end
+      end
+    end
+  end
+end

data/lib/engines/assets.rb

@@ -0,0 +1,38 @@
+module Engines
+  module Assets    
+    class << self      
+      @@readme = %{Files in this directory are automatically generated from your plugins.
+They are copied from the 'assets' directories of each plugin into this directory
+each time Rails starts (script/server, script/console... and so on).
+Any edits you make will NOT persist across the next server restart; instead you
+should edit the files within the <plugin_name>/assets/ directory itself.}     
+       
+      # Ensure that the plugin asset subdirectory of RAILS_ROOT/public exists, and
+      # that we've added a little warning message to instruct developers not to mess with
+      # the files inside, since they're automatically generated.
+      def initialize_base_public_directory
+        dir = Engines.public_directory
+        unless File.exist?(dir)
+          Engines.logger.debug "Creating public engine files directory '#{dir}'"
+          FileUtils.mkdir_p(dir)
+        end
+        readme = File.join(dir, "README")        
+        File.open(readme, 'w') { |f| f.puts @@readme } unless File.exist?(readme)
+      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_files_for(plugin)
+        return if plugin.public_directory.nil?
+        begin 
+          Engines.logger.debug "Attempting to copy plugin assets from '#{plugin.public_directory}' to '#{Engines.public_directory}'"
+          Engines.mirror_files_from(plugin.public_directory, File.join(Engines.public_directory, plugin.name))      
+        rescue Exception => e
+          Engines.logger.warn "WARNING: Couldn't create the public file structure for plugin '#{plugin.name}'; Error follows:"
+          Engines.logger.warn e
+        end
+      end
+    end 
+  end
+end