rc 0.2.0 → 0.3.0

data/.index

@@ -0,0 +1,66 @@
+---
+type: ruby
+revision: 2013
+sources:
+- var
+authors:
+- name: Trans
+  email: transfire@gmail.com
+organizations: []
+requirements:
+- name: finder
+- groups:
+  - build
+  development: true
+  name: detroit
+- groups:
+  - test
+  development: true
+  name: qed
+- groups:
+  - test
+  development: true
+  name: ae
+- groups:
+  - test
+  development: true
+  name: test
+conflicts: []
+alternatives: []
+resources:
+- type: home
+  uri: http://rubyworks.github.com/rc
+  label: Homepage
+- type: docs
+  uri: http://rubydoc.info/github/rubyworks/rc/master/frames
+  label: Documentation
+- type: code
+  uri: http://github.com/rubyworks/rc
+  label: Source Code
+- type: mail
+  uri: http://groups.google.com/group/rubyworks-mailinglist
+  label: Mailing List
+- type: chat
+  uri: http://chat.us.freenode.net/rubyworks
+  label: IRC Channel
+repositories:
+- name: upstream
+  scm: git
+  uri: git://github.com/rubyworks/rc.git
+categories: []
+paths:
+  load:
+  - lib
+copyrights:
+- holder: Rubyworks
+  year: '2011'
+  license: BSD-2-Clause
+created: '2011-11-06'
+summary: The best way to manage your application's configuration.
+title: RC
+version: 0.3.0
+name: rc
+description: ! 'R.C. is a multi-tenant configuration system for Ruby projects.
+
+  R.C. can configure almost any Ruby tool or library.'
+date: '2013-01-08'

data/.rubyrc

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+
+#
+# Configure QED demo tool.
+#
+config 'qed' do
+  puts "QED!"
+end
+
+#
+# QED test coverage report using SimpleCov.
+#
+# Use `$properties.coverage_folder` to set directory in which to store
+# coverage report this defaults to `log/coverage`.
+#
+# IMPORTANT! Unfortunately this will not give us a reliable report
+# b/c QED uses the RC gem, so SimpleCov can't differentiate the two.
+#
+config 'qed', :profile=>'cov' do
+  puts "QED w/coverage!"
+
+  require 'simplecov'
+
+  dir = $properties.coverage_folder
+
+  SimpleCov.start do
+    coverage_dir(dir || 'log/coverage')
+    #add_group "Label", "lib/qed/directory"
+  end
+end
+
+#
+#
+#
+config 'pry' do
+  puts "Pry on RC!"
+  $LOAD_PATH.unshift('lib')
+end
+
+#
+# Detroit assembly.
+#
+config 'detroit' do |asm|
+  asm.service :email do |s|
+    s.mailto = ['ruby-talk@ruby-lang.org', 
+                'rubyworks-mailinglist@googlegroups.com']
+  end
+
+  asm.service :gem do |s|
+    s.gemspec = 'pkg/rc.gemspec'
+  end
+
+  asm.service :github do |s|
+    s.folder = 'web'
+  end
+
+  asm.service :dnote do |s|
+    s.title  = 'Source Notes'
+    s.output = 'log/notes.html'
+  end
+
+  asm.service :locat do |s|
+    s.output = 'log/locat.html'
+  end
+
+  asm.service :vclog do |s|
+    s.output = ['log/history.html',
+                'log/changes.html']
+  end
+end
+
+#
+# Rake tasks 
+#
+config 'rake' do
+  desc 'run unit tests'
+  task 'test' do
+    puts "Rake Boo!"
+  end
+end
+
+#
+# Example configuration.
+#
+config 'example' do
+  puts "Configuration Example!"
+end
+

data/.yardopts

@@ -0,0 +1,8 @@
+--title "Runtime Configuration"
+--readme README.rdoc
+--protected
+--private
+lib
+-
+[A-Z]*.*
+

data/HISTORY.md

@@ -0,0 +1,40 @@
+# RELEASE HISTORY
+
+## 0.3.0 / 2012-13-08
+
+This release is of the project finally begins to settle down the API.
+The most significant change since the last release is the use of `.rubyrc`,
+or just `.ruby`, as the name for the standard configuration file. It was 
+changed from the previous `Config.rb` file name in order to avoid any
+confusion with Rails `config` directory or any other use of the word.
+If you still prefer the old name, simply add a `.rubyrc` file to your
+project containing `import "Config.rb"` to get equivalent functionality.
+Other than that the majority of changes have been to improve the library
+internally.
+
+Changes:
+
+* Change default config file name to `.rubyrc`, or just `.ruby`.
+* Improve configuration loading code.
+* Remove dependency on Courtier.
+
+
+## 0.2.0 / 2012-04-16
+
+Major improvements and simplifications to design and API.
+Basically, just read the README to see what is new.
+
+Changes:
+
+* Add support for require-based configuration setups.
+* Overhaul and drastically simplify design.
+
+
+## 0.1.1 . 2012-04-09
+
+Initial release of RC. 
+
+Changes:
+
+* Happy first release.
+

data/LICENSE.txt

@@ -0,0 +1,27 @@
+(BSD-2-Clause license)
+
+Ruby Confection (http://rubyworks.github.com/rc)
+
+Copyright (c) 2011 Rubyworks. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/README.md

@@ -0,0 +1,194 @@
+# RC - Runtime Configuration
+
+[Homepage](http://rubyworks.github.com/rc) /
+[Report Issue](http://github.com/rubyworks/rc/issues) /
+[Source Code](http://github.com/rubyworks/rc)
+( [![Build Status](https://secure.travis-ci.org/rubyworks/rc.png)](http://travis-ci.org/rubyworks/rc) )
+
+
+## About
+
+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.
+
+
+## Installation
+
+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 always available.
+
+
+## Instruction
+
+To use RC in a project create a configuration file called either `.rc` or `RC.rb`. 
+Technically the file can be any variation of `rc` with an optional `.rb` extension,
+hidden or not and case-insensitive. Hidden file names have precedence if multiple
+matches exist. 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 most developers are just as happy
+to keep using a Rakefile. But a Rake example serves to show that it can be done,
+and also it makes a good tie-in with next example.)
+
+    $ cat Config.rb
+    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 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} 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.
+
+
+## Customization
+
+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.
+
+
+## Dependencies
+
+### Libraries
+
+RC depends on the [Finder](http://rubyworks.github.com/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.)
+
+### Core Extensions
+
+RC uses two core extensions, `#to_h`, which applies to a few different
+classes, and `String#tabto`. These are *copied* from
+[Ruby Facets](http://rubyworks.github.com/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.
+
+* http://bugs.ruby-lang.org/issues/749
+* http://bugs.ruby-lang.org/issues/6056
+
+
+## Release Notes
+
+Please see HISTORY.md file.
+
+
+## Copyrights
+
+Copyright (c) 2011 Rubyworks
+
+Confection is distributable in accordance with the **BSD-2-Clause** license.
+
+See LICENSE.txt file for details.
+

data/demo/00_concept.md

@@ -0,0 +1,23 @@
+# R.C.
+
+The purpose of R.C. is to provide unified configuration management
+for Ruby tools.
+
+R.C. designates a single per-project configuration file, named
+either `.config.rb`, `Config.rb` or `config.rb`, looked up in that 
+order. The structure of this configuration file is very simple.
+It is a ruby script sectioned into named `config` and `onload`
+blocks:
+
+    config 'rubytest' do
+      # ... configure rubytest command ...
+    end
+
+    onload 'rake' do
+      # ... when rake is required then ...
+    end
+
+Utilization of the these configurations may be handled by the consuming 
+application, but can be used on any Ruby-based tool if `-rc` is added 
+to RUBYOPT.
+