=== Welcome to RConfigurator!

--- Abstract

RConfigurator automatically "hydrates" your application's module constants by walking
through a .yml file. If you've got module constants strewn throughout your project, 
you can use RConfigurator to aggregate these into one place.

--- Usage

Just require 'rconfigurator', provide the location of the configuration file and the
name of a project, and then call RConfigurator.configure!:

    require 'rconfigurator'
    RConfigurator.configure! "ExampleModule", "/path/to/my/config"

Configurator will analyze the file and 'inflate' your module constants using the data 
it finds there. Let's say you've got the following module constants:

  ExampleModule::KEY = 'value'
  ExampleModule::NUMERIC_DATA = 3.221
  ExampleModule::SampleModule::SOME_KEY = 'another value'    
  ExampleModule::KEY_SHOULD_BE_MODULE = I::Am::A::Module

RConfigurator can create these for you (before you've even defined the modules
themselves!) if you point it to the following .yml file:

	key: value
	numeric_data: 3.221
	sample_module:
	    some_key: another value
	key_should_be_module: I::Am::A::Module


RConfigurator even handles some common edge cases for you, in particular the case 
when the value is itself a module. RConfigurator will construct the module context 
in place just before it needs a reference. 

For a better feel of how this ends up being useful, or perhaps some inspiration,
here's an example of part of a real configuration file I am using for another 
small project:

		version: 0.3.9
		release: alpha
		authors: joseph weissman
		license: artistic <http://www.perlfoundation.org/artistic_license_2_0>

		# support module config
		support:
		    logging:
		        use_chainsaw: true
		        chainsaw:
		            hostname: 'localhost'
		            port: 8071

		# graphics subsystem config
		graphics:
		    default_window_options:
		        fullscreen: true
		        width:  1920
		        height: 1080
	
		# ... 


--- Tools


RConfigurator comes with a command line utility called 'rconfig' for debugging 
your configuration files. Invoking the utility against a configuration file 
attempts to perform the configuration, logging the statements RConfigurator.config! 
would normally just silently 'eval'. Invoke this utility as 'rconfig [file1] [file2] ...' 
(assuming you have installed the gem.)

Running rconfig over the first example yaml file gives us the module structure 
we are expecting. It uses "HypotheticalParentModule" as the root project module
Note the output from rconfig is the unindented 'compact' form we actually evaluate, 
with one key-value pair per line.

	module HypotheticalParentModule; module SampleModule; SOME_KEY = "another value"; end; ; end	
	module I;  module Am;  module A;  module Module; end; end; end; end; 	
	module HypotheticalParentModule; KEY_SHOULD_BE_MODULE = I::Am::A::Module; ; end	
	module HypotheticalParentModule; KEY = "value"; ; end	
	module HypotheticalParentModule; NUMERIC_DATA = 3.221; ; end

Please note that I have added this tool as a convenience, and I should point out 
that developing the configuration file is generally quite straightforward. Using 
rconfig to 'validate' is probably not necessary. This tool is included for sanity-
inducing purposes (and perhaps more involved use-cases where it could be helpful 
in the scenario where a complex config file has become subtly incorrect.)

--- Problems? 

Please log bug reports and enhancement proposals here, or feel free to email the 
author/maintainer of RConfigurator, Joseph Weissman, jweissman1986 (at) gmail.com

--- Afterword

So far in practice, I have found that it is definitely convenient to be able to 
architecturally separate 'tuning' from code. I like that I can instantiate complex 
module structures just by adding a few lines of YAML.