env_parser 1.6.0 → 1.6.2

data/docs/file.README.html

@@ -6,7 +6,7 @@
 <title>
   File: README
   
-    &mdash; Documentation by YARD 0.9.28
+    &mdash; Documentation by YARD 0.9.37
   
 </title>
 
@@ -58,7 +58,7 @@
       </div>
 
       <div id="content"><div id='filecontents'><p><a href="https://rubygems.org/gems/env_parser"><img src="https://img.shields.io/github/v/release/nestor-custodio/env_parser?color=green&amp;label=gem%20version" alt="Gem Version" /></a>
-<a href="https://github.com/nestor-custodio/env_parser/blob/main/LICENSE.txt"><img src="https://img.shields.io/github/license/nestor-custodio/env_parser" alt="MIT License" /></a></p>
+<a href="https://tldrlegal.com/license/mit-license"><img src="https://img.shields.io/github/license/nestor-custodio/env_parser" alt="MIT License" /></a></p>
 
 <h1 id="envparser">EnvParser</h1>
 
@@ -76,13 +76,13 @@
       <li>
         <p>Add one of the following to your application’s Gemfile:
 ```ruby
-## For on-demand usage …
-##
+# For on-demand usage …
+#
 gem ‘env_parser’</p>
 
-        <h2 id="to-automatically-register-env">To automatically register ENV</h2>
-        <p>## constants per “.env_parser.yml” …
-##
+        <h1 id="to-automatically-register-env">To automatically register ENV</h1>
+        <p># constants per “.env_parser.yml” …
+#
 gem ‘env_parser’, require: ‘env_parser/autoregister’
 ```</p>
       </li>
@@ -103,33 +103,34 @@ $ gem install env_parser
 <h2 id="syntax-cheat-sheet">Syntax Cheat Sheet</h2>
 
 <p>```ruby
-## Returns an ENV value parsed “as” a specific type:
-##
-EnvParser.parse env_key_as_a_symbol
-                as: …                          ## ➜ required
-                if_unset: …                    ## ➜ optional; default value
-                from_set: …                    ## ➜ optional; an Array or Range
-                validated_by: -&gt;(value) { … }  ## ➜ optional; may also be given as a block</p>
-
-<h2 id="parse-an-env-value-and-register-it-as-a-constant">Parse an ENV value and register it as a constant:</h2>
-<p>##
-EnvParser.register env_key_as_a_symbol
-                   as: …                          ## ➜ required
-                   within: …                      ## ➜ optional; Class or Module
-                   if_unset: …                    ## ➜ optional; default value
-                   from_set: …                    ## ➜ optional; an Array or Range
-                   validated_by: -&gt;(value) { … }  ## ➜ optional; may also be given as a block</p>
-
-<h2 id="registers-all-env-variables-as-speced-in-envparseryml">Registers all ENV variables as spec’ed in “.env_parser.yml”:</h2>
-<p>##
-EnvParser.autoregister  ## Note this is automatically called if your
-                        ## Gemfile included the “env_parser” gem with
-                        ## the “require: ‘env_parser/autoregister’” option.</p>
-
-<h2 id="lets-you-call-parse-and-register-on-env-itself">Lets you call “parse” and “register” on ENV itself:</h2>
-<p>##
-EnvParser.add_env_bindings  ## ENV.parse will now be a proxy for EnvParser.parse
-                            ## and ENV.register will now be a proxy for EnvParser.register
+# Returns an ENV value parsed “as” a specific type:
+#
+EnvParser.parse env_key_as_a_symbol,
+                as: …,                         # ➜ required; Symbol
+                if_unset: …,                   # ➜ optional; default value (of any type)
+                from_set: …,                   # ➜ optional; Array or Range
+                validated_by: -&gt;(value) { … }  # ➜ optional; may also be given as a block</p>
+
+<h1 id="parse-an-env-value-and-register-it-as-a-constant">Parse an ENV value and register it as a constant:</h1>
+<p>#
+EnvParser.register env_key_as_a_symbol,
+                   as: …,                         # ➜ required; Symbol
+                   named: …,                      # ➜ optional; String or Symbol; available only if <code>within</code> is also given
+                   within: …,                     # ➜ optional; Class or Module
+                   if_unset: …,                   # ➜ optional; default value (of any type)
+                   from_set: …,                   # ➜ optional; Array or Range
+                   validated_by: -&gt;(value) { … }  # ➜ optional; may also be given as a block</p>
+
+<h1 id="registers-all-env-variables-as-speced-in-envparseryml">Registers all ENV variables as spec’ed in “.env_parser.yml”:</h1>
+<p>#
+EnvParser.autoregister  # Note this is automatically called if your
+                        # Gemfile included the “env_parser” gem with
+                        # the “require: ‘env_parser/autoregister’” option.</p>
+
+<h1 id="lets-you-call-parse-and-register-on-env-itself">Lets you call “parse” and “register” on ENV itself:</h1>
+<p>#
+EnvParser.add_env_bindings  # ENV.parse will now be a proxy for EnvParser.parse
+                            # and ENV.register will now be a proxy for EnvParser.register
 ```</p>
 
 <h2 id="extended-how-to-use">Extended How-To-Use</h2>
@@ -143,9 +144,9 @@ EnvParser.add_env_bindings  ## ENV.parse will now be a proxy for EnvParser.parse
     <p>At its core, EnvParser is a straight-forward parser for string values (since that’s all <code>ENV</code> ever gives you), allowing you to read a given string <strong><em>as</em></strong> a variety of types.</p>
 
     <p><code>ruby
-## Returns ENV['TIMEOUT_MS'] as an Integer,
-## or a sensible default (0) if ENV['TIMEOUT_MS'] is unset.
-##
+# Returns ENV['TIMEOUT_MS'] as an Integer,
+# or a sensible default (0) if ENV['TIMEOUT_MS'] is unset.
+#
 timeout_ms = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
 </code></p>
 
@@ -157,9 +158,9 @@ timeout_ms = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
     <p>EnvParser is all about ~~simplification~~ ~~less typing~~ <em>laziness</em>. If you pass in a symbol instead of a string, EnvParser will look to <code>ENV</code> and use the value from the corresponding (string) key.</p>
 
     <p><code>ruby
-## YAY, LESS TYPING!  😃
-## These two are the same:
-##
+# YAY, LESS TYPING!  😃
+# These two are the same:
+#
 more_typing = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
 less_typing = EnvParser.parse :TIMEOUT_MS, as: :integer
 </code></p>
@@ -170,20 +171,32 @@ less_typing = EnvParser.parse :TIMEOUT_MS, as: :integer
     <p>The <code>EnvParser.register</code> method lets you “promote” <code>ENV</code> variables into their own constants, already parsed into the correct type.</p>
 
     <p>```ruby
-ENV[‘API_KEY’]  ## =&gt; ‘unbreakable p4$$w0rd’</p>
+ENV[‘API_KEY’]  # =&gt; ‘unbreakable p4$$w0rd’</p>
 
     <p>EnvParser.register :API_KEY, as: :string
-API_KEY  ## =&gt; ‘unbreakable p4$$w0rd’
+API_KEY  # =&gt; ‘unbreakable p4$$w0rd’
 ```</p>
 
     <p>By default, <code>EnvParser.register</code> will create the requested constant within the Kernel module (making it available everywhere), but you can specify any class or module you like.</p>
 
     <p>```ruby
-ENV[‘BEST_VIDEO’]  ## =&gt; ‘https://youtu.be/L_jWHffIx5E’</p>
+ENV[‘BEST_VIDEO’]  # =&gt; ‘https://youtu.be/L_jWHffIx5E’</p>
 
     <p>EnvParser.register :BEST_VIDEO, as: :string, within: URI
-URI::BEST_VIDEO  ## =&gt; ‘https://youtu.be/L_jWHffIx5E’
-BEST_VIDEO  ## =&gt; raises NameError
+URI::BEST_VIDEO  # =&gt; ‘https://youtu.be/L_jWHffIx5E’
+BEST_VIDEO  # =&gt; raises NameError
+```</p>
+
+    <p><code>EnvParser.register</code>’s <strong><em>within</em></strong> option also allows for specifying what you would like the registered constant to be <strong><em>named</em></strong>, since related ENV variables will tend to have redundant names once namespaced within a single class or module. Note that <code>named</code> is only available when used alongside <code>within</code>, as it exists solely as a namespacing aid; registering ENV variables as <em>global</em> constants with different names would be a debugging nightmare.</p>
+
+    <p>```ruby
+ENV[‘CUSTOM_CLIENT_DEFAULT_HOSTNAME’]  # =&gt; ‘localhost’
+ENV[‘CUSTOM_CLIENT_DEFAULT_PORT’    ]  # =&gt; ‘3000’</p>
+
+    <p>EnvParser.register :CUSTOM_CLIENT_DEFAULT_HOSTNAME, as: :string , named: :DEFAULT_HOSTNAME, within: CustomClient
+EnvParser.register :CUSTOM_CLIENT_DEFAULT_PORT    , as: :integer, named: :DEFAULT_PORT    , within: CustomClient
+CustomClient::DEFAULT_HOSTNAME  # =&gt; ‘localhost’
+CustomClient::DEFAULT_PORT      # =&gt; 3000
 ```</p>
 
     <p>You can also register multiple constants with a single call, which is a bit cleaner.</p>
@@ -193,7 +206,7 @@ EnvParser.register :USERNAME, as: :string
 EnvParser.register :PASSWORD, as: :string
 EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
 
-    <h2 id="is-equivalent-to-">… is equivalent to …</h2>
+    <h1 id="is-equivalent-to-">… is equivalent to …</h1>
 
     <p>EnvParser.register USERNAME: { as: :string                           },
                    PASSWORD: { as: :string                           },
@@ -206,31 +219,31 @@ EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
     <p>Calling <code>EnvParser.add_env_bindings</code> binds proxy <code>parse</code> and <code>register</code> methods onto <code>ENV</code>. With these bindings in place, you can call <code>parse</code> or <code>register</code> on <code>ENV</code> itself, which is more legible and feels more straight-forward.</p>
 
     <p>```ruby
-ENV[‘SHORT_PI’]  ## =&gt; ‘3.1415926’
-ENV[‘BETTER_PI’]  ## =&gt; ‘[“flaky crust”, “strawberry filling”]’</p>
+ENV[‘SHORT_PI’]  # =&gt; ‘3.1415926’
+ENV[‘BETTER_PI’]  # =&gt; ‘[“flaky crust”, “strawberry filling”]’</p>
 
-    <h2 id="bind-the-proxy-methods">Bind the proxy methods.</h2>
-    <p>##
+    <h1 id="bind-the-proxy-methods">Bind the proxy methods.</h1>
+    <p>#
 EnvParser.add_env_bindings</p>
 
-    <p>ENV.parse :SHORT_PI, as: :float  ## =&gt; 3.1415926
-ENV.register :BETTER_PI, as: :array  ## Your constant is set!
+    <p>ENV.parse :SHORT_PI, as: :float  # =&gt; 3.1415926
+ENV.register :BETTER_PI, as: :array  # Your constant is set!
 ```</p>
 
     <p>Note that the proxy <code>ENV.parse</code> method will (naturally) <em>always</em> interpret the value given as an <code>ENV</code> key (converting it to a string, if necessary), which is slightly different from the original <code>EnvParser.parse</code> method.</p>
 
     <p>```ruby
-ENV[‘SHORT_PI’]  ## =&gt; ‘3.1415926’</p>
+ENV[‘SHORT_PI’]  # =&gt; ‘3.1415926’</p>
 
-    <p>EnvParser.parse ‘SHORT_PI’, as: :float  ## =&gt; ‘SHORT_PI’ as a float: 0.0
-EnvParser.parse :SHORT_PI , as: :float  ## =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926</p>
+    <p>EnvParser.parse ‘SHORT_PI’, as: :float  # =&gt; ‘SHORT_PI’ as a float: 0.0
+EnvParser.parse :SHORT_PI , as: :float  # =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926</p>
 
-    <h2 id="bind-the-proxy-methods-1">Bind the proxy methods.</h2>
-    <p>##
+    <h1 id="bind-the-proxy-methods-1">Bind the proxy methods.</h1>
+    <p>#
 EnvParser.add_env_bindings</p>
 
-    <p>ENV.parse ‘SHORT_PI’, as: :float  ## =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926
-ENV.parse :SHORT_PI , as: :float  ## =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926
+    <p>ENV.parse ‘SHORT_PI’, as: :float  # =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926
+ENV.parse :SHORT_PI , as: :float  # =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926
 ```</p>
 
     <p>Note also that the <code>ENV.parse</code> and <code>ENV.register</code> binding is done safely and without polluting the method space for other objects.</p>
@@ -248,14 +261,14 @@ ENV.parse :SHORT_PI , as: :float  ## =&gt; ENV[‘SHORT_PI’] as a float: 3.141
     <p>If the <code>ENV</code> variable you want is unset (<code>nil</code>) or blank (<code>''</code>), the return value is a sensible default for the given <strong><em>as</em></strong> type: 0 or 0.0 for numbers, an empty string/array/hash, etc. Sometimes you want a non-trivial default, however. The <strong><em>if_unset</em></strong> option lets you specify a default that better meets your needs.</p>
 
     <p><code>ruby
-ENV.parse :MISSING_VAR, as: :integer  ## =&gt; 0
-ENV.parse :MISSING_VAR, as: :integer, if_unset: 250  ## =&gt; 250
+ENV.parse :MISSING_VAR, as: :integer  # =&gt; 0
+ENV.parse :MISSING_VAR, as: :integer, if_unset: 250  # =&gt; 250
 </code></p>
 
-    <p>Note these default values are used as-is with no type conversion, so exercise caution.</p>
+    <p>Note these default values are used as-is, with no type conversion (because sometimes you just want <code>nil</code> 🤷), so exercise caution.</p>
 
     <p><code>ruby
-ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!'  ## =&gt; 'Careful!' (NOT AN INTEGER)
+ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!'  # =&gt; 'Careful!' (NOT AN INTEGER)
 </code></p>
   </li>
   <li>
@@ -267,23 +280,23 @@ ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!'  ## =&gt; 'Careful!'
 ENV.parse :API_TO_USE, as: :symbol, from_set: %i[internal external]
 ENV.parse :NETWORK_PORT, as: :integer, from_set: (1..65535), if_unset: 80</p>
 
-    <h2 id="and-if-the-value-is-not-in-the-allowed-set-">And if the value is not in the allowed set …</h2>
-    <p>##
-ENV.parse :TWELVE, as: :integer, from_set: (1..5)  ## =&gt; raises EnvParser::ValueNotAllowedError
+    <h1 id="and-if-the-value-is-not-in-the-allowed-set-">And if the value is not in the allowed set …</h1>
+    <p>#
+ENV.parse :TWELVE, as: :integer, from_set: (1..5)  # =&gt; raises EnvParser::ValueNotAllowedError
 ```</p>
   </li>
   <li>
     <p><strong>Custom Validation Of Parsed Values</strong></p>
 
-    <p>You can write your own, more complex validations by passing in a <strong><em>validated_by</em></strong> lambda or an equivalent block. The lambda/block should take one value and return true if the given value passes the custom validation.</p>
+    <p>You can write your own, more complex validations by passing in a <strong><em>validated_by</em></strong> lambda or an equivalent block. The lambda/block should expect one value (of the requested <strong><em>as</em></strong> type) and return true if the given value passes the custom validation.</p>
 
     <p>```ruby
-## Via a “validated_by” lambda …
-##
+# Via a “validated_by” lambda …
+#
 ENV.parse :MUST_BE_LOWERCASE, as: :string, validated_by: -&gt;(value) { value == value.downcase }</p>
 
-    <h2 id="or-with-a-block">… or with a block!</h2>
-    <p>##
+    <h1 id="or-with-a-block">… or with a block!</h1>
+    <p>#
 ENV.parse(:MUST_BE_LOWERCASE, as: :string) { |value| value == value.downcase }
 ENV.parse(:CONNECTION_RETRIES, as: :integer, &amp;:positive?)
 ```</p>
@@ -327,7 +340,7 @@ b = ENV.parse :B, as: :my_special_type_of_number
   <li>
     <p><strong>The <code>autoregister</code> Call</strong></p>
 
-    <p>Consolidating all of your <code>EnvParser.register</code> calls into a single place only makes sense. A single <code>EnvParser.autoregister</code> call take a filename to read and process as a series of constant registration requests. If no filename is given, the default <code>".env_parser.yml"</code> is assumed.</p>
+    <p>Consolidating all of your <code>EnvParser.register</code> calls into a single place only makes sense. A single <code>EnvParser.autoregister</code> call takes a filename to read and process as a series of constant registration requests. If no filename is given, the default <code>".env_parser.yml"</code> is assumed.</p>
 
     <p>You’ll normally want to call <code>EnvParser.autoregister</code> as early in your application as possible. For Rails applications (and other frameworks that call <code>require 'bundler/setup'</code>), requiring the EnvParser gem via …</p>
 
@@ -347,7 +360,7 @@ EnvParser.register :USERNAME, as: :string
 EnvParser.register :PASSWORD, as: :string
 EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
 
-    <h2 id="is-equivalent-to--1">… is equivalent to …</h2>
+    <h1 id="is-equivalent-to--1">… is equivalent to …</h1>
 
     <p>EnvParser.register USERNAME: { as: :string                           },
                    PASSWORD: { as: :string                           },
@@ -370,7 +383,7 @@ USERNAME:
   within: MyClassOrModule
 ```</p>
 
-    <p>Because no Ruby <em>statements</em> can be safely represented via YAML, the set of <code>EnvParser.register</code> options available via autoregistration is limited to <strong><em>as</em></strong>, <strong><em>within</em></strong>, <strong><em>if_unset</em></strong>, and <strong><em>from_set</em></strong>. As an additional restriction, <strong><em>from_set</em></strong> (if given) must be an array, as ranges cannot be represented in YAML.</p>
+    <p>Because no Ruby <em>statements</em> can be safely represented via YAML, the set of <code>EnvParser.register</code> options available via autoregistration is limited to <strong><em>as</em></strong>, <strong><em>named</em></strong>, <strong><em>within</em></strong>, <strong><em>if_unset</em></strong>, and <strong><em>from_set</em></strong>. As an additional restriction, <strong><em>from_set</em></strong> (if given) must be an array, as ranges cannot be represented in YAML.</p>
   </li>
 </ul>
 
@@ -396,9 +409,9 @@ USERNAME:
 </div></div>
 
       <div id="footer">
-  Generated on Sun Dec 25 21:11:48 2022 by
+  Generated on Mon Jun  9 14:00:25 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.28 (ruby-3.0.4).
+  0.9.37 (ruby-3.4.2).
 </div>
 
     </div>

data/docs/file_list.html

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html>
+<html >
   <head>
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta charset="utf-8" />
@@ -38,7 +38,10 @@
           
         </div>
 
-        <div id="search">Search: <input type="text" /></div>
+        <div id="search">
+          <label for="search-class">Search:</label>
+          <input id="search-class" type="text" />
+        </div>
       </div>
 
       <ul id="full_list" class="file">

data/docs/frames.html

@@ -2,13 +2,18 @@
 <html>
 <head>
   <meta charset="utf-8">
-	<title>Documentation by YARD 0.9.28</title>
+	<title>Documentation by YARD 0.9.37</title>
 </head>
 <script type="text/javascript">
-  var match = unescape(window.location.hash).match(/^#!(.+)/);
-  var name = match ? match[1] : 'index.html';
-  name = name.replace(/^(\w+):\/\//, '').replace(/^\/\//, '');
-  window.top.location = name;
+var mainUrl = 'index.html';
+try {
+    var match = decodeURIComponent(window.location.hash).match(/^#!(.+)/);
+    var name = match ? match[1] : mainUrl;
+    var url = new URL(name, location.href);
+    window.top.location.replace(url.origin === location.origin ? name : mainUrl);
+} catch (e) {
+    window.top.location.replace(mainUrl);
+}
 </script>
 <noscript>
   <h1>Oops!</h1>