configru 0.0.2 → 0.1.0

data/README.md

@@ -2,40 +2,133 @@
 
 Versatile configuration file loader for Ruby
 
-## Desired Example Usage
+## Installation
 
+    gem install configru
+
+## Usage
+
+Configru loads YAML configuration files and provides a simple way to access
+configuration options.
+
+### Loading Configuration Files
+
+Configru provides a DSL for loading configuration files.
+
+```ruby
+require 'configru'
+
+Configru.load do
+  # Things
+end
+```
+
+At the very least, the block passed to `Configru.load` must tell Configru
+which files it should load. There are two different methods of loading
+configuration files available.
+
+#### Just load a file already!
+
+This is the simplest method of loading. It just loads a file, already!
+
+```ruby
+Configru.load do
+  just 'foo.yml'
+end
+```
+
+#### First-of Loading
+
+This method loads the first file that exists, ignoring all other files.
+
+```ruby
+Configru.load do
+  first_of 'foo.yml', '~/foo.yml', '/etc/foo.yml'
+end
+```
+
+#### Cascading Loading
+
+This method of loading loads each file given (if it exists) and cascades
+their values. The values in the first given file have highest priority,
+and the values in the last file have lowest priority.
+
+```ruby
+Configru.load do
+  cascade '~/foo.yml', '/etc/foo.yml'
+end
+```
+
+This will load `/etc/foo.yml` first, then `~/foo.yml`. The values in
+`~/foo.yml` will overwrite the values in `/etc/foo.yml`. If a configuration
+option is omitted in `~/foo.yml`, it will default to the value in
+`/etc/foo.yml`.
+
+### Accessing Options
+
+Configru aims to make accessing configuration values as simple as possible.
+All configuration options can be accessed as methods on the module
+`Configru`.
+
+##### foo.yml
 ```yaml
-server: irc.ninthbit.net
-port: 6667
-nick: awesomeface
-powerlevel: 9
-awesome: omgyes
+nick: bob
+server:
+  address: foo.net
+  port: 6782
 ```
 
+##### foo.rb
 ```ruby
 require 'configru'
+require 'socket'
 
 Configru.load do
-  cascade '~/foo.yml', '/etc/foo.yml' # Set files to look in
+  first_of 'foo.yml', '~/foo.yml'
+end
+
+s = TCPSocket.new(Configru.server.address, Configru.server.port)
+s.puts "Hello, I am #{Configru.nick}"
+```
+
+Configuration options can also be accessed the old-fashioned way like a
+Hash. `Configru['server']['port']` is equivalent to `Configru.server.port`.
+
+Configuration optiosn with hyphens (ie. `foo-bar`) can be accessed either
+using the old-fashioned way (ie. `Configru['foo-bar']`), or by replacing
+the hyphens with underscores for the method way (ie. `Configru.foo_bar`).
+
+### Defaults
+
+Configru's load DSL allows for setting configuration defaults.
+
+```ruby
+require 'configru'
+
+Configru.load do
+  first_of 'foo.yml', '~/foo.yml'
   defaults do
-    server 'irc.freenode.net'
-    port 6667
-    nick 'bot'
-    powerlevel 1
-    awesome 'not at all'
-  end
-  verify do
-    server /\S+/ # Must match regex
-    nick /\S+/
-    port Fixnum # Must be an instance of
-    powerlevel 1..10 # Must be in range
-    awesome ['not at all', 'omgyes', 'meh'] # Must be one of
+    nick 'Dr. Nader'
+    server do
+      address 'abcd.com'
+      port 1111
+    end
   end
 end
+```
 
-puts "Connecting to #{Configru.server}:#{Configru.port}"
+The above `defaults` block is equivalent to the following YAML:
+
+```yaml
+nick: Dr. Nader
+server:
+  address: abcd.com
+  port: 1111
 ```
 
+If no configuration files are found or if the configuration file omits an
+option, the values in `defaults` will be used.
+
 ## License
 
 Copyright (c) 2011, Curtis McEnroe <programble@gmail.com>

data/lib/configru/dsl.rb

@@ -10,11 +10,13 @@ module Configru
         @load_method = :first
         instance_eval(&block)
       end
-      
+
       def first_of(*args)
         @load_method = :first
         @files_array = args
       end
+
+      alias :just :first_of
       
       def cascade(*args)
         @load_method = :cascade

data/lib/configru/version.rb

@@ -1,3 +1,3 @@
 module Configru
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 2
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors: 
 - Curtis McEnroe
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-15 00:00:00 -04:00
+date: 2011-07-17 00:00:00 -04:00
 default_executable: 
 dependencies: []