A command to unpack an extension from the system location.

lib/compass/commands.rb

@@ -6,6 +6,6 @@ require 'compass/commands/registry'
 %w(base generate_grid_background help list_frameworks project_base
    update_project watch_project create_project imports installer_command
    print_version project_stats stamp_pattern validate_project
-   write_configuration interactive).each do |lib|
+   write_configuration interactive unpack_extension).each do |lib|
   require "compass/commands/#{lib}"
 end

lib/compass/commands/project_base.rb

@@ -24,7 +24,7 @@ module Compass
       def configure!
         add_project_configuration
         Compass.add_configuration(options, "command_line")
-        Compass.discover_extensions!
+        Compass.discover_extensions! unless skip_extension_discovery?
       end
 
       def add_project_configuration
@@ -88,6 +88,10 @@ module Compass
         path.index(File::SEPARATOR) == 0
       end
 
+      def skip_extension_discovery?
+        false
+      end
+
     end
   end
 end

lib/compass/commands/unpack_extension.rb

@@ -0,0 +1,117 @@
+require 'compass/commands/project_base'
+require 'fileutils'
+
+module Compass
+  module Commands
+    module ExtensionOptionsParser
+      def set_options(opts)
+        opts.banner = %Q{
+          Usage: compass unpack EXTENSION
+
+          Description:
+            Copy an extension into your extensions folder for easy access to the source code.
+            This makes it easier to peruse the source in unfamiliar projects. It is not recommended
+            that you change other extensions' source -- this makes it hard to take updates from
+            the original author. The following extensions are available:
+            
+          FRAMEWORKS
+            
+          Options:
+        }.strip.split("\n").map{|l| l.gsub(/^ {0,10}/,'')}.join("\n")
+        opts.banner.gsub!(/FRAMEWORKS/,Compass::Frameworks.pretty_print(true))
+        super
+      end
+    end
+
+    class UnpackExtension < ProjectBase
+
+      register :unpack
+
+      def initialize(working_path, options)
+        super
+        assert_project_directory_exists!
+      end
+
+      def perform
+        framework = Compass::Frameworks[options[:framework]]
+        files = Dir["#{framework.path}/**/*"]
+        extension_dir = File.join(Compass.configuration.extensions_path, framework.name)
+        FileUtils.rm_rf extension_dir
+        FileUtils.mkdir_p extension_dir
+        write_file File.join(extension_dir, "DO_NOT_MODIFY"), readme(framework)
+        files.each do |f|
+          next if File.directory?(f)
+          ending = f[(framework.path.size+1)..-1]
+          destination = File.join(extension_dir, ending)
+          FileUtils.mkdir_p(File.dirname(destination))
+          copy f, destination
+        end
+        puts "\nYou have unpacked \"#{framework.name}\""
+        puts
+        puts readme(framework)
+      end
+
+      def readme(framework)
+        %Q{| This is a copy of the "#{framework.name}" extension.
+           |
+           | It now overrides the original which was found here:
+           |
+           | #{framework.path}
+           |
+           | Unpacking an extension is useful when you need to easily peruse the
+           | extension's source. You might find yourself tempted to change the
+           | stylesheets here. If you do this, you'll find it harder to take
+           | updates from the original author. Sometimes this seems like a good
+           | idea at the time, but in a few months, you'll probably regret it.
+           |
+           | In the future, if you take an update of this framework, you'll need to run
+           |
+           |     compass unpack #{framework.name}
+           |
+           | again or remove this unpacked extension.
+           |}.gsub(/^\s*\| ?/,"")
+      end
+
+      def skip_extension_discovery?
+        true
+      end
+
+      class << self
+
+        def option_parser(arguments)
+          parser = Compass::Exec::CommandOptionParser.new(arguments)
+          parser.extend(Compass::Exec::GlobalOptionsParser)
+          parser.extend(Compass::Exec::ProjectOptionsParser)
+          parser.extend(ExtensionOptionsParser)
+        end
+
+        def usage
+          option_parser([]).to_s
+        end
+
+        def description(command)
+          "Copy an extension into your extensions folder."
+        end
+
+        def parse!(arguments)
+          parser = option_parser(arguments)
+          parser.parse!
+          parse_arguments!(parser, arguments)
+          parser.options
+        end
+
+        def parse_arguments!(parser, arguments)
+          if arguments.size == 1
+            parser.options[:framework] = arguments.shift
+          elsif arguments.size == 0
+            raise Compass::Error, "Please specify an extension to unpack."
+          else
+            raise Compass::Error, "Too many arguments were specified."
+          end
+        end
+
+      end
+
+    end
+  end
+end

lib/compass/frameworks.rb

@@ -7,10 +7,11 @@ module Compass
 
     class Framework
       attr_accessor :name
+      attr_accessor :path
       attr_accessor :templates_directory, :stylesheets_directory
       def initialize(name, *arguments)
         options = arguments.last.is_a?(Hash) ? arguments.pop : {}
-        path = options[:path] || arguments.shift
+        self.path = path = options[:path] || arguments.shift
         @name = name
         @templates_directory = options[:templates_directory] || File.join(path, 'templates')
         @stylesheets_directory = options[:stylesheets_directory] || File.join(path, 'stylesheets')
@@ -97,7 +98,7 @@ module Compass
       end
     end
 
-    def pretty_print
+    def pretty_print(skip_patterns = false)
       result = ""
       max = Compass::Frameworks::ALL.inject(0) do |gm, framework|
         fm = framework.template_directories.inject(0) do |lm,pattern|
@@ -108,6 +109,7 @@ module Compass
       Compass::Frameworks::ALL.each do |framework|
         next if framework.name =~ /^_/
         result << "  * #{framework.name}\n"
+        unless skip_patterns
           framework.template_directories.each do |pattern|
             result << "    - #{framework.name}/#{pattern}".ljust(max)
             if description = framework.manifest(pattern).description
@@ -116,6 +118,7 @@ module Compass
             result << "\n"
           end
         end
+      end
       result
     end
   end