configatron 2.3.1 → 2.3.2

data/README

@@ -5,9 +5,10 @@ Configatron makes configuring your applications and scripts incredibly easy. No
 ==Examples
 
 ===Simple
+
   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 # => "me@example.com"
@@ -15,19 +16,19 @@ Now, anywhere in your code you can do the following:
 
 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:
+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 <tt>database_url</tt> option to be <tt>postgres://localhost/mack_framework_rocks</tt>. 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.database_url = "postgres://localhost/mack_framework_rocks_development"
 
-  
 becomes:
 
   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?
 
 ===Hash/YAML
+
 You can configure configatron from a hash as well:
 
   configatron.configure_from_hash({:email => {:pop => {:address => 'pop.example.com', :port => 110}}, :smtp => {:address => 'smtp.example.com'}})
@@ -35,17 +36,15 @@ You can configure configatron from a hash as well:
   configatron.email.pop.address # => 'pop.example.com'
   configatron.email.pop.port # => 110
   # and so on...
-  
+
 Notice how they're all namespaced for your as well. The same holds true for YAML files:
 
   configuration.configure_from_yaml('/path/to/file.yml')
-  
-When the 'reload' method is called on configatron then the YAML file will be re-read in case changes have been made.
 
 ===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.website_url = "http://www.mackframework.com"
   configatron.email.pop.address = "pop.example.com"
   configatron.email.pop.port = 110
@@ -57,7 +56,7 @@ becomes:
   configatron.email.pop.address # => "pop.example.com"
   configatron.email.smtp.address # => "smtp.example.com"
   configatron.website_url # => "http://www.mackframework.com"
-  
+
 Configatron allows you to nest namespaces to your hearts content! Just keep going, it's that easy.
 
 Of course you can update a single parameter n levels deep as well:
@@ -66,21 +65,27 @@ Of course you can update a single parameter n levels deep as well:
   
   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:
+Even if parameters haven't been set, you can still call them, but you'll get a <tt>Configatron::Store</tt> object back. The Configatron::Store class, however, will respond true to <tt>.nil?</tt> if there are no parameters configured on it.
 
   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.i.dont.exist # => Configatron::Store
+
+If you want to get back an actual <tt>nil</tt> then you can use the <tt>retrieve</tt> method:
+
+  configatron.i.do.exist = [:some, :array]
+  configatron.i.dont.retrieve(:exist, nil) # => nil
+  configatron.i.do.retrieve(:exist, :foo) # => [:some, :array]
+
+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 its 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
@@ -98,7 +103,7 @@ Sometimes in testing, or other situations, you want to temporarily change some s
   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
@@ -118,12 +123,14 @@ You can also pass in an optional Hash to the <tt>temp</tt>:
 Enjoy!
 
 ==Contact
-Please mail bugs, suggestions and patches to <bugs@mackframework.com>.
 
-On the web at: http://www.mackframework.com
+Please mail bugs, suggestions and patches to "bugs@mackframework.com":mailto:bugs@mackframework.com
+
+On the web at: "http://www.mackframework.com":http://www.mackframework.com
 
 ==License and Copyright
-Copyright (C) 2008 Mark Bates, http://www.mackframework.com
+
+Copyright (C) 2008 Mark Bates, "http://www.mackframework.com":http://www.mackframework.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

data/doc/classes/Class.html

@@ -0,0 +1,169 @@
+<?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: Class</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">Class</td>
+        </tr>
+        <tr class="top-aligned-row">
+            <td><strong>In:</strong></td>
+            <td>
+                <a href="../files/lib/configatron/core_ext/class_rb.html">
+                lib/configatron/core_ext/class.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">to_configatron</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-M000001" class="method-detail">
+        <a name="M000001"></a>
+
+        <div class="method-heading">
+          <a href="#M000001" class="method-signature">
+          <span class="method-name">to_configatron</span><span class="method-args">(*args)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns access to configuration parameters named after the class.
+</p>
+<p>
+Examples:
+</p>
+<pre>
+  configatron.foo.bar = :bar
+  configatron.a.b.c.d = 'D'
+
+  class Foo
+  end
+
+  module A
+    module B
+      class C
+      end
+    end
+  end
+
+  Foo.to_configatron.bar # =&gt; :bar
+  A::B::C.to_configatron.d # =&gt; 'D'
+</pre>
+          <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/core_ext/class.rb, line 21</span>
+21:   <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">to_configatron</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
+22:     <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">name</span>.<span class="ruby-identifier">to_configatron</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
+23:   <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.html

@@ -0,0 +1,303 @@
+<?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="#M000002">method_missing</a>&nbsp;&nbsp;
+      <a href="#M000003">reset!</a>&nbsp;&nbsp;
+      <a href="#M000004">temp</a>&nbsp;&nbsp;
+      <a href="#M000006">temp_end</a>&nbsp;&nbsp;
+      <a href="#M000005">temp_start</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/LockedNamespace.html" class="link">Configatron::LockedNamespace</a><br />
+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>
+
+
+    <div id="aliases-list">
+      <h3 class="section-bar">External Aliases</h3>
+
+      <div class="name-list">
+                        <table summary="aliases">
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">send</td>
+          <td>-&gt;</td>
+          <td class="context-item-value">send!</td>
+        </tr>
+                        </table>
+      </div>
+    </div>
+
+
+      
+
+
+    <!-- if method_list -->
+    <div id="methods">
+      <h3 class="section-bar">Public Instance methods</h3>
+
+      <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">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('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 14</span>
+14:   <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>)
+15:     <span class="ruby-ivar">@_store</span>[<span class="ruby-ivar">@_namespace</span>.<span class="ruby-identifier">last</span>].<span class="ruby-identifier">send</span>(<span class="ruby-identifier">sym</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
+16:   <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">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('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 19</span>
+19:   <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">reset!</span>
+20:     <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>}
+21:   <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000004" class="method-detail">
+        <a name="M000004"></a>
+
+        <div class="method-heading">
+          <a href="#M000004" 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('M000004-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000004-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/configatron/configatron.rb, line 27</span>
+27:   <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>)
+28:     <span class="ruby-keyword kw">begin</span>
+29:       <span class="ruby-identifier">temp_start</span>(<span class="ruby-identifier">options</span>)
+30:       <span class="ruby-keyword kw">yield</span>
+31:     <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>
+32:       <span class="ruby-identifier">raise</span> <span class="ruby-identifier">e</span>
+33:     <span class="ruby-keyword kw">ensure</span>
+34:       <span class="ruby-identifier">temp_end</span>
+35:     <span class="ruby-keyword kw">end</span>
+36:   <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000006" class="method-detail">
+        <a name="M000006"></a>
+
+        <div class="method-heading">
+          <a href="#M000006" class="method-signature">
+          <span class="method-name">temp_end</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000006-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000006-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/configatron/configatron.rb, line 47</span>
+47:   <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">temp_end</span>
+48:     <span class="ruby-ivar">@_store</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-ivar">@_namespace</span>.<span class="ruby-identifier">pop</span>)
+49:   <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000005" class="method-detail">
+        <a name="M000005"></a>
+
+        <div class="method-heading">
+          <a href="#M000005" class="method-signature">
+          <span class="method-name">temp_start</span><span class="method-args">(options = nil)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000005-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000005-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/configatron/configatron.rb, line 38</span>
+38:   <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">temp_start</span>(<span class="ruby-identifier">options</span> = <span class="ruby-keyword kw">nil</span>)
+39:     <span class="ruby-identifier">n_space</span> = <span class="ruby-identifier">rand</span>
+40:     <span class="ruby-ivar">@_store</span>[<span class="ruby-identifier">n_space</span>] = <span class="ruby-ivar">@_store</span>[<span class="ruby-ivar">@_namespace</span>.<span class="ruby-identifier">last</span>].<span class="ruby-identifier">deep_clone</span>
+41:     <span class="ruby-ivar">@_namespace</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-identifier">n_space</span>
+42:     <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">options</span>
+43:       <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>)
+44:     <span class="ruby-keyword kw">end</span>
+45:   <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>