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

Confection is distributable in accordance with the BSD-2-Clause license.

See LICENSE.txt file for details.