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 © 2011 Christopher J Bottaro. See LICENSE.txt for further details.