iqeo-conf 0.0.10 → 0.0.11

data/.gitignore

@@ -1,4 +1,4 @@
 .idea/
-.bundle/
+.rspec
 .rvmrc
-
+pkg/

data/.yardoc/checksums

@@ -0,0 +1,2 @@
+lib/iqeo/configuration.rb 0790c6ed002a1b1e69afc4f38e218756c5ac480f
+lib/iqeo/configuration/version.rb dad9c52c1d00b3028d333907df8e3ad45d475d93

data/.yardoc/proxy_types

@@ -0,0 +1,2 @@
+{I"Object:EF:
+class

data/Gemfile.lock

@@ -2,14 +2,16 @@ PATH
   remote: .
   specs:
     iqeo-conf (0.0.11)
-      blankslate (~> 2.1.2.4)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    blankslate (2.1.2.4)
     diff-lcs (1.1.3)
+    json (1.7.1)
     rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    redcarpet (2.1.1)
     rspec (2.9.0)
       rspec-core (~> 2.9.0)
       rspec-expectations (~> 2.9.0)
@@ -18,6 +20,7 @@ GEM
     rspec-expectations (2.9.1)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.9.0)
+    yard (0.8.1)
 
 PLATFORMS
   ruby
@@ -25,4 +28,7 @@ PLATFORMS
 DEPENDENCIES
   iqeo-conf!
   rake (~> 0.9.2)
+  rdoc (~> 3.12.0)
+  redcarpet (~> 2.1.1)
   rspec (~> 2.9.0)
+  yard (~> 0.8.1)

data/README.md

@@ -1,108 +1,136 @@
 # Iqeo::Configuration
 
-A DSL for writing configuration files.
+A DSL representing configuration files.
 
 ## Installation
 
-It's a gem...
+It`s a gem...
 
-```
-$ gem install iqeo-conf
-```
+    $ gem install iqeo-conf
 
 ## Usage
 
-Require it...
+Require 'iqeo/configuration' and optionally include Iqeo namespace:
 
 ```ruby
 require 'iqeo/configuration'
+include Iqeo
 ```
 
-### Create a configuration
+### Create configuration
 
-Set values...
+There are three ways to create configurations; explicit, block DSL, eval DSL.
 
-#### Directly on a configuration object
+#### Explicit
 
-```ruby
-conf = Iqeo::Configuration.new
+Call Configuration#new without a block.
+Explicitly call methods on instance to configure instance.
 
-# add some settings
-
-conf.alpha 42
-conf.bravo "foobar"
-conf.charlie { :a => 1, :b => 2, :c => 3 }
-conf.delta [ 1, 2, 3 ]
+```ruby
+conf = Configuration.new
+conf.alpha   1
+conf.bravo   2.0
+conf.charlie :three
+conf.delta   "four"
 ```
 
-#### Configuration DSL block yield style
+#### Block DSL
+
+Call Configuration#new with a block that expects a variable, a new instance will be yielded.
+Within block, call methods on yielded instance to configure.
 
 ```ruby
-conf = Iqeo::Configuration.new do |c|
+conf = Configuration.new do |c|
+  c.alpha   1
+  c.bravo   2.0
+  c.charlie :three
+  c.delta   "four"
+end
+```
 
-  c.alpha 42
-  c.bravo "foobar"
-  c.charlie { :a => 1, :b => 2, :c => 3 }
-  c.delta [ 1, 2, 3 ]
+#### Eval DSL
 
+Call Configuration#new with a block that does not expect a variable, contents of the block are eval`d in the context of the new instance.
+Call methods with implied self to configure instance.
+
+```ruby
+conf = Configuration.new do
+  alpha   1
+  bravo   2.0
+  charlie :three
+  delta   "four"
 end
 ```
 
-#### Configuration DSL instance_eval style
+### Read configuration
 
-```ruby
-conf = Iqeo::Configuration.new do
+All examples above result in the same configuration.
+Configuration settings can be retrieved directly or indirectly.
 
-  alpha 42
-  bravo "foobar"
-  charlie { :a => 1, :b => 2, :c => 3 }
-  delta [ 1, 2, 3 ]
+#### Directly
 
-end
+##### Named method
+
+```ruby
+conf.alpha        # => 1
+conf.bravo        # => 2.0
+conf.charlie      # => :three
+conf.delta        # => "four"
 ```
 
-### Reading a configuration
+##### [ 'string' ]
 
-Retrieve settings...
+```ruby
+conf['alpha']     # => 1
+conf['bravo']     # => 2.0
+conf['charlie']   # => :three
+conf['delta']     # => "four"
+```
+
+##### [ :symbol ]
 
 ```ruby
-conf.alpha      =>  42
-conf.bravo      =>  "foobar"
-conf.charlie    =>  { :a => 1, :b => 2, :c => 3 }
-conf.delta      =>  [ 1, 2, 3 ]
+conf[:alpha]      # => 1
+conf[:bravo]      # => 2.0
+conf[:charlie]    # => :three
+conf[:delta]      # => "four"
 ```
 
-## Other features
+#### Indirectly
 
-This README may not be complete, see rspec tests for all working features.
+The underlying storage is an indifferent hash, so the usual Hash and Enumerable methods work.
 
-## Done
+##### Hash & Enumerable methods
 
-Need docs...
+```ruby
+conf.size                           # => 4
+conf.keys                           # => [ 'alpha', 'bravo', 'charlie', 'delta' ]
+conf.collect { |key,value| value }  # => [ 1, 2.0, :three, 'four' ]
+```
 
-* Hash operators [] & []=
-* Nested configurations
-* Nested configurations inherit settings
-* Nested configurations override inherited settings
-* Load configurations from a string or file at creation
-* Iterate over items hash - by delegation to hash
-* Indifferent hash access - using ActiveSupport/HashWithIndifferentAccess
-* Clean DSL syntax for creating a nested configuration - just a block ?
-* Load configurations from a string or file after creation / in DSL block
+## Features
 
-## Todo
+* settings by named methods
+* settings by '[]' & '[]='
+* settings & locals with '='
+* referencing existing settings
+* nested configurations
+* inheritance & override
+* read from string, at creation, or after - merged & nested
+* load from filename, at creation, or after - merged & nested
+* todo: merge configurations
+* todo: defaults
+* todo: blank slate
 
-Need time (have motivation)...
+## Fancy usage
 
-* Configuration file load path
-* Use an existing configuration for defaults
-* Blank slate for DSL ? - optional ?
-* Option to get hash directly to prevent polluting namespace with delegated hash methods
-* Consider issues around deferred interpolation / procs / lambdas etc...
-* Load other formats into configuration - YAML, CSV, ...anything Enumerable should be easy enough.
+* Dynamic settings by '[]' & '[]=' & 'self'
+* Multiple configuration files
+* Hierarchial configuration files
 
 ## License
 
-Licensed under GPL Version 3 license
-See LICENSE file
+Copyright Gerard Fowley (gerard.fowley@iqeo.net).
 
+Licensed under GPL Version 3 license.
+See LICENSE file.

data/Rakefile

@@ -1,14 +1,22 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.test_files = FileList['test/test*.rb']
-  t.verbose = true
-end
 
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new('spec')
 
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.rdoc"
+  rdoc.rdoc_files.include "README.rdoc", "lib/**/*.rb"
+  rdoc.rdoc_files.exclude "lib/**/hash_with_indifferent_access.rb"
+  rdoc.options << "--all" << "--verbose"
+end
+
+require 'yard'
+#require 'yard/rake/yardoc_task'
+YARD::Rake::YardocTask.new do |yard|
+  yard.files   = %w( lib/**/*.rb )
+  yard.options = %w( --main README.md --exclude hash_with_indifferent_access.rb )
+end
+
 task :default => :spec