Confection
¶ ↑
Homepage / Source Code / Report Issue / Mailing List / IRC Channel
Description¶ ↑
Confection
is multi-tenant configuration system for Ruby projects. If was designed to facilitate Ruby-based configuration for multiple tools in a single file. It is extremely simple, which makes it easy to understand and flexible in use.
Instruction¶ ↑
To get started, create a master configuration file for your project called Config.rb
. The file can have any name that matches .config.rb
, Config.rb
or config.rb
, in that order of precedence. In this file add configuration blocks by name. For example, let’s demonstrate how we could use this to configure Rake tasks.
$ cat Config.rb config :rake do desc 'generate yard docs' task :yard do sh 'yard' end end
In our Rakefile:
$ cat Rakefile require 'confection' confection(:rake, '*').load
Now you might wonder why the heck you would do this. That’s where the multi-tenancy comes into play. Let’s add another configuration, and this time for a tool that has native support for Confection
.
$ cat Config.rb title = "MyApp" config :rake do desc 'generate yard docs' task :yard do sh "yard doc --title #{title}" end end config :qedoc do |doc| doc.title = "#{title} Demonstrandum" end
Now we have configuration for both the rake tool and the qedoc tool in a single file. Thus we gain the advantage of reducing the file count of our project while pulling our tool configurations together into one place. Moreover, these configurations can potentially share settings as demonstrated here via the title
variable.
Confection
also supports profiles, either via a profile
block or via a second config argument.
config :qed, :cov do require 'simplecov' ... end
Or,
profile :cov config :qed do require 'simplecov' ... end end
Using Confection
in your libraries is very simple, as can be seen from our Rakefile example. The #confection
method (alias #config
) is used to get a handle on a named configuration. With it you have a few options, #call
, #exec
or #load
, #to_s
or #to_h
.
The #call
method evaluates a config’s block in a separate per-configuration file context in which it was defined. This is recommended. The #exec
method, on the other hand, will evaluate the block in the context of the caller. Where as the #load
method evaluates the block in the toplevel context.
For instance, QED uses #exec
to import user configuration directly into its Settings instance.
confection(:qed, profile_name).exec
The last two methods, #to_s
and #to_h
are used for text-based or hash-based configurations. The qedoc
configuration above is a good example of the later. It can be converted directly into a Hash.
confection(:qedoc, :cov).to_h #=> {:title => "MyApp Demonstration"}
Lastly, there is the #confect
method (alias #configure
). This is just like the #confection
method, but automatically invokes configure(self)
on each selected configuration. In most cases that’s exactly what is needed, so it saves having to make the additional invocation on the return value of #confection
.
Dependencies¶ ↑
Libraries¶ ↑
Confection
depends on the Finder library to provide reliable load path and Gem searching. This is used when importing configurations from external projects.
Confection
also depends on Ruby Facets for just a few very useful core extensions.
To use Confection
on Ruby 1.8 series, the BlankSlate
library is also needed in order to emulate Ruby’s BasicObject. (This may change to the Backports
project in a future version.)
Core Extensions¶ ↑
Confection
uses two core extensions, #to_h
, which applies a few different classes, String#tabto
. These come from Ruby Facets to ensure a high standard of interoperability.
Both of these methods have been suggested for inclusion in Ruby proper. Please head over to Ruby Issue Tracker and add your support.
Release Notes¶ ↑
Please see HISTORY.rdoc file.
Copyrights¶ ↑
Copyright © 2011 Rubyworks
Confection
is distributable in accordance with the BSD-2-Clause license.
See LICENSE.txt file for details.