= configurable

* http://bitbucket.org/krbullock/configurable

== DESCRIPTION:

Lets you make your Ruby class configurable with a simple mixin.

== FEATURES/PROBLEMS:

* Generic mixin that you can use in any Ruby class (or application).

* Separates handling configuration of a class from its implementation.

* Supports nested settings.

* Rejects configuration keys outside those you specify.

* Supports setting defaults on a class which can then be modified for
  each instance of the class.

* Settings are stored in Structs (well, actually a subclass of Struct),
  so they can be accessed via normal methods calls, or by Symbol or
  String keys.

* Settings (even nested settings) can be serialized to a hash with
  string keys, which means you can also trivially serialize to YAML (or
  JSON).

* Settings (even nested settings) can be loaded from a hash, which means
  you can also trivially deserialize from YAML (and remember, YAML is a
  superset of JSON).

* Plays nicely with the Singleton module.

* Can safely store other kinds of structs as opaque config values. They
  won't get automatically deep-copied.

* Doesn't yet support independent configs for classes and their subclasses.

== SYNOPSIS:

 require 'configurable'
 class Doodad
   include Configurable

   # Declare the allowed options and their default values
   configurable_options :foo => 'default',
     :bar => {:quux => 42, :wibble => nil},
     :baz => nil
 end

 Doodad::Config              # => a ConfigStruct::Struct
 Doodad::Config::Bar         # => another ConfigStruct::Struct

 Doodad::Config.defaults     # => #<struct Doodad::Config
                             #     bar=#<struct Doodad::Config::Bar
                             #          quux=42, wibble=nil>,
                             #     baz=nil,
                             #     foo="default">

 Doodad.config               # => a (deep) copy of Doodad::Config.defaults,
                             #    ready for use

 Doodad.config.replace(      # replaces config with passed values
   :foo => 'mine',
   :bar => {:quux => 9})

 Doodad.config.update(       # loads config from a YAML file
   YAML.load('config.yml'))

See the documentation on Configurable for an overview and links to more
specifics.

=== Using with Rails

If you want to make a Rails class configurable, you'll need some special
mojo to reconfigure the class when it gets reloaded in development mode.
You can do this with Rails.application.config.to_prepare. For example,
to have your class configuration reloaded from a YAML file, create an
initializer like so:

 Rails.application.config.to_prepare do
   begin
     Doodad.config.update(
       YAML.load_file(File.join(Rails.root, 'config', 'doodad.yml')) || {})
   rescue Errno::ENOENT
     # handle missing config file
   end
 end

== REQUIREMENTS:

* Ruby

== INSTALL:

 $ gem install ruby-configurable

== DEVELOPERS:

After checking out the source, run:

 $ rake newb

This task will install any missing dependencies, run the tests/specs,
and generate the RDoc.

== LICENSE:

(GNU General Public License v2.0)

Copyright (C) 2010 Kevin R. Bullock

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.