Added a mechanism for plugins to extend compass's configuration options.

doc-src/content/CHANGELOG.markdown

@@ -14,6 +14,12 @@ The Documentation for the [latest stable release](http://compass-style.org/docs/
 
 The Documentation for the [latest preview release](http://beta.compass-style.org/)
 
+0.11.beta.8 (UNRELEASED)
+------------------------
+
+* Created an official API to add configuration options to compass.
+  [More information](/help/tutorials/extending/).
+
 0.11.beta.7 (04/16/2011)
 ------------------------
 * Added support for the new webkit gradient syntax that matches the css3 specification.

doc-src/content/help/tutorials/extending.markdown

@@ -12,7 +12,7 @@ classnames:
 
 The sprite engine is the work horse of sprite generation it's the interface for assembling and writing the image file to disk.
 
-## Requirments
+### Requirements
 
 A sprite engine requires only one method and that is `construct_sprite` which must return an object that responds to `save(filepath)`
 
@@ -25,11 +25,10 @@ Since the Engine module extends base you also have access to all methods in [Com
 To enable your sprite engine from the config file set
     
     sprite_engine = :<engine name>
-    
+
 The example below will load `Compass::SassExtension::Sprites::ChunkyPngEngine`
 
     sprite_engine = :chunky_png
-    
 
 ### Class Definition
 
@@ -47,3 +46,28 @@ The example below will load `Compass::SassExtension::Sprites::ChunkyPngEngine`
         end
       end
     end
+
+<a name="adding-configuration-properties"></a>
+## Adding Configuration Properties to Compass
+
+To add a new configuration property to Compass:
+
+    Compass::Configuration.add_configuration_property(:foobar, "this is a foobar") do
+      if environment == :production
+        "foo"
+      else
+        "bar"
+      end
+    end
+
+This will do several things:
+
+1. make it possible for users to set the `foobar` configuration property in their
+   configuration file.
+2. Ruby code can read and write the `foobar` attribute from any configuration object.
+3. It will add the comment `# this is a foobar` above the property in the configuration file.
+   A comment is not required, you can simply omit this argument if you like.
+4. The block of code provided allows you to assign a sensible default value according to other
+   settings in the configuration or by using arbitrary code to determine what the value should
+   be. For instance it could read from another configuration file or it could change based on
+   the user's operating system.

doc-src/content/help/tutorials/extensions.markdown

@@ -106,6 +106,10 @@ template directories are not at the top level, you can just do this instead:
     base_directory  = File.join(File.dirname(__FILE__), '..', 'compass')
     Compass::Frameworks.register('my_extension', :path => base_directory)
 
+### Adding Configuration Options to Compass
+
+For details on how to add new configuration options to compass [read this](/help/tutorials/extending/#adding-configuration-properties).
+
 Conventions to Follow
 ---------------------
 

lib/compass/configuration.rb

@@ -41,6 +41,40 @@ module Compass
       :sprite_engine
     ].flatten
 
+    # Registers a new configuration property.
+    # Extensions can use this to add new configuration options to compass.
+    #
+    # @param [Symbol] name The name of the property.
+    # @param [String] comment A comment for the property.
+    # @param [Proc] default A method to calculate the default value for the property.
+    #                       The proc is executed in the context of the project's configuration data.
+    def self.add_configuration_property(name, comment = nil, &default)
+      ATTRIBUTES << name
+      if comment.is_a?(String)
+        unless comment[0..0] == "#"
+          comment = "# #{comment}"
+        end
+        unless comment[-1..-1] == "\n"
+          comment = comment + "\n"
+        end
+        Data.class_eval <<-COMMENT
+          def comment_for_#{name}
+            #{comment.inspect}
+          end
+        COMMENT
+      end
+      Data.send(:define_method, :"default_#{name}", &default) if default
+      Data.inherited_accessor(name)
+      if name.to_s =~ /dir|path/
+        strip_trailing_separator(name)
+      end
+    end
+
+    # For testing purposes
+    def self.remove_configuration_property(name)
+      ATTRIBUTES.delete(name)
+    end
+
   end
 end
 

lib/compass/configuration/data.rb

@@ -125,6 +125,7 @@ module Compass
         Compass::Frameworks.register_directory framework_dir
       end
 
+      # Finds all extensions within a directory and registers them.
       def discover(frameworks_dir)
         (self.framework_path ||= []) << frameworks_dir
         Compass::Frameworks.discover frameworks_dir

test/configuration_test.rb

@@ -195,4 +195,44 @@ EXPECTED
     assert_equal "fonts", Compass.configuration.fonts_dir
     assert_equal "extensions", Compass.configuration.extensions_dir
   end
+
+  def test_custom_configuration_properties
+    # Add a configuration property to compass.
+    Compass::Configuration.add_configuration_property(:foobar, "this is a foobar") do
+      if environment == :production
+        "foo"
+      else
+        "bar"
+      end
+    end
+
+    contents = StringIO.new(<<-CONFIG)
+      foobar = "baz"
+    CONFIG
+
+    Compass.add_configuration(contents, "test_strip_trailing_directory_separators")
+
+    assert_equal "baz", Compass.configuration.foobar
+    expected_serialization = <<EXPECTED
+# Require any additional compass plugins here.
+# Set this to the root of your project when deployed:
+http_path = "/"
+# You can select your preferred output style here (can be overridden via the command line):
+# output_style = :expanded or :nested or :compact or :compressed
+# To enable relative paths to assets via compass helper functions. Uncomment:
+# relative_assets = true
+# To disable debugging comments that display the original location of your selectors. Uncomment:
+# line_comments = false
+# this is a foobar
+foobar = "baz"
+EXPECTED
+    assert_equal expected_serialization, Compass.configuration.serialize
+    Compass.reset_configuration!
+    Compass.configuration.environment = :production
+    assert_equal "foo", Compass.configuration.foobar
+    Compass.configuration.environment = :development
+    assert_equal "bar", Compass.configuration.foobar
+  ensure
+    Compass::Configuration.remove_configuration_property :foobar
+  end
 end