configuration_dsl 0.2.0

data/.document

@@ -0,0 +1,6 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt
+README.rdoc

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,18 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  rcov

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Christopher J Bottaro
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,150 @@
+= configuration_dsl
+
+Easily configure classes and objects using a DSL.
+
+== Description
+
+configuration_dsl encapsulates the pattern of using a DSL to "configure" objects and/or classes:
+
+  class MyAwesomeClass
+    ... some setup code here ...
+    configure do
+      greeting "Hello!"
+      count 5
+    end
+  end
+
+  MyAwesomeClass.configuration.greeting
+  # => "Hello!"
+
+  MyAwesomeClass.configuration.count
+  # => 5
+
+== Usage
+
+Bet you're wondering what goes in that "some setup code here" placeholder.  It's nothing too complicated.  Here's a complete example.
+
+  module Configuration
+    DEFAULTS = {
+      :greeting => "Hi.",
+      :count => 1
+    }
+  end
+
+  require "configuration_dsl"
+  
+  class MyAwesomeClass
+    extend ConfigurationDsl
+    configure_with(Configuration)
+    configure do
+      greeting "Hello!"
+    end
+  end
+
+  MyAwesomeClass.configuration.greeting
+  # => "Hello!"
+
+  MyAwesomeClass.configuration.count
+  # => 1
+
+The basic idea is that you define a module with your configuration options.  The module must contain a constant called DEFAULTS that has the configuration option names and their default values.  You can then optionally define setter methods for each configuration option (more on that later), or just use the ones that are automatically created for you.
+
+== Why a module?
+
+Why are the configuration options stored in a module?  It makes for pretty documentation.  Instead of using the automatically generated setters, you can write (and document!) your own.
+
+  module Configuration
+    DEFAULTS = {
+      :greeting => "Hi.",
+      :count => 1
+    }
+  
+    # Set the phrase used to greet someone.
+    def greeting(phrase)
+      configuration.greeting = value
+    end
+  
+    # How many times to greet someone. +n+ must be greater than zero.
+    def count(n)
+      raise ArgumentError, "count must be greater than zero" if n <= 0
+      configuration.count = n
+    end
+  end
+
+Just run rdoc on that module and you have all your configuration options documented in one easy to link to place.
+
+== Working with objects
+
+configuration_dsl works with plain objects (in addition to classes).  Given the module Configuration from our previous examples:
+
+  foo = Foo.new
+  foo.extend(ConfigurationDsl)
+  foo.configure_with(Configuration)
+  foo.configure do
+    greeting "What up?"
+    count 2
+  end
+  foo.configuration.greeting
+  # => "What up?"
+  foo.configuration.count
+  # => 2
+
+== Working with classes
+
+If you use configuration_dsl with classes, then derived classes should inherit the configuration in a sane and predictable way.
+
+== Complex setters
+
+You can have a single setter for multiple configuration options.
+
+  module Configuration
+    DEFAULTS = {
+      :frequence => 0,
+      :callback => nil
+    }
+  
+    def set_callback(f, &block)
+      configuration.frequence = f
+      configuration.callback = block
+    end
+  end
+
+== Callback
+
+You can set a callback to be called after each time +configure+ is called.  Just pass a block to +configure_with+.
+
+  class MyClass
+    extend ConfigurationDsl
+    configure_with(SomeConfigurationModule) do
+      @configure_count ||= 0
+      @configure_count += 1
+    end
+  
+    configure do
+      some_option "something"
+    end
+  end
+
+  MyClass.configure do
+    another_option "something else"
+  end
+
+  MyClass.instance_variable_get(:@configure_count)
+  # => 2
+
+This is useful if you need to run some kind of initialization code after your class or object has been configured.
+
+== Contributing to configuration_dsl
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Christopher J Bottaro. See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "configuration_dsl"
+  gem.homepage = "http://github.com/cjbottaro/configuration_dsl"
+  gem.license = "MIT"
+  gem.summary = %Q{Configure classes and objects using a DSL.}
+  gem.description = %Q{Easily configure a class (or object) with a DSL.}
+  gem.email = "cjbottaro@alumni.cs.utexas.edu"
+  gem.authors = ["Christopher J Bottaro"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "configuration_dsl #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/configuration_dsl.rb

@@ -0,0 +1,52 @@
+require "configuration_dsl/dsl"
+require "configuration_dsl/impl"
+
+module ConfigurationDsl
+  
+  class Error < RuntimeError; end
+  
+  VERSION = File.read(File.dirname(__FILE__)+"/../VERSION")
+  
+  def configure_with(configuration_module, &block)
+    @configuration_dsl ||= Impl.new(self)
+    @configuration_dsl.module = configuration_module
+    @configuration_dsl.callback = block if block_given?
+    @configuration_dsl.default_configuration!
+    
+    # Automatically define setters.
+    @configuration_dsl.module.module_eval do
+      self::DEFAULTS.keys.each do |name|
+        next if method_defined?(name) # Don't override custom setters.
+        module_eval <<-code
+          def #{name}(value)
+            configuration.#{name} = value
+          end
+        code
+      end
+    end
+  end
+  
+  def configure(&block)
+    @configuration_dsl ||= Impl.new(self)
+    
+    # Instance eval the block.
+    if block_given?
+      _module = @configuration_dsl.find_module
+      raise Error, "cannot find configuration module" unless _module
+      dsl = Dsl.new(Impl.dup_struct(configuration)) # Dup it to unfreeze it.
+      dsl.send(:extend, _module)
+      dsl.instance_eval(&block)
+      @configuration_dsl.configuration = dsl.configuration.freeze
+    end
+    
+    # Run the callback.
+    callback = @configuration_dsl.find_callback
+    instance_eval(&callback) if callback
+  end
+  
+  def configuration
+    @configuration_dsl ||= Impl.new(self)
+    @configuration_dsl.find_configuration
+  end
+  
+end

data/lib/configuration_dsl/dsl.rb

@@ -0,0 +1,9 @@
+module ConfigurationDsl
+  class Dsl
+    attr_reader :configuration
+  
+    def initialize(configuration)
+      @configuration = configuration
+    end
+  end
+end

data/lib/configuration_dsl/impl.rb

@@ -0,0 +1,59 @@
+module ConfigurationDsl
+  class Impl
+    attr_accessor :module, :callback, :configuration
+    
+    def self.dup_struct(struct)
+      members = struct.members.collect{ |member| member.to_sym } # Normalize between Ruby versions.
+      values = struct.values.collect do |value|
+        if value.kind_of?(Class)
+          value
+        else
+          value.dup rescue value
+        end
+      end
+      Struct.new(*members).new(*values)
+    end
+    
+    def initialize(object)
+      @object = object
+    end
+    
+    def find_module
+      ancestors.each do |object|
+        next unless (impl = object.instance_variable_get(:@configuration_dsl))
+        return impl.module if impl.module
+      end
+      nil
+    end
+    
+    def find_callback
+      ancestors.each do |object|
+        next unless (impl = object.instance_variable_get(:@configuration_dsl))
+        return impl.callback if impl.callback
+      end
+      nil
+    end
+    
+    def find_configuration
+      ancestors.each do |object|
+        next unless (impl = object.instance_variable_get(:@configuration_dsl))
+        return impl.configuration if impl.configuration
+      end
+      nil
+    end
+    
+    def default_configuration
+      defaults = find_module.const_get(:DEFAULTS)
+      Struct.new(*defaults.keys).new(*defaults.values)
+    end
+    
+    def default_configuration!
+      @configuration = default_configuration.freeze
+    end
+    
+    def ancestors
+      @object.respond_to?(:ancestors) ? @object.ancestors : [@object]
+    end
+    
+  end
+end

data/test/helper.rb

@@ -0,0 +1,52 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'test/unit'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'configuration_dsl'
+
+class Test::Unit::TestCase
+  attr_reader :configuration_module, :auto_module, :object
+  
+  def setup
+    @configuration_module = Module.new do
+      const_set(:DEFAULTS, {
+        :a => nil,
+        :b => :b,
+        :c => "c"
+      })
+
+      def a(v)
+        configuration.a = v
+      end
+
+      def b(v)
+        configuration.b = v
+      end
+
+      def c(v)
+        configuration.c = v
+      end
+    end
+    
+    @auto_module = Module.new do
+      const_set(:DEFAULTS, {
+        :a => nil,
+        :b => :b,
+        :c => "c"
+      })
+      def c(v)
+        configuration.c = "c:#{v}"
+      end
+    end
+  end
+  
+end

data/test/test_configuration_dsl.rb

@@ -0,0 +1,155 @@
+require 'helper'
+
+class TestConfigurationDsl < Test::Unit::TestCase
+  
+  def both_configure
+    object.extend(ConfigurationDsl)
+    object.configure_with(configuration_module)
+    assert_equal nil, object.configuration.a
+    assert_equal :b,  object.configuration.b
+    assert_equal "c", object.configuration.c
+    
+    object.configure{ a("a") }
+    assert_equal "a", object.configuration.a
+    assert_equal :b,  object.configuration.b
+    assert_equal "c", object.configuration.c
+  end
+  
+  def both_callback
+    object.extend(ConfigurationDsl)
+    object.configure_with(configuration_module){ @something = "blahtest" }
+    object.configure
+    assert_equal "blahtest", object.instance_variable_get(:@something)
+  end
+  
+  def test_inheritance
+    klass = Class.new
+    klass.extend ConfigurationDsl
+    klass.configure_with(configuration_module)
+    klass.configure do
+      b "bee"
+    end
+    
+    derived = Class.new(klass)
+    assert_equal nil,   derived.configuration.a
+    assert_equal "bee", derived.configuration.b
+    assert_equal "c",   derived.configuration.c
+    
+    derived.configure do
+      c :sea
+    end
+    assert_equal nil,   derived.configuration.a
+    assert_equal "bee", derived.configuration.b
+    assert_equal :sea,  derived.configuration.c
+    
+    # Make sure the inherited class's configuration didn't change.
+    assert_equal nil,   klass.configuration.a
+    assert_equal "bee", klass.configuration.b
+    assert_equal "c",   klass.configuration.c
+  end
+  
+  def test_deep_inheritance
+    
+    # Obscure bug where the base class extends ConfigurationDsl and calls
+    # configure_with, but never configure.  Then a class inherits and does
+    # call configure.
+    
+    klass = Class.new
+    klass.extend ConfigurationDsl
+    klass.configure_with(configuration_module)
+    
+    derived = Class.new(klass)
+    derived.configure do
+      c :sea
+    end
+    
+    assert_equal :sea, derived.configuration.c
+  end
+  
+  def test_inherit_does_not_dup_classes
+    base = Class.new
+    base.extend ConfigurationDsl
+    base.configure_with(configuration_module)
+    
+    require "timeout"
+    base.configure do
+      a Timeout::Error
+    end
+    
+    derived = Class.new(base)
+    assert_equal Timeout::Error, derived.configuration.a
+  end
+  
+  def test_override_inheritance
+    klass = Class.new
+    klass.extend ConfigurationDsl
+    klass.configure_with(configuration_module)
+    klass.configure do
+      b "bee"
+    end
+    
+    derived = Class.new(klass)
+    assert_equal nil,   derived.configuration.a
+    assert_equal "bee", derived.configuration.b
+    assert_equal "c",   derived.configuration.c
+    
+    new_module = Module.new do
+      const_set(:DEFAULTS, {
+        :x => "x",
+        :y => "y",
+        :z => "z"
+      })
+      def x(v); configuration.x = v; end
+      def y(v); configuration.y = v; end
+      def z(v); configuration.z = v; end
+    end
+    
+    derived.configure_with(new_module)
+    assert_equal "x", derived.configuration.x
+    assert_equal "y", derived.configuration.y
+    assert_equal "z", derived.configuration.z
+  end
+  
+  def test_frozen_configuration
+    object = Object.new
+    object.extend ConfigurationDsl
+    object.configure_with(configuration_module)
+    assert_equal :b, object.configuration.b
+    assert_raises(RuntimeError){ object.configuration.b = "something" }
+    object.configure do
+      b "bee"
+    end
+    assert_equal "bee", object.configuration.b
+    assert_raises(RuntimeError){ object.configuration.b = "something" }
+  end
+  
+  def both_auto_setters
+    object.extend ConfigurationDsl
+    object.configure_with(auto_module)
+    object.configure do
+      a "aye"
+      b "bee"
+      c "sea"
+    end
+    assert_equal "aye", object.configuration.a
+    assert_equal "bee", object.configuration.b
+    assert_equal "c:sea", object.configuration.c # Custom setters.
+  end
+  
+  instance_methods.each do |method_name|
+    if method_name.to_s =~ /^both_/
+      base_name = method_name.to_s.sub(/^both_/, "")
+      class_eval <<-code
+        def test_object_#{base_name}
+          @object = Object.new
+          #{method_name}
+        end
+        def test_class_#{base_name}
+          @object = Class.new
+          #{method_name}
+        end
+      code
+    end
+  end
+  
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification 
+name: configuration_dsl
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Christopher J Bottaro
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-02 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 5
+        - 2
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+description: Easily configure a class (or object) with a DSL.
+email: cjbottaro@alumni.cs.utexas.edu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- .document
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/configuration_dsl.rb
+- lib/configuration_dsl/dsl.rb
+- lib/configuration_dsl/impl.rb
+- test/helper.rb
+- test/test_configuration_dsl.rb
+has_rdoc: true
+homepage: http://github.com/cjbottaro/configuration_dsl
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -826723195589293974
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Configure classes and objects using a DSL.
+test_files: 
+- test/helper.rb
+- test/test_configuration_dsl.rb