Homepage /
Report Issue /
Source Code
( 
RC is a is multi-tenant runtime configuration system for Ruby tools. It is designed to facilitate Ruby-based configuration for multiple tools in a single file, and designed to work whether the tool has built-in support for RC or not. The syntax is simple, universally applicable, yet flexible.
RC can be used with any Ruby-based commandline tool or library utilized by such tool, where there exists some means of configuring it via a toplevel/global interface; or the tool has been designed to directly support RC, of course.
To use RC with tools that support RC directly, there is likely nothing to
install. Installing the tool should install rc via a dependency and
load runtime configurations when the tool is used.
To use RC with a tool that does not provide built-in support, first install the RC library, typically via RubyGems:
gem install rc
Then add -rc to your system's RUBYOPT environment variable.
$ export RUBYOPT='-rc'
You will want to add that to your .bashrc, .profile or equivalent configuration
script, so it is always available.
To use RC in a project create a configuration file called either .ruby or .rubyrc.
The longer name has precedence if both are present. In this file add configuration blocks
by name of the commandline tool.
For example, let's demonstrate how we could use this to configure Rake tasks. (Yes, Rake is not the most obvious choice, since developers are just as happy to keep using a Rakefile. But using Rake as an example serves to show that it can be done, and also it makes a good tie-in with next example.)
$ cat .rubyrc
config :rake do
desc 'generate yard docs'
task :yard do
sh 'yard'
end
end
Now when rake is run the tasks defined in this configuration will be available.
You might wonder why anyone would do this. That's where the multi-tenancy comes into play. Let's add another configuration.
$ cat .rubyrc
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} Demos"
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 local variable.
Of course, if we want configurations stored in multiple files, that can be done
too. Simple use the import method to load them, e.g.
import 'rc/*.rb'
RC also supports profiles, either via a profile block:
profile :cov do
config :qed do
require 'simplecov'
...
end
end
Or via a keyword parameter:
config 'qed', profile: 'cov' do
require 'simplecov'
...
end
When utilizing the tool, set the profile via an environment variable.
$ profile=cov qed
RC also support just p as a convenient shortcut.
$ p=cov qed
Some tools that support RC out-of-the-box, may support a profile command line option for specifying the profile.
$ qed -p cov
Beyond mere namespacing, some tools might utilize profiles for a more specific purpose fitting the tool. Consult the tool's documentation for details.
Configurations can also be pulled in from other gems using the from option.
config :qed, :profile=>'simplecov', :from=>'qed'
As long as a project includes its .rubyrc file (and any imported files)
in it's gem package, it's possible to share configurations in this manner.
A tool can provide dedicated support for RC by loading rc/api and using the
configure method to define a configuration procedure. For example,
the detroit project defines:
require 'rc/api'
RC.configure 'detroit' do |config|
if config.command?
Detroit.rc_config << config
end
end
In our example, when detroit is required this configuration will be processed.
The if config.command? condition ensures that it only happens if the config's
command property matches the current command, i.e. $0 == 'detroit'. We see
here that Detroit stores the configuration for later use. When Detroit gets
around to doing it's thing, it checks this rc_config setting and evaluates
the configurations found there.
It is important that RC be required first, ideally before anything else. This ensures it will pick up all configured features.
Some tools will want to support a command line option for selecting a
configuration profile. RC has a convenience method to make this very
easy to do. For example, qed uses it:
RC.profile_switch('qed', '-p', '--profile')
It does not remove the argument from ARGV, so the tool's command line option
parser should still account for it. This simply ensures RC will know what the
profile is by setting ENV['profile'] to the entry following the switch.
RC depends on the Finder library to provide reliable load path and Gem searching. This is used when importing configurations from other projects. (It's very much a shame Ruby and RubyGems does not have this kind of functionality built-in.)
RC uses two core extensions, #to_h, which applies to a few different
classes, and String#tabto. These are copied 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.
Please see HISTORY.md file.
Copyright (c) 2011 Rubyworks
Confection is distributable in accordance with the BSD-2-Clause license.
See LICENSE.txt file for details.