Skip to content

Commit 947f775

Browse files
gfowleygfowley
committed
rdoc
1 parent 54ce192 commit 947f775

10 files changed

+340
-436
lines changed

‎README.rdoc

+81-73
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,116 @@
1-
# Iqeo::Configuration
1+
= Iqeo::Configuration
22

3-
A DSL for writing configuration files.
3+
A DSL representing configuration files.
44

5-
## Installation
5+
== Installation
66

7-
It's a gem...
7+
It's a gem:
88

9-
```
10-
$ gem install iqeo-conf
11-
```
9+
$ gem install iqeo-conf
1210

13-
## Usage
11+
== Usage
1412

15-
Require it...
13+
Require 'iqeo/configuration' and optionally include Iqeo namespace:
1614

17-
```ruby
18-
require 'iqeo/configuration'
19-
```
15+
require 'iqeo/configuration'
16+
include Iqeo
2017

21-
### Create a configuration
18+
=== Create configuration
2219

23-
Set values...
20+
Supports three ways to create configurations; explicit, block DSL, eval DSL.
2421

25-
#### Directly on a configuration object
22+
==== Explicit
2623

27-
```ruby
28-
conf = Iqeo::Configuration.new
24+
Call Configuration#new without a block.
2925

30-
# add some settings
26+
Explicitly call methods on instance to configure instance.
3127

32-
conf.alpha 42
33-
conf.bravo "foobar"
34-
conf.charlie { :a => 1, :b => 2, :c => 3 }
35-
conf.delta [ 1, 2, 3 ]
36-
```
28+
conf = Configuration.new # => #<Iqeo::Configuration:0x........>
29+
conf.alpha 1
30+
conf.bravo 2.0
31+
conf.charlie :three
32+
conf.delta "four"
3733

38-
#### Configuration DSL block yield style
34+
==== Block DSL
3935

40-
```ruby
41-
conf = Iqeo::Configuration.new do |c|
36+
Call Configuration#new with a block that expects a variable, a new instance will be yielded.
4237

43-
c.alpha 42
44-
c.bravo "foobar"
45-
c.charlie { :a => 1, :b => 2, :c => 3 }
46-
c.delta [ 1, 2, 3 ]
38+
Within block, call methods on yielded instance to configure.
4739

48-
end
49-
```
40+
conf = Configuration.new do |c|
41+
c.alpha 1
42+
c.bravo 2.0
43+
c.charlie :three
44+
c.delta "four"
45+
end # => #<Iqeo::Configuration:0x........>
5046

51-
#### Configuration DSL instance_eval style
47+
==== Eval DSL
5248

53-
```ruby
54-
conf = Iqeo::Configuration.new do
49+
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.
5550

56-
alpha 42
57-
bravo "foobar"
58-
charlie { :a => 1, :b => 2, :c => 3 }
59-
delta [ 1, 2, 3 ]
51+
Call methods with implied self to configure instance.
6052

61-
end
62-
```
53+
conf = Configuration.new do
54+
alpha 1
55+
bravo 2.0
56+
charlie :three
57+
delta "four"
58+
end # => #<Iqeo::Configuration:0x........>
6359

64-
### Reading a configuration
60+
=== Read configuration
6561

66-
Retrieve settings...
62+
All examples above result in the same configuration. Configuration settings can be retrieved directly in three ways:
6763

68-
```ruby
69-
conf.alpha => 42
70-
conf.bravo => "foobar"
71-
conf.charlie => { :a => 1, :b => 2, :c => 3 }
72-
conf.delta => [ 1, 2, 3 ]
73-
```
64+
==== Named method
7465

75-
## Other features
66+
conf.alpha # => 1
67+
conf.bravo # => 2.0
68+
conf.charlie # => :three
69+
conf.delta # => "four"
7670

77-
This README may not be complete, see rspec tests for all working features.
71+
==== [ 'string' ]
7872

79-
## Done
73+
conf['alpha'] # => 1
74+
conf['bravo'] # => 2.0
75+
conf['charlie'] # => :three
76+
conf['delta'] # => "four"
8077

81-
Need docs...
78+
==== [ :symbol ]
8279

83-
* Hash operators [] & []=
84-
* Nested configurations
85-
* Nested configurations inherit settings
86-
* Nested configurations override inherited settings
87-
* Load configurations from a string or file at creation
88-
* Iterate over items hash - by delegation to hash
89-
* Indifferent hash access - using ActiveSupport/HashWithIndifferentAccess
90-
* Clean DSL syntax for creating a nested configuration - just a block ?
91-
* Load configurations from a string or file after creation / in DSL block
80+
conf[:alpha] # => 1
81+
conf[:bravo] # => 2.0
82+
conf[:charlie] # => :three
83+
conf[:delta] # => "four"
9284

93-
## Todo
85+
The underlying storage is an indifferent hash, so the usual Hash and Enumerable methods work:
9486

95-
Need time (have motivation)...
87+
conf.size # => 4
88+
conf.keys # => [ 'alpha', 'bravo', 'charlie', 'delta' ]
89+
conf.collect { |key,value| value } # => [ 1, 2.0, :three, 'four' ]
9690

97-
* Configuration file load path
98-
* Use an existing configuration for defaults
99-
* Blank slate for DSL ? - optional ?
100-
* Option to get hash directly to prevent polluting namespace with delegated hash methods
101-
* Consider issues around deferred interpolation / procs / lambdas etc...
102-
* Load other formats into configuration - YAML, CSV, ...anything Enumerable should be easy enough.
91+
== Features
10392

104-
## License
93+
* settings by named methods
94+
* settings by '[]' & '[]='
95+
* settings & locals with '='
96+
* referencing existing settings
97+
* nested configurations
98+
* inheritance & override
99+
* read from string, at creation, or after - merged & nested
100+
* load from filename, at creation, or after - merged & nested
101+
* todo: merge configurations
102+
* todo: defaults
103+
* todo: blank slate
105104

106-
Licensed under GPL Version 3 license
107-
See LICENSE file
105+
== Fancy usage
108106

107+
* Dynamic settings by '[]' & '[]=' & 'self'
108+
* Multiple configuration files
109+
* Hierarchial configuration files
110+
111+
== License
112+
113+
Copyright Gerard Fowley ([email protected]).
114+
115+
Licensed under GPL Version 3 license.
116+
See LICENSE file.

‎html/Iqeo.html

+1-100
Original file line numberDiff line numberDiff line change
@@ -93,106 +93,7 @@ <h1 class="module">module Iqeo</h1>
9393

9494
<div id="description" class="description">
9595

96-
<p>Title</p>
97-
98-
<pre>blurb...</pre>
99-
100-
<p>Installation</p>
101-
102-
<pre>gem...</pre>
103-
104-
<p>Usage</p>
105-
106-
<pre class="ruby"><span class="ruby-constant">Create</span> <span class="ruby-identifier">configuration</span>
107-
<span class="ruby-identifier">modes</span> <span class="ruby-identifier">of</span> <span class="ruby-identifier">usage</span><span class="ruby-operator">...</span>
108-
109-
<span class="ruby-constant">Explicit</span>
110-
<span class="ruby-identifier">example</span><span class="ruby-operator">...</span>
111-
112-
<span class="ruby-identifier">conf</span> = <span class="ruby-constant">Configuration</span>.<span class="ruby-identifier">new</span>
113-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">alpha</span> <span class="ruby-value">1</span>
114-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">bravo</span> <span class="ruby-value">2.0</span>
115-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">charlie</span> :<span class="ruby-identifier">three</span>
116-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">delta</span> <span class="ruby-string">&quot;four&quot;</span>
117-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">echo</span> <span class="ruby-constant">Configuration</span>.<span class="ruby-identifier">new</span>
118-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">echo</span>.<span class="ruby-identifier">foxtrot</span> <span class="ruby-keyword">true</span>
119-
120-
<span class="ruby-constant">Block</span> <span class="ruby-constant">DSL</span>
121-
<span class="ruby-identifier">example</span><span class="ruby-operator">...</span> <span class="ruby-keyword">yield</span>
122-
123-
<span class="ruby-identifier">conf</span> = <span class="ruby-constant">Configuration</span>.<span class="ruby-identifier">new</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">c</span><span class="ruby-operator">|</span>
124-
<span class="ruby-identifier">c</span>.<span class="ruby-identifier">alpha</span> <span class="ruby-value">1</span>
125-
<span class="ruby-identifier">c</span>.<span class="ruby-identifier">bravo</span> <span class="ruby-value">2.0</span>
126-
<span class="ruby-identifier">c</span>.<span class="ruby-identifier">charlie</span> :<span class="ruby-identifier">three</span>
127-
<span class="ruby-identifier">c</span>.<span class="ruby-identifier">delta</span> <span class="ruby-string">&quot;four&quot;</span>
128-
<span class="ruby-identifier">c</span>.<span class="ruby-identifier">echo</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">e</span><span class="ruby-operator">|</span>
129-
<span class="ruby-identifier">e</span>.<span class="ruby-identifier">foxtrot</span> <span class="ruby-keyword">true</span>
130-
<span class="ruby-keyword">end</span>
131-
<span class="ruby-keyword">end</span>
132-
133-
<span class="ruby-constant">Eval</span> <span class="ruby-constant">DSL</span>
134-
<span class="ruby-identifier">example</span><span class="ruby-operator">...</span> <span class="ruby-identifier">instance_eval</span>
135-
136-
<span class="ruby-identifier">conf</span> = <span class="ruby-constant">Configuration</span>.<span class="ruby-identifier">new</span> <span class="ruby-keyword">do</span>
137-
<span class="ruby-identifier">alpha</span> <span class="ruby-value">1</span>
138-
<span class="ruby-identifier">bravo</span> <span class="ruby-value">2.0</span>
139-
<span class="ruby-identifier">charlie</span> :<span class="ruby-identifier">three</span>
140-
<span class="ruby-identifier">delta</span> <span class="ruby-string">&quot;four&quot;</span>
141-
<span class="ruby-identifier">echo</span> <span class="ruby-keyword">do</span>
142-
<span class="ruby-identifier">foxtrot</span> <span class="ruby-keyword">true</span>
143-
<span class="ruby-keyword">end</span>
144-
<span class="ruby-keyword">end</span>
145-
146-
<span class="ruby-constant">Read</span> <span class="ruby-identifier">configuration</span>
147-
<span class="ruby-identifier">examples</span><span class="ruby-operator">...</span>
148-
149-
<span class="ruby-identifier">method</span> <span class="ruby-identifier">access</span>
150-
151-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">alpha</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-value">1</span>
152-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">bravo</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-value">2.0</span>
153-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">charlie</span> =<span class="ruby-operator">&gt;</span> :<span class="ruby-identifier">three</span>
154-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">delta</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;four&quot;</span>
155-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">echo</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-constant">Configuration</span><span class="ruby-operator">...</span>
156-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">echo</span>.<span class="ruby-identifier">foxtrot</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
157-
158-
<span class="ruby-identifier">string</span> <span class="ruby-identifier">access</span>
159-
160-
<span class="ruby-identifier">conf</span>[<span class="ruby-string">'alpha'</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-value">1</span>
161-
<span class="ruby-identifier">conf</span>[<span class="ruby-string">'bravo'</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-value">2.0</span>
162-
<span class="ruby-identifier">conf</span>[<span class="ruby-string">'charlie'</span>] =<span class="ruby-operator">&gt;</span> :<span class="ruby-identifier">three</span>
163-
<span class="ruby-identifier">conf</span>[<span class="ruby-string">'delta'</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;four&quot;</span>
164-
<span class="ruby-identifier">conf</span>[<span class="ruby-string">'echo'</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-constant">Configuration</span><span class="ruby-operator">...</span>
165-
<span class="ruby-identifier">conf</span>[<span class="ruby-string">'echo'</span>][<span class="ruby-string">'foxtrot'</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
166-
167-
<span class="ruby-identifier">symbol</span> <span class="ruby-identifier">access</span>
168-
169-
<span class="ruby-identifier">conf</span>[:<span class="ruby-identifier">alpha</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-value">1</span>
170-
<span class="ruby-identifier">conf</span>[:<span class="ruby-identifier">bravo</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-value">2.0</span>
171-
<span class="ruby-identifier">conf</span>[:<span class="ruby-identifier">charlie</span>] =<span class="ruby-operator">&gt;</span> :<span class="ruby-identifier">three</span>
172-
<span class="ruby-identifier">conf</span>[:<span class="ruby-identifier">delta</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;four&quot;</span>
173-
<span class="ruby-identifier">conf</span>[:<span class="ruby-identifier">echo</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-constant">Configuration</span><span class="ruby-operator">...</span>
174-
<span class="ruby-identifier">conf</span>[:<span class="ruby-identifier">echo</span>][:<span class="ruby-identifier">foxtrot</span>] =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
175-
176-
<span class="ruby-identifier">enumerable</span> <span class="ruby-identifier">hash</span>
177-
178-
<span class="ruby-identifier">conf</span>.<span class="ruby-identifier">collect</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">key</span>,<span class="ruby-identifier">value</span><span class="ruby-operator">|</span> <span class="ruby-identifier">value</span> } =<span class="ruby-operator">&gt;</span> [ <span class="ruby-value">1</span>, <span class="ruby-value">2.0</span>, :<span class="ruby-identifier">three</span>, <span class="ruby-string">'four'</span> ] <span class="ruby-operator">...</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">nested</span> <span class="ruby-identifier">configuration</span> <span class="ruby-operator">?</span>
179-
180-
<span class="ruby-identifier">inheritance</span>
181-
</pre>
182-
183-
<p>Features</p>
184-
185-
<pre>Per mode
186-
setting value
187-
setting/local = value
188-
existing setting + override
189-
nesting
190-
inherited setting + override
191-
load from string + file, merge + nest
192-
[] and []= methods + self
193-
+ merge
194-
+ defaults
195-
+ blank slate</pre>
96+
<p><a href="Iqeo.html">Iqeo</a> namespace module.</p>
19697

19798
</div><!-- description -->
19899

0 commit comments

Comments
 (0)