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.