configatron 1.2.2 → 2.0.0

data/README

@@ -5,28 +5,24 @@ Configatron makes configuring your applications and scripts incredibly easy. No
 ==Examples
 
 ===Simple
-  configatron do |config|
-    config.email = "mark@mackframework.com"
-    config.database_url = "postgres://localhost/mack_framework_rocks"
-    # etc...
-  end
+  configatron.email = 'me@example.com'
+  configatron.database_url = "postgres://localhost/mack_framework_rocks"
   
 Now, anywhere in your code you can do the following:
 
-  configatron.email # => "mark@mackframework.com"
+  configatron.email # => "me@example.com"
   configatron.database_url # => "postgres://localhost/mack_framework_rocks"
 
 Viola! Simple as can be.
 
 Now you're saying, what if I want to have a 'default' set of options, but then override them later, based on other information? Simple again. Let's use our above example. We've configured our 'database_url' option to be "postgres://localhost/mack_framework_rocks". The problem with that is that is our production database url, not our development url. Fair enough, all you have to do is redeclare it:
 
-  configatron do |config|
-    config.database_url = "postgres://localhost/mack_framework_rocks_development"
-  end
+  configatron.database_url = "postgres://localhost/mack_framework_rocks_development"
+
   
 becomes:
 
-  configatron.email # => "mark@mackframework.com"
+  configatron.email # => "me@example.com"
   configatron.database_url # => "postgres://localhost/mack_framework_rocks_development"
   
 Notice how our other configuration parameters haven't changed? Cool, eh?
@@ -49,23 +45,12 @@ When the 'reload' method is called on configatron then the YAML file will be re-
 ===Namespaces
 
 The question that should be on your lips is what I need to have namespaced configuration parameters. It's easy! Configatron allows you to create namespaces.
-
-  configatron do |config|
-    config.website_url = "http://www.mackframework.com"
-    config.namespace(:email) do |email|
-      email.namespace(:pop) do |pop|
-        pop.address = "pop.example.com"
-        pop.port = "110"
-        # etc ...
-      end
-      email.namespace(:smtp) do |smtp|
-        smtp.address = "smtp.example.com"
-        smtp.port = "25"
-        # etc ...
-      end
-    end
-    # etc...
-  end
+  
+  configatron.website_url = "http://www.mackframework.com"
+  configatron.email.pop.address = "pop.example.com"
+  configatron.email.pop.port = 110
+  configatron.email.smtp.address = "smtp.example.com"
+  configatron.email.smtp.port = 25
 
 becomes:
 
@@ -77,16 +62,58 @@ Configatron allows you to nest namespaces to your hearts content! Just keep goin
 
 Of course you can update a single parameter n levels deep as well:
 
-  configatron do |config|
-    config.namespace(:email) do |email|
-      email.namespace(:pop) do |pop|
-        pop.address = "pop2.example.com"
-      end
-    end
-  end
+  configatron.email.pop.address = "pop2.example.com"
   
   configatron.email.pop.address # => "pop2.example.com"
   configatron.email.smtp.address # => "smtp.example.com"
+  
+===Misc.
+
+Even if parameters haven't been set, you can still call them, and you'll get nil back:
+
+  configatron.i.dont.exist.nil? # => true
+  configatron.i.dont.exist # => nil
+  
+You can set 'default' values for parameters. If there is already a setting, it won't be replaced. This is useful if you've already done your 'configuration' and you call a library, that needs to have parameters set. The library can set it's defaults, without worrying that it might have overridden your custom settings.
+
+  configatron.set_default(:name, 'Mark Bates')
+  configatron.name # => 'Mark Bates'
+  configatron.set_default(:name, 'Me')
+  configatron.name # => 'Mark Bates'
+  
+Sometimes in testing, or other situations, you want to temporarily change some settings. You can do this with the <tt>temp</tt> method:
+
+  configatron.one = 1
+  configatron.letters.a = 'A'
+  configatron.letters.b = 'B'
+  configatron.temp do
+    configatron.letters.b = 'bb'
+    configatron.letters.c = 'c'
+    configatron.one # => 1
+    configatron.letters.a # => 'A'
+    configatron.letters.b # => 'bb'
+    configatron.letters.c # => 'c'
+  end
+  configatron.one # => 1
+  configatron.letters.a # => 'A'
+  configatron.letters.b # => 'B'
+  configatron.letters.c # => nil
+  
+You can also pass in an optional Hash to the <tt>temp</tt>:
+
+  configatron.one = 1
+  configatron.letters.a = 'A'
+  configatron.letters.b = 'B'
+  configatron.temp(:letters => {:b => 'bb', :c => 'c'}) do
+    configatron.one == 1
+    configatron.letters.a # => 'A'
+    configatron.letters.b # => 'bb'
+    configatron.letters.c # => 'c'
+  end
+  configatron.one == 1
+  configatron.letters.a # => 'A'
+  configatron.letters.b # => 'B'
+  configatron.letters.c # => nil
 
 Enjoy!
 

data/doc/classes/Configatron.html

@@ -0,0 +1,241 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html 
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Class: Configatron</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <meta http-equiv="Content-Script-Type" content="text/javascript" />
+  <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript">
+  // <![CDATA[
+
+  function popupCode( url ) {
+    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+
+  function toggleCode( id ) {
+    if ( document.getElementById )
+      elem = document.getElementById( id );
+    else if ( document.all )
+      elem = eval( "document.all." + id );
+    else
+      return false;
+
+    elemStyle = elem.style;
+    
+    if ( elemStyle.display != "block" ) {
+      elemStyle.display = "block"
+    } else {
+      elemStyle.display = "none"
+    }
+
+    return true;
+  }
+  
+  // Make codeblocks hidden by default
+  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+  
+  // ]]>
+  </script>
+
+</head>
+<body>
+
+
+
+    <div id="classHeader">
+        <table class="header-table">
+        <tr class="top-aligned-row">
+          <td><strong>Class</strong></td>
+          <td class="class-name-in-header">Configatron</td>
+        </tr>
+        <tr class="top-aligned-row">
+            <td><strong>In:</strong></td>
+            <td>
+                <a href="../files/lib/configatron/configatron_rb.html">
+                lib/configatron/configatron.rb
+                </a>
+        <br />
+                <a href="../files/lib/configatron/errors_rb.html">
+                lib/configatron/errors.rb
+                </a>
+        <br />
+                <a href="../files/lib/configatron/store_rb.html">
+                lib/configatron/store.rb
+                </a>
+        <br />
+            </td>
+        </tr>
+
+        <tr class="top-aligned-row">
+            <td><strong>Parent:</strong></td>
+            <td>
+                Object
+            </td>
+        </tr>
+        </table>
+    </div>
+  <!-- banner header -->
+
+  <div id="bodyContent">
+
+
+
+  <div id="contextContent">
+
+
+
+   </div>
+
+    <div id="method-list">
+      <h3 class="section-bar">Methods</h3>
+
+      <div class="name-list">
+      <a href="#M000001">method_missing</a>&nbsp;&nbsp;
+      <a href="#M000002">reset!</a>&nbsp;&nbsp;
+      <a href="#M000003">temp</a>&nbsp;&nbsp;
+      </div>
+    </div>
+
+  </div>
+
+
+    <!-- if includes -->
+    <div id="includes">
+      <h3 class="section-bar">Included Modules</h3>
+
+      <div id="includes-list">
+        <span class="include-name">Singleton</span>
+      </div>
+    </div>
+
+    <div id="section">
+
+    <div id="class-list">
+      <h3 class="section-bar">Classes and Modules</h3>
+
+      Class <a href="Configatron/ProtectedParameter.html" class="link">Configatron::ProtectedParameter</a><br />
+Class <a href="Configatron/Store.html" class="link">Configatron::Store</a><br />
+
+    </div>
+
+
+
+
+      
+
+
+    <!-- if method_list -->
+    <div id="methods">
+      <h3 class="section-bar">Public Instance methods</h3>
+
+      <div id="method-M000001" class="method-detail">
+        <a name="M000001"></a>
+
+        <div class="method-heading">
+          <a href="#M000001" class="method-signature">
+          <span class="method-name">method_missing</span><span class="method-args">(sym, *args)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Forwards the method call onto the &#8216;namespaced&#8217; <a
+href="Configatron/Store.html">Configatron::Store</a>
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000001-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000001-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/configatron/configatron.rb, line 12</span>
+12:   <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">method_missing</span>(<span class="ruby-identifier">sym</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
+13:     <span class="ruby-ivar">@_store</span>[<span class="ruby-ivar">@_namespace</span>].<span class="ruby-identifier">send</span>(<span class="ruby-identifier">sym</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
+14:   <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000002" class="method-detail">
+        <a name="M000002"></a>
+
+        <div class="method-heading">
+          <a href="#M000002" class="method-signature">
+          <span class="method-name">reset!</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Removes ALL configuration parameters
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000002-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000002-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/configatron/configatron.rb, line 17</span>
+17:   <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">reset!</span>
+18:     <span class="ruby-ivar">@_store</span> = {<span class="ruby-identifier">:default</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-constant">Configatron</span><span class="ruby-operator">::</span><span class="ruby-constant">Store</span>.<span class="ruby-identifier">new</span>}
+19:   <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000003" class="method-detail">
+        <a name="M000003"></a>
+
+        <div class="method-heading">
+          <a href="#M000003" class="method-signature">
+          <span class="method-name">temp</span><span class="method-args">(options = nil) {|| ...}</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Allows for the temporary overriding of parameters in a block. Takes an
+optional Hash of parameters that will be applied before the block gets
+called. At the end of the block, the temporary settings are deleted and the
+original settings are reinstated.
+</p>
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000003-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000003-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/configatron/configatron.rb, line 25</span>
+25:   <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">temp</span>(<span class="ruby-identifier">options</span> = <span class="ruby-keyword kw">nil</span>)
+26:     <span class="ruby-ivar">@_namespace</span> = <span class="ruby-identifier">rand</span>
+27:     <span class="ruby-ivar">@_store</span>[<span class="ruby-ivar">@_namespace</span>] = <span class="ruby-ivar">@_store</span>[<span class="ruby-identifier">:default</span>].<span class="ruby-identifier">deep_clone</span> 
+28:     <span class="ruby-keyword kw">begin</span>
+29:       <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">options</span>
+30:         <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">method_missing</span>(<span class="ruby-identifier">:configure_from_hash</span>, <span class="ruby-identifier">options</span>)
+31:       <span class="ruby-keyword kw">end</span>
+32:       <span class="ruby-keyword kw">yield</span>
+33:     <span class="ruby-keyword kw">rescue</span> <span class="ruby-constant">Exception</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">e</span>
+34:       <span class="ruby-identifier">raise</span> <span class="ruby-identifier">e</span>
+35:     <span class="ruby-keyword kw">ensure</span>
+36:       <span class="ruby-ivar">@_store</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-ivar">@_namespace</span>)
+37:       <span class="ruby-ivar">@_namespace</span> = <span class="ruby-identifier">:default</span>
+38:     <span class="ruby-keyword kw">end</span>
+39:   <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+
+    </div>
+
+
+  </div>
+
+
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+
+</body>
+</html>

data/doc/classes/Configatron/ProtectedParameter.html

@@ -0,0 +1,146 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html 
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Class: Configatron::ProtectedParameter</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <meta http-equiv="Content-Script-Type" content="text/javascript" />
+  <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript">
+  // <![CDATA[
+
+  function popupCode( url ) {
+    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+
+  function toggleCode( id ) {
+    if ( document.getElementById )
+      elem = document.getElementById( id );
+    else if ( document.all )
+      elem = eval( "document.all." + id );
+    else
+      return false;
+
+    elemStyle = elem.style;
+    
+    if ( elemStyle.display != "block" ) {
+      elemStyle.display = "block"
+    } else {
+      elemStyle.display = "none"
+    }
+
+    return true;
+  }
+  
+  // Make codeblocks hidden by default
+  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+  
+  // ]]>
+  </script>
+
+</head>
+<body>
+
+
+
+    <div id="classHeader">
+        <table class="header-table">
+        <tr class="top-aligned-row">
+          <td><strong>Class</strong></td>
+          <td class="class-name-in-header">Configatron::ProtectedParameter</td>
+        </tr>
+        <tr class="top-aligned-row">
+            <td><strong>In:</strong></td>
+            <td>
+                <a href="../../files/lib/configatron/errors_rb.html">
+                lib/configatron/errors.rb
+                </a>
+        <br />
+            </td>
+        </tr>
+
+        <tr class="top-aligned-row">
+            <td><strong>Parent:</strong></td>
+            <td>
+                StandardError
+            </td>
+        </tr>
+        </table>
+    </div>
+  <!-- banner header -->
+
+  <div id="bodyContent">
+
+
+
+  <div id="contextContent">
+
+
+
+   </div>
+
+    <div id="method-list">
+      <h3 class="section-bar">Methods</h3>
+
+      <div class="name-list">
+      <a href="#M000014">intialize</a>&nbsp;&nbsp;
+      </div>
+    </div>
+
+  </div>
+
+
+    <!-- if includes -->
+
+    <div id="section">
+
+
+
+
+
+      
+
+
+    <!-- if method_list -->
+    <div id="methods">
+      <h3 class="section-bar">Public Instance methods</h3>
+
+      <div id="method-M000014" class="method-detail">
+        <a name="M000014"></a>
+
+        <div class="method-heading">
+          <a href="#M000014" class="method-signature">
+          <span class="method-name">intialize</span><span class="method-args">(name)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000014-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000014-source">
+<pre>
+   <span class="ruby-comment cmt"># File lib/configatron/errors.rb, line 3</span>
+3:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">intialize</span>(<span class="ruby-identifier">name</span>)
+4:       <span class="ruby-keyword kw">super</span>(<span class="ruby-node">&quot;Can not modify protected parameter: '#{name}'&quot;</span>)
+5:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+
+    </div>
+
+
+  </div>
+
+
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+
+</body>
+</html>