= 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 MyConfiguration def greeting(s) s end

def count(n)
  n
end

end

require "configuration_dsl"

class MyAwesomeClass extend ConfigurationDsl configure_with(MyConfiguration) configure do greeting "Hello!" count 1 end end

MyAwesomeClass.configuration.greeting

=> "Hello!"

MyAwesomeClass.configuration.count

=> 1

The basic idea is that you define a module with your configuration options, then you configure your class/object with it.

== Why a module?

Why are the configuration options stored in a module? It makes for pretty documentation! Just run rdoc on your configuration module.

== Default values, lazily evaluated values and modified values.

Default values are supported in an intuative way. If you specify a block for a value, then it is lazily evaluated when you try to access the value for the first time.

class MyClass extend ConfigurationDsl configure_with Module.new { def name(s = "Christopher") s end def time(t) t end def age(n) n - 1 end def callback(proc) proc end } configure do puts Time.now # => 2011-08-02 01:11:50 -0400 time{ Time.now } age 31 greeter Proc.new{ |name| "Hello, #{name}" } end end

sleep(2) MyClass.configuration.time # => 2011-08-02 01:11:52 -0400 MyClass.configuration.age # => 30 MyClass.configuration.name # => "Christopher" MyClass.configuration.greeter.call("Chris") # => "Hello, Chris"

Make sense?

== Working with objects

configuration_dsl works with plain objects (in addition to classes). Given the module MyConfiguration from our previous examples:

foo = Foo.new foo.extend(ConfigurationDsl) foo.configure_with(MyConfiguration) 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.

== 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.

== Configuring the +configure+ and +configuration+ methods

You can use different methods for #configure and #configuration.

class MyClass extend ConfigurationDsl configure_with(SomeModule, :method => :setup, :storage => :settings) setup do setting1 "blah" setting2 "bleh" end end

MyClass.settings.setting1 # => "blah" MyClass.settings.setting2 # => "bleh"

== Multiple Configurations

+configuration_dsl+ supports multiple configurations for a single object.

module PersonalConfig def name(s) s.to_s end def age(n) n.to_i end end

module AccountsConfig def twitter(name) name.to_s end def email(email) email.to_s end end

class MyClass extend ConfigurationDsl configure_with(PersonalConfig, :method => :configure_personal, :storage => :personal_configuration) configure_with(AccountsConfig, :method => :configure_accounts, :storage => :accounts_configuration) configure_personal do name "Christopher" age 31 end configure_accounts do twitter "cjbottaro" email "[email protected]" end end

MyClass.personal_configuration.name # => "Christopher" MyClass.personal_configuration.age # => 31 MyClass.accounts_configuration.twitter # => "cjbottaro" MyClass.accounts_configuration.email # => "[email protected]"

== 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.