env_parser 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1074b534666060176bf44c5b5d96c91ebf87f13e
-  data.tar.gz: a4bbaf7ec568cf6fb1a3c8adb75b0ba36e0abfcc
+  metadata.gz: e4e18299d9f60e90144794c743405a7719404e8a
+  data.tar.gz: 57ea9d3762d0e6294600afc8df35968bd290dbd8
 SHA512:
-  metadata.gz: '0778ff18e226b11676ac3ef7b2c0d4ec939ce6ca5a272e5d2ddbfc29827ff29bb1fe96d5028190fa4deec42858a1235de02ca783fa04902c4eca140e62d0ff12'
-  data.tar.gz: 4e11313dca4ee78652b0dbe34af9d47b8bf7a61aa5ed7ebc7d119d8ada62a5b2d4d977caf194e6f88f0d4591e2fc902eaed9bd6ea665faa12fcfc07347cb69ee
+  metadata.gz: dc3918f1dd9be06601fe68826fd891f76081fa424a1607453f2956f09590e469b53029c8c4ad2b541f5619343ef44e132ac784e96e7c028da51bdc73b19ae886
+  data.tar.gz: 34b54cc90f38bfe93994a42e90fd351573476bc503174de330258ffb7c8639c0bc147baaac079e5eff1eaffa5f02b01a6aed75adb41340c4fec90b40976e17c8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    env_parser (0.6.0)
+    env_parser (0.7.0)
       activesupport (>= 5.0.0)
 
 GEM

data/README.md

@@ -1,10 +1,8 @@
-# EnvParser
+# EnvParser  [![Gem Version](https://badge.fury.io/rb/env_parser.svg)](https://badge.fury.io/rb/env_parser)
 
-If your code uses environment variables, you know that `ENV` will always surface these as strings. Interpreting these strings as the value you *actually* want to see/use takes some additional effort, however.
+If your code uses environment variables, you know that `ENV` will always surface these as strings. Interpreting these strings as the value you *actually* want to see/use takes some work, however: for numbers you need to cast with `#to_i`/`#to_f`, for booleans you need to check for a specific value (`ENV['SOME_VAR'] == 'true'`), etc. Maybe you want to set non-trivial defaults (something other than `0` or `''`)? Maybe you only want to allow values from a limited set? ...
 
-If you want a number, you need to cast: `#to_i`/`#to_f`. If you want a boolean, you need to check for a specific value: `ENV['SOME_VAR'] == 'true'`. Maybe you want to set non-trivial defaults (something other than `0` or `''`)? Maybe you only want to allow values from a limited set.
-
-Things can get out of control pretty fast, especially as the number of environment variables in play grows. EnvParser aims to help keep things simple.
+Things can get out of control pretty fast, especially as the number of environment variables in play grows. Tools like [dotenv](https://github.com/bkeepers/dotenv) help to make sure you're loading the correct set of *variables*, but EnvParser makes *the values themselves* usable with a minimum of effort.
 
 
 ## Installation
@@ -122,6 +120,15 @@ EnvParser.parse :SOME_CUSTOM_NETWORK_PORT, as: :integer, from_set: (1..65535), i
 ## And if the value is not allowed...
 ##
 EnvParser.parse :NEGATIVE_NUMBER, as: :integer, from_set: (1..5) ## => raises EnvParser::ValueNotAllowed
+
+
+## The "validated_by" option allows for more complex validation.
+##
+EnvParser.parse :MUST_BE_LOWERCASE, as: :string, validated_by: ->(value) { value == value.downcase }
+
+## ... but a block will also do the trick!
+EnvParser.parse(:MUST_BE_LOWERCASE, as: :string) { |value| value == value.downcase }
+EnvParser.parse(:CONNECTION_RETRIES, as: :integer, &:nonzero?)
 ```
 
 
@@ -182,7 +189,7 @@ ENV.register :SHORT_PI, as: :float ## Your constant is set, my man!
 ## Feature Roadmap / Future Development
 
 Additional features/options coming in the future:
-- A `validator` option that lets you pass in a validator lambda/block for things more complex than what a simple `from_set` can enforce.
+
 - A means to register validation blocks as new "as" types. This will allow for custom "as" types like `:url`, `:email`, etc.
 - ... ?
 

data/docs/EnvParser/ValueNotAllowed.html

@@ -126,7 +126,7 @@ option.</p>
 </div>
 
       <div id="footer">
-  Generated on Sun Dec  3 16:33:44 2017 by
+  Generated on Mon Dec 11 23:37:25 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.11 (ruby-2.4.2).
 </div>

data/docs/EnvParser.html

@@ -130,7 +130,7 @@ different data types.</p>
       <dt id="VERSION-constant" class="">VERSION =
         
       </dt>
-      <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>0.6.0</span><span class='tstring_end'>&#39;</span></span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
+      <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>0.7.0</span><span class='tstring_end'>&#39;</span></span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
     
   </dl>
 
@@ -176,7 +176,7 @@ methods.</p>
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#parse-class_method" title="parse (class method)">.<strong>parse</strong>(value, options = {})  &#x21d2; Object </a>
+      <a href="#parse-class_method" title="parse (class method)">.<strong>parse</strong>(value, options = {}) {|value| ... } &#x21d2; Object </a>
     
 
     
@@ -200,7 +200,7 @@ methods.</p>
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#register-class_method" title="register (class method)">.<strong>register</strong>(name, options = {})  &#x21d2; Object </a>
+      <a href="#register-class_method" title="register (class method)">.<strong>register</strong>(name, options = {}) {|value| ... } &#x21d2; Object </a>
     
 
     
@@ -281,27 +281,27 @@ is equivalent to <a href="'XYZ'">EnvParser.parse(ENV</a>, …)</p>
       <pre class="lines">
 
 
-160
-161
-162
-163
-164
-165
-166
-167
-168
-169
-170
-171
-172</pre>
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/env_parser.rb', line 160</span>
+      <pre class="code"><span class="info file"># File 'lib/env_parser.rb', line 190</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_add_env_bindings'>add_env_bindings</span>
   <span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_instance_eval'>instance_eval</span> <span class='kw'>do</span>
-    <span class='kw'>def</span> <span class='id identifier rubyid_parse'>parse</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
-      <span class='const'><span class='object_link'><a href="" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span><span class='lparen'>(</span><span class='kw'>self</span><span class='lbracket'>[</span><span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span><span class='rparen'>)</span>
+    <span class='kw'>def</span> <span class='id identifier rubyid_parse'>parse</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_validation_block'>validation_block</span><span class='rparen'>)</span>
+      <span class='const'><span class='object_link'><a href="" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span><span class='lparen'>(</span><span class='kw'>self</span><span class='lbracket'>[</span><span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_validation_block'>validation_block</span><span class='rparen'>)</span>
     <span class='kw'>end</span>
 
     <span class='kw'>def</span> <span class='id identifier rubyid_register'>register</span><span class='lparen'>(</span><span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='rparen'>)</span>
@@ -319,7 +319,7 @@ is equivalent to <a href="'XYZ'">EnvParser.parse(ENV</a>, …)</p>
       <div class="method_details ">
   <h3 class="signature " id="parse-class_method">
   
-    .<strong>parse</strong>(value, options = {})  &#x21d2; <tt>Object</tt> 
+    .<strong>parse</strong>(value, options = {}) {|value| ... } &#x21d2; <tt>Object</tt> 
   
 
   
@@ -455,6 +455,30 @@ returned, even if it is not part of the “from_set” list/range.</p>
 only available for scalar values (i.e. not arrays, hashes, or other
 enumerables). An attempt to use the “from_set” option with a non-scalar
 value will raise an ArgumentError exception.</p>
+</div>
+          
+        </li>
+      
+        <li>
+          <span class="name">validated_by</span>
+          <span class="type">(<tt>Proc</tt>)</span>
+          <span class="default">
+            
+          </span>
+          
+            &mdash; <div class='inline'>
+<p>If given, the “validated_by” proc is called with the parsed value (after
+type conversion) as its sole argument. This allows for user-defined
+validation of the parsed value beyond what can be enforced by use of the
+“from_set” option alone. If the proc&#39;s return value is
+<code>#blank?</code>, an EnvParser::ValueNotAllowed exception is raised. To
+accomodate your syntax of choice, this validation proc may be given as a
+yield block instead.</p>
+
+<p>Note that this option is intended to provide an inspection mechanism only –
+no mutation of the parsed value should occur within the given proc. To that
+end, the argument passed is a <em>frozen</em> duplicate of the parsed
+value.</p>
 </div>
           
         </li>
@@ -462,6 +486,28 @@ value will raise an ArgumentError exception.</p>
     </ul>
   
 
+<p class="tag_title">Yields:</p>
+<ul class="yield">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>value</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>A block (if given) is treated exactly as the “validated_by” Proc would.
+Although there is no compelling reason to provide both a “validated_by”
+proc <em>and</em> a validation block, there is no technical limitation
+preventing this. <strong>If both are given, both validation checks must
+pass.</strong></p>
+</div>
+      
+    </li>
+  
+</ul>
 <p class="tag_title">Raises:</p>
 <ul class="raise">
   
@@ -482,32 +528,34 @@ value will raise an ArgumentError exception.</p>
       <pre class="lines">
 
 
-55
-56
-57
-58
-59
-60
-61
-62
-63
-64
-65
-66
-67
-68
-69
-70
-71
 72
 73
 74
-75</pre>
+75
+76
+77
+78
+79
+80
+81
+82
+83
+84
+85
+86
+87
+88
+89
+90
+91
+92
+93
+94</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/env_parser.rb', line 55</span>
+      <pre class="code"><span class="info file"># File 'lib/env_parser.rb', line 72</span>
 
-<span class='kw'>def</span> <span class='id identifier rubyid_parse'>parse</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
+<span class='kw'>def</span> <span class='id identifier rubyid_parse'>parse</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_validation_block'>validation_block</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='const'>ENV</span><span class='lbracket'>[</span><span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='rbracket'>]</span> <span class='kw'>if</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_is_a?'>is_a?</span> <span class='const'>Symbol</span>
   <span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span>
 
@@ -526,6 +574,8 @@ value will raise an ArgumentError exception.</p>
           <span class='kw'>end</span>
 
   <span class='id identifier rubyid_check_for_set_inclusion'>check_for_set_inclusion</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='comma'>,</span> <span class='label'>set:</span> <span class='id identifier rubyid_options'>options</span><span class='lbracket'>[</span><span class='symbol'>:from_set</span><span class='rbracket'>]</span><span class='rparen'>)</span> <span class='kw'>if</span> <span class='id identifier rubyid_options'>options</span><span class='period'>.</span><span class='id identifier rubyid_key?'>key?</span><span class='lparen'>(</span><span class='symbol'>:from_set</span><span class='rparen'>)</span>
+  <span class='id identifier rubyid_check_user_defined_validations'>check_user_defined_validations</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='comma'>,</span> <span class='label'>proc:</span> <span class='id identifier rubyid_options'>options</span><span class='lbracket'>[</span><span class='symbol'>:validated_by</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>block:</span> <span class='id identifier rubyid_validation_block'>validation_block</span><span class='rparen'>)</span>
+
   <span class='id identifier rubyid_value'>value</span>
 <span class='kw'>end</span></pre>
     </td>
@@ -536,7 +586,7 @@ value will raise an ArgumentError exception.</p>
       <div class="method_details ">
   <h3 class="signature " id="register-class_method">
   
-    .<strong>register</strong>(name, options = {})  &#x21d2; <tt>Object</tt> 
+    .<strong>register</strong>(name, options = {}) {|value| ... } &#x21d2; <tt>Object</tt> 
   
 
   
@@ -650,11 +700,12 @@ Kernel (making it a global constant).</p>
           <span class="type">(<tt>Symbol</tt>)</span>
           <span class="default">
             
-              &mdash; default:
-              <tt>See `.parse`</tt>
-            
           </span>
           
+            &mdash; <div class='inline'>
+<p>See <code>.parse</code>.</p>
+</div>
+          
         </li>
       
         <li>
@@ -662,11 +713,12 @@ Kernel (making it a global constant).</p>
           <span class="type">(<tt>Object</tt>)</span>
           <span class="default">
             
-              &mdash; default:
-              <tt>See `.parse`</tt>
-            
           </span>
           
+            &mdash; <div class='inline'>
+<p>See <code>.parse</code>.</p>
+</div>
+          
         </li>
       
         <li>
@@ -674,16 +726,51 @@ Kernel (making it a global constant).</p>
           <span class="type">(<tt>Array</tt>, <tt>Range</tt>)</span>
           <span class="default">
             
-              &mdash; default:
-              <tt>See `.parse`</tt>
+          </span>
+          
+            &mdash; <div class='inline'>
+<p>See <code>.parse</code>.</p>
+</div>
+          
+        </li>
+      
+        <li>
+          <span class="name">validated_by</span>
+          <span class="type">(<tt>Proc</tt>)</span>
+          <span class="default">
             
           </span>
           
+            &mdash; <div class='inline'>
+<p>See <code>.parse</code>.</p>
+</div>
+          
         </li>
       
     </ul>
   
 
+<p class="tag_title">Yields:</p>
+<ul class="yield">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>value</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>A block (if given) is treated exactly as in <code>.parse</code>. Note,
+however, that a single yield block cannot be used to register multiple
+constants simultaneously – each value needing validation must give its own
+“validated_by” proc.</p>
+</div>
+      
+    </li>
+  
+</ul>
 <p class="tag_title">Raises:</p>
 <ul class="raise">
   
@@ -704,45 +791,51 @@ Kernel (making it a global constant).</p>
       <pre class="lines">
 
 
-119
-120
-121
-122
-123
-124
-125
-126
-127
-128
-129
-130
-131
-132
-133
-134
-135
-136
-137
-138
-139
-140
-141
-142
-143
-144
-145
 146
 147
 148
-149</pre>
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/env_parser.rb', line 119</span>
+      <pre class="code"><span class="info file"># File 'lib/env_parser.rb', line 146</span>
 
-<span class='kw'>def</span> <span class='id identifier rubyid_register'>register</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
+<span class='kw'>def</span> <span class='id identifier rubyid_register'>register</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_validation_block'>validation_block</span><span class='rparen'>)</span>
   <span class='comment'>## We want to allow for registering multiple variables simultaneously via a single `.register`
 </span>  <span class='comment'>## method call.
-</span>  <span class='kw'>return</span> <span class='id identifier rubyid_register_all'>register_all</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span> <span class='kw'>if</span> <span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_is_a?'>is_a?</span> <span class='const'>Hash</span>
+</span>  <span class='kw'>if</span> <span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_is_a?'>is_a?</span> <span class='const'>Hash</span>
+    <span class='id identifier rubyid_raise'>raise</span> <span class='const'>ArgumentError</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>cannot register multiple values with one yield block</span><span class='tstring_end'>&#39;</span></span> <span class='kw'>if</span> <span class='id identifier rubyid_block_given?'>block_given?</span>
+    <span class='kw'>return</span> <span class='id identifier rubyid_register_all'>register_all</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span>
+  <span class='kw'>end</span>
 
   <span class='id identifier rubyid_from'>from</span> <span class='op'>=</span> <span class='id identifier rubyid_options'>options</span><span class='period'>.</span><span class='id identifier rubyid_fetch'>fetch</span><span class='lparen'>(</span><span class='symbol'>:from</span><span class='comma'>,</span> <span class='const'>ENV</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_within'>within</span> <span class='op'>=</span> <span class='id identifier rubyid_options'>options</span><span class='period'>.</span><span class='id identifier rubyid_fetch'>fetch</span><span class='lparen'>(</span><span class='symbol'>:within</span><span class='comma'>,</span> <span class='const'>Kernel</span><span class='rparen'>)</span>
@@ -765,7 +858,7 @@ Kernel (making it a global constant).</p>
   <span class='kw'>end</span>
 
   <span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='id identifier rubyid_from'>from</span><span class='lbracket'>[</span><span class='id identifier rubyid_name'>name</span><span class='rbracket'>]</span>
-  <span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='id identifier rubyid_parse'>parse</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span><span class='rparen'>)</span>
+  <span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='id identifier rubyid_parse'>parse</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_validation_block'>validation_block</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_within'>within</span><span class='period'>.</span><span class='id identifier rubyid_const_set'>const_set</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_upcase'>upcase</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span><span class='comma'>,</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_dup'>dup</span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span><span class='rparen'>)</span>
 
   <span class='id identifier rubyid_value'>value</span>
@@ -780,7 +873,7 @@ Kernel (making it a global constant).</p>
 </div>
 
       <div id="footer">
-  Generated on Sun Dec  3 16:33:44 2017 by
+  Generated on Mon Dec 11 23:37:25 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.11 (ruby-2.4.2).
 </div>

data/docs/_index.html

@@ -112,7 +112,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sun Dec  3 16:33:43 2017 by
+  Generated on Mon Dec 11 23:37:25 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.11 (ruby-2.4.2).
 </div>

data/docs/file.README.html

@@ -58,23 +58,22 @@
       </div>
 
       <div id="content"><div id='filecontents'>
-<h1 id="label-EnvParser">EnvParser</h1>
+<h1 id="label-EnvParser+rdoc-image-3Ahttps-3A-2F-2Fbadge.fury.io-2Frb-2Fenv_parser.svg">EnvParser <a href="https://badge.fury.io/rb/env_parser"><img src="https://badge.fury.io/rb/env_parser.svg"></a></h1>
 
 <p>If your code uses environment variables, you know that <code>ENV</code>
 will always surface these as strings. Interpreting these strings as the
-value you <em>actually</em> want to see/use takes some additional effort,
-however.</p>
-
-<p>If you want a number, you need to cast:
-<code>#to_i</code>/<code>#to_f</code>. If you want a boolean, you need to
-check for a specific value: <code>ENV['SOME_VAR'] == &#39;true&#39;</code>.
-Maybe you want to set non-trivial defaults (something other than
-<code>0</code> or <code>&#39;&#39;</code>)? Maybe you only want to allow
-values from a limited set.</p>
+value you <em>actually</em> want to see/use takes some work, however: for
+numbers you need to cast with <code>#to_i</code>/<code>#to_f</code>, for
+booleans you need to check for a specific value (<code>ENV['SOME_VAR'] ==
+&#39;true&#39;</code>), etc. Maybe you want to set non-trivial defaults
+(something other than <code>0</code> or <code>&#39;&#39;</code>)? Maybe you
+only want to allow values from a limited set? …</p>
 
 <p>Things can get out of control pretty fast, especially as the number of
-environment variables in play grows. EnvParser aims to help keep things
-simple.</p>
+environment variables in play grows. Tools like <a
+href="https://github.com/bkeepers/dotenv">dotenv</a> help to make sure
+you&#39;re loading the correct set of <em>variables</em>, but EnvParser
+makes <em>the values themselves</em> usable with a minimum of effort.</p>
 
 <h2 id="label-Installation">Installation</h2>
 
@@ -181,7 +180,16 @@ simple.</p>
 <span class='comment'>## And if the value is not allowed...
 </span><span class='comment'>##
 </span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:NEGATIVE_NUMBER</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>from_set:</span> <span class='lparen'>(</span><span class='int'>1</span><span class='op'>..</span><span class='int'>5</span><span class='rparen'>)</span> <span class='comment'>## =&gt; raises EnvParser::ValueNotAllowed
-</span></code></pre>
+</span>
+
+<span class='comment'>## The &quot;validated_by&quot; option allows for more complex validation.
+</span><span class='comment'>##
+</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='comma'>,</span> <span class='label'>validated_by:</span> <span class='tlambda'>-&gt;</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span> <span class='tlambeg'>{</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
+
+<span class='comment'>## ... but a block will also do the trick!
+</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span><span class='lparen'>(</span><span class='symbol'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_value'>value</span><span class='op'>|</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
+<span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span><span class='lparen'>(</span><span class='symbol'>:CONNECTION_RETRIES</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='symbol'>:nonzero?</span><span class='rparen'>)</span>
+</code></pre>
 
 <h4 id="label-Setting+Constants+From+ENV+Values">Setting Constants From ENV Values</h4>
 
@@ -235,12 +243,13 @@ docs</a> for the full EnvParser documentation.</p>
 
 <h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
 
-<p>Additional features/options coming in the future: - A
-<code>validator</code> option that lets you pass in a validator
-lambda/block for things more complex than what a simple
-<code>from_set</code> can enforce. - A means to register validation blocks
-as new “as” types. This will allow for custom “as” types like
-<code>:url</code>, <code>:email</code>, etc. - … ?</p>
+<p>Additional features/options coming in the future:</p>
+<ul><li>
+<p>A means to register validation blocks as new “as” types. This will allow
+for custom “as” types like <code>:url</code>, <code>:email</code>, etc.</p>
+</li><li>
+<p>… ?</p>
+</li></ul>
 
 <h2 id="label-Contribution+-2F+Development">Contribution / Development</h2>
 
@@ -271,7 +280,7 @@ href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Dec  3 16:33:43 2017 by
+  Generated on Mon Dec 11 23:37:25 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.11 (ruby-2.4.2).
 </div>

data/docs/index.html

@@ -58,23 +58,22 @@
       </div>
 
       <div id="content"><div id='filecontents'>
-<h1 id="label-EnvParser">EnvParser</h1>
+<h1 id="label-EnvParser+rdoc-image-3Ahttps-3A-2F-2Fbadge.fury.io-2Frb-2Fenv_parser.svg">EnvParser <a href="https://badge.fury.io/rb/env_parser"><img src="https://badge.fury.io/rb/env_parser.svg"></a></h1>
 
 <p>If your code uses environment variables, you know that <code>ENV</code>
 will always surface these as strings. Interpreting these strings as the
-value you <em>actually</em> want to see/use takes some additional effort,
-however.</p>
-
-<p>If you want a number, you need to cast:
-<code>#to_i</code>/<code>#to_f</code>. If you want a boolean, you need to
-check for a specific value: <code>ENV['SOME_VAR'] == &#39;true&#39;</code>.
-Maybe you want to set non-trivial defaults (something other than
-<code>0</code> or <code>&#39;&#39;</code>)? Maybe you only want to allow
-values from a limited set.</p>
+value you <em>actually</em> want to see/use takes some work, however: for
+numbers you need to cast with <code>#to_i</code>/<code>#to_f</code>, for
+booleans you need to check for a specific value (<code>ENV['SOME_VAR'] ==
+&#39;true&#39;</code>), etc. Maybe you want to set non-trivial defaults
+(something other than <code>0</code> or <code>&#39;&#39;</code>)? Maybe you
+only want to allow values from a limited set? …</p>
 
 <p>Things can get out of control pretty fast, especially as the number of
-environment variables in play grows. EnvParser aims to help keep things
-simple.</p>
+environment variables in play grows. Tools like <a
+href="https://github.com/bkeepers/dotenv">dotenv</a> help to make sure
+you&#39;re loading the correct set of <em>variables</em>, but EnvParser
+makes <em>the values themselves</em> usable with a minimum of effort.</p>
 
 <h2 id="label-Installation">Installation</h2>
 
@@ -181,7 +180,16 @@ simple.</p>
 <span class='comment'>## And if the value is not allowed...
 </span><span class='comment'>##
 </span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:NEGATIVE_NUMBER</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>from_set:</span> <span class='lparen'>(</span><span class='int'>1</span><span class='op'>..</span><span class='int'>5</span><span class='rparen'>)</span> <span class='comment'>## =&gt; raises EnvParser::ValueNotAllowed
-</span></code></pre>
+</span>
+
+<span class='comment'>## The &quot;validated_by&quot; option allows for more complex validation.
+</span><span class='comment'>##
+</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='comma'>,</span> <span class='label'>validated_by:</span> <span class='tlambda'>-&gt;</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span> <span class='tlambeg'>{</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
+
+<span class='comment'>## ... but a block will also do the trick!
+</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span><span class='lparen'>(</span><span class='symbol'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_value'>value</span><span class='op'>|</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
+<span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span><span class='lparen'>(</span><span class='symbol'>:CONNECTION_RETRIES</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='symbol'>:nonzero?</span><span class='rparen'>)</span>
+</code></pre>
 
 <h4 id="label-Setting+Constants+From+ENV+Values">Setting Constants From ENV Values</h4>
 
@@ -235,12 +243,13 @@ docs</a> for the full EnvParser documentation.</p>
 
 <h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
 
-<p>Additional features/options coming in the future: - A
-<code>validator</code> option that lets you pass in a validator
-lambda/block for things more complex than what a simple
-<code>from_set</code> can enforce. - A means to register validation blocks
-as new “as” types. This will allow for custom “as” types like
-<code>:url</code>, <code>:email</code>, etc. - … ?</p>
+<p>Additional features/options coming in the future:</p>
+<ul><li>
+<p>A means to register validation blocks as new “as” types. This will allow
+for custom “as” types like <code>:url</code>, <code>:email</code>, etc.</p>
+</li><li>
+<p>… ?</p>
+</li></ul>
 
 <h2 id="label-Contribution+-2F+Development">Contribution / Development</h2>
 
@@ -271,7 +280,7 @@ href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Dec  3 16:33:43 2017 by
+  Generated on Mon Dec 11 23:37:25 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.11 (ruby-2.4.2).
 </div>

data/docs/top-level-namespace.html

@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sun Dec  3 16:33:43 2017 by
+  Generated on Mon Dec 11 23:37:25 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.11 (ruby-2.4.2).
 </div>

data/lib/env_parser/version.rb

@@ -1,3 +1,3 @@
 class EnvParser
-  VERSION = '0.6.0'.freeze
+  VERSION = '0.7.0'.freeze
 end

data/lib/env_parser.rb

@@ -50,9 +50,26 @@ class EnvParser
     ##   for scalar values (i.e. not arrays, hashes, or other enumerables). An attempt to use the
     ##   "from_set" option with a non-scalar value will raise an ArgumentError exception.
     ##
+    ## @option options validated_by [Proc]
+    ##   If given, the "validated_by" proc is called with the parsed value (after type conversion)
+    ##   as its sole argument. This allows for user-defined validation of the parsed value beyond
+    ##   what can be enforced by use of the "from_set" option alone. If the proc's return value is
+    ##   `#blank?`, an EnvParser::ValueNotAllowed exception is raised. To accomodate your syntax of
+    ##   choice, this validation proc may be given as a yield block instead.
+    ##
+    ##   Note that this option is intended to provide an inspection mechanism only -- no mutation
+    ##   of the parsed value should occur within the given proc. To that end, the argument passed is
+    ##   a *frozen* duplicate of the parsed value.
+    ##
+    ## @yield [value]
+    ##   A block (if given) is treated exactly as the "validated_by" Proc would. Although there is
+    ##   no compelling reason to provide both a "validated_by" proc *and* a validation block, there
+    ##   is no technical limitation preventing this. **If both are given, both validation checks
+    ##   must pass.**
+    ##
     ## @raise [ArgumentError, EnvParser::ValueNotAllowed]
     ##
-    def parse(value, options = {})
+    def parse(value, options = {}, &validation_block)
       value = ENV[value.to_s] if value.is_a? Symbol
       value = value.to_s
 
@@ -71,6 +88,8 @@ class EnvParser
               end
 
       check_for_set_inclusion(value, set: options[:from_set]) if options.key?(:from_set)
+      check_user_defined_validations(value, proc: options[:validated_by], block: validation_block)
+
       value
     end
 
@@ -106,20 +125,31 @@ class EnvParser
     ##   a global constant).
     ##
     ## @option options as [Symbol]
-    ##   (See `.parse`)
+    ##   See `.parse`.
     ##
     ## @option options if_unset
-    ##   (See `.parse`)
+    ##   See `.parse`.
     ##
     ## @option options from_set [Array, Range]
-    ##   (See `.parse`)
+    ##   See `.parse`.
+    ##
+    ## @option options validated_by [Proc]
+    ##   See `.parse`.
+    ##
+    ## @yield [value]
+    ##   A block (if given) is treated exactly as in `.parse`. Note, however, that a single yield
+    ##   block cannot be used to register multiple constants simultaneously -- each value needing
+    ##   validation must give its own "validated_by" proc.
     ##
     ## @raise [ArgumentError]
     ##
-    def register(name, options = {})
+    def register(name, options = {}, &validation_block)
       ## We want to allow for registering multiple variables simultaneously via a single `.register`
       ## method call.
-      return register_all(name) if name.is_a? Hash
+      if name.is_a? Hash
+        raise ArgumentError, 'cannot register multiple values with one yield block' if block_given?
+        return register_all(name)
+      end
 
       from = options.fetch(:from, ENV)
       within = options.fetch(:within, Kernel)
@@ -142,7 +172,7 @@ class EnvParser
       end
 
       value = from[name]
-      value = parse(value, options)
+      value = parse(value, options, &validation_block)
       within.const_set(name.upcase.to_sym, value.dup.freeze)
 
       value
@@ -159,8 +189,8 @@ class EnvParser
     ##
     def add_env_bindings
       ENV.instance_eval do
-        def parse(name, options = {})
-          EnvParser.parse(self[name.to_s], options)
+        def parse(name, options = {}, &validation_block)
+          EnvParser.parse(self[name.to_s], options, &validation_block)
         end
 
         def register(*args)
@@ -226,7 +256,6 @@ class EnvParser
     ## Verifies that the given "value" is included in the "set".
     ##
     ## @param value
-    ##
     ## @param set [Array, Range]
     ##
     ## @return [nil]
@@ -248,6 +277,25 @@ class EnvParser
       nil
     end
 
+    ## Verifies that the given "value" passes both the "proc" and "block" validations.
+    ##
+    ## @param value
+    ## @param proc [Proc, nil]
+    ## @param block [Proc, nil]
+    ##
+    ## @return [nil]
+    ##   This generates no usable value.
+    ##
+    ## @raise [EnvParser::ValueNotAllowed]
+    ##
+    def check_user_defined_validations(value, proc: nil, block: nil)
+      immutable_value = value.dup.freeze
+      error = 'parsed value failed user validation'
+      raise ValueNotAllowed, error unless [proc, block].compact.all? { |i| i.call(immutable_value) }
+
+      nil
+    end
+
     ## Receives a list of "register" calls to make, as a Hash keyed with variable names and the
     ## values being each "register" call's option set.
     ##

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: env_parser
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Nestor Custodio
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-03 00:00:00.000000000 Z
+date: 2017-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler