env_parser 1.6.2 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. checksums.yaml +4 -4
  2. data/.circleci/config.yml +3 -2
  3. data/Gemfile.lock +73 -30
  4. data/README.md +2 -2
  5. data/docs/EnvParser/AutoregisterFileNotFound.html +12 -9
  6. data/docs/EnvParser/Error.html +10 -8
  7. data/docs/EnvParser/TypeAlreadyDefinedError.html +11 -8
  8. data/docs/EnvParser/Types/BaseTypes.html +11 -11
  9. data/docs/EnvParser/Types/ChronologyTypes.html +10 -9
  10. data/docs/EnvParser/Types/InternetTypes.html +10 -9
  11. data/docs/EnvParser/Types.html +12 -10
  12. data/docs/EnvParser/UnknownTypeError.html +12 -9
  13. data/docs/EnvParser/UnparseableAutoregisterSpec.html +12 -9
  14. data/docs/EnvParser/ValueNotAllowedError.html +12 -9
  15. data/docs/EnvParser/ValueNotConvertibleError.html +11 -8
  16. data/docs/EnvParser.html +67 -113
  17. data/docs/_index.html +9 -7
  18. data/docs/class_list.html +5 -5
  19. data/docs/css/common.css +1 -1
  20. data/docs/css/full_list.css +201 -53
  21. data/docs/css/style.css +988 -402
  22. data/docs/file.README.html +242 -327
  23. data/docs/file_list.html +5 -5
  24. data/docs/frames.html +1 -1
  25. data/docs/index.html +242 -327
  26. data/docs/js/app.js +800 -343
  27. data/docs/js/full_list.js +332 -240
  28. data/docs/method_list.html +5 -5
  29. data/docs/top-level-namespace.html +8 -6
  30. data/env_parser.gemspec +3 -3
  31. data/lib/env_parser/types/internet_types.rb +2 -2
  32. data/lib/env_parser/version.rb +1 -1
  33. data/lib/env_parser.rb +1 -3
  34. metadata +4 -9
  35. data/spec/env_parser/types/base_types_spec.rb +0 -98
  36. data/spec/env_parser/types/chronology_types_spec.rb +0 -49
  37. data/spec/env_parser/types/internet_types_spec.rb +0 -95
  38. data/spec/env_parser_spec.rb +0 -214
  39. data/spec/spec_helper.rb +0 -14
data/docs/index.html CHANGED
@@ -6,13 +6,13 @@
6
6
  <title>
7
7
  File: README
8
8
 
9
- &mdash; Documentation by YARD 0.9.37
9
+ &mdash; Documentation by YARD 0.9.44
10
10
 
11
11
  </title>
12
12
 
13
- <link rel="stylesheet" href="css/style.css" type="text/css" />
13
+ <link rel="stylesheet" href="css/style.css" type="text/css">
14
14
 
15
- <link rel="stylesheet" href="css/common.css" type="text/css" />
15
+ <link rel="stylesheet" href="css/common.css" type="text/css">
16
16
 
17
17
  <script type="text/javascript">
18
18
  pathId = "README";
@@ -27,6 +27,8 @@
27
27
 
28
28
  </head>
29
29
  <body>
30
+ <div id="main_progress" aria-hidden="true"></div>
31
+
30
32
  <div class="nav_wrap">
31
33
  <iframe id="nav" src="class_list.html?1"></iframe>
32
34
  <div id="resizer"></div>
@@ -59,361 +61,274 @@
59
61
 
60
62
  <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>
61
63
  <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>
62
-
63
- <h1 id="envparser">EnvParser</h1>
64
-
65
- <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 work, however: for numbers you need to cast with <code>to_i</code> or <code>to_f</code> … for booleans you need to check for a specific value (<code>ENV['SOME_VAR'] == 'true'</code>) … maybe you want to set non-trivial defaults (something other than <code>0</code> or <code>''</code>)? … maybe you only want to allow values from a limited set? …</p>
66
-
67
- <p>Things can get out of control pretty fast, especially as the number of environment variables in play grows. Tools like <a href="https://github.com/bkeepers/dotenv">dotenv</a> help to make sure you’re loading the correct <strong>set</strong> of variables, but <a href="https://github.com/nestor-custodio/env_parser">EnvParser</a> makes <strong>the values themselves</strong> usable with a minimum of effort.</p>
68
-
69
- <p><a href="http://nestor-custodio.github.io/env_parser/EnvParser.html">Full documentation is available here</a>, but do read below for a crash course on availble featues!</p>
70
-
71
- <h2 id="installation">Installation</h2>
72
-
64
+ <h1 id="EnvParser">EnvParser</h1>
65
+ <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 work, however: for numbers you need to cast with <code>to_i</code> or <code>to_f</code> ... for booleans you need to check for a specific value (<code>ENV['SOME_VAR'] == 'true'</code>) ... maybe you want to set non-trivial defaults (something other than <code>0</code> or <code>''</code>)? ... maybe you only want to allow values from a limited set? ...</p>
66
+ <p>Things can get out of control pretty fast, especially as the number of environment variables in play grows. Tools like <a href="https://github.com/bkeepers/dotenv">dotenv</a> help to make sure you're loading the correct <strong>set</strong> of variables, but <a href="https://github.com/nestor-custodio/env_parser">EnvParser</a> makes <strong>the values themselves</strong> usable with a minimum of effort.</p>
67
+ <p><a href="https://nestor-custodio.github.io/env_parser/EnvParser.html">Full documentation is available here</a>, but do read below for a crash course on availble featues!</p>
68
+ <h2 id="Installation">Installation</h2>
73
69
  <ul>
74
- <li>If your project uses <a href="https://github.com/bundler/bundler">Bundler</a>:
75
- <ul>
76
- <li>
77
- <p>Add one of the following to your application’s Gemfile:
78
- ```ruby
79
- # For on-demand usage …
80
- #
81
- gem ‘env_parser’</p>
82
-
83
- <h1 id="to-automatically-register-env">To automatically register ENV</h1>
84
- <p># constants per “.env_parser.yml” …
85
- #
86
- gem ‘env_parser’, require: ‘env_parser/autoregister’
87
- ```</p>
88
- </li>
89
- <li>
90
- <p>And then run a:
91
- <code>shell
92
- $ bundle install
93
- </code></p>
94
- </li>
95
- </ul>
96
- </li>
97
- <li>Or, you can keep things simple with a manual install:
98
- <code>shell
99
- $ gem install env_parser
100
- </code></li>
70
+ <li>
71
+ <p>If your project uses <a href="https://github.com/bundler/bundler">Bundler</a>:</p>
72
+ <ul>
73
+ <li>Add one of the following to your application's Gemfile:
74
+ <pre class="code ruby"><code class="ruby"><span class='comment'># For on-demand usage ...
75
+ </span><span class='comment'>#
76
+ </span><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>env_parser</span><span class='tstring_end'>&#39;</span></span>
77
+
78
+ <span class='comment'># To automatically register ENV
79
+ </span><span class='comment'># constants per &quot;.env_parser.yml&quot; ...
80
+ </span><span class='comment'>#
81
+ </span><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>env_parser</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>require:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>env_parser/autoregister</span><span class='tstring_end'>&#39;</span></span>
82
+ </code></pre>
83
+ </li>
84
+ <li>And then run a:
85
+ <pre class="code shell"><code class="shell">$ bundle install
86
+ </code></pre>
87
+ </li>
101
88
  </ul>
102
-
103
- <h2 id="syntax-cheat-sheet">Syntax Cheat Sheet</h2>
104
-
105
- <p>```ruby
106
- # Returns an ENV value parsed “as” a specific type:
107
- #
108
- EnvParser.parse env_key_as_a_symbol,
109
- as: …, # ➜ required; Symbol
110
- if_unset: …, # ➜ optional; default value (of any type)
111
- from_set: …, # ➜ optional; Array or Range
112
- validated_by: -&gt;(value) { … } # ➜ optional; may also be given as a block</p>
113
-
114
- <h1 id="parse-an-env-value-and-register-it-as-a-constant">Parse an ENV value and register it as a constant:</h1>
115
- <p>#
116
- EnvParser.register env_key_as_a_symbol,
117
- as: …, # ➜ required; Symbol
118
- named: …, # ➜ optional; String or Symbol; available only if <code>within</code> is also given
119
- within: …, # ➜ optional; Class or Module
120
- if_unset: …, # ➜ optional; default value (of any type)
121
- from_set: …, # ➜ optional; Array or Range
122
- validated_by: -&gt;(value) { … } # ➜ optional; may also be given as a block</p>
123
-
124
- <h1 id="registers-all-env-variables-as-speced-in-envparseryml">Registers all ENV variables as spec’ed in “.env_parser.yml”:</h1>
125
- <p>#
126
- EnvParser.autoregister # Note this is automatically called if your
127
- # Gemfile included the “env_parser” gem with
128
- # the “require: ‘env_parser/autoregister’” option.</p>
129
-
130
- <h1 id="lets-you-call-parse-and-register-on-env-itself">Lets you call “parse” and “register” on ENV itself:</h1>
131
- <p>#
132
- EnvParser.add_env_bindings # ENV.parse will now be a proxy for EnvParser.parse
133
- # and ENV.register will now be a proxy for EnvParser.register
134
- ```</p>
135
-
136
- <h2 id="extended-how-to-use">Extended How-To-Use</h2>
137
-
138
- <h4 id="basic-usage">Basic Usage</h4>
139
-
89
+ </li>
90
+ <li>
91
+ <p>Or, you can keep things simple with a manual install:</p>
92
+ <pre class="code shell"><code class="shell">$ gem install env_parser
93
+ </code></pre>
94
+ </li>
95
+ </ul>
96
+ <h2 id="Syntax_Cheat_Sheet">Syntax Cheat Sheet</h2>
97
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Returns an ENV value parsed &quot;as&quot; a specific type:
98
+ </span><span class='comment'>#
99
+ </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='id identifier rubyid_env_key_as_a_symbol'>env_key_as_a_symbol</span><span class='comma'>,</span>
100
+ <span class='label'>as:</span> <span class='id identifier rubyid_…'>…</span><span class='comma'>,</span> <span class='comment'># ➜ required; Symbol
101
+ </span> <span class='label'>if_unset:</span> <span class='id identifier rubyid_…'>…</span><span class='comma'>,</span> <span class='comment'># ➜ optional; default value (of any type)
102
+ </span> <span class='label'>from_set:</span> <span class='id identifier rubyid_…'>…</span><span class='comma'>,</span> <span class='comment'># ➜ optional; Array or Range
103
+ </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_…'>…</span> <span class='rbrace'>}</span> <span class='comment'># ➜ optional; may also be given as a block
104
+ </span>
105
+ <span class='comment'># Parse an ENV value and register it as a constant:
106
+ </span><span class='comment'>#
107
+ </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_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='id identifier rubyid_env_key_as_a_symbol'>env_key_as_a_symbol</span><span class='comma'>,</span>
108
+ <span class='label'>as:</span> <span class='id identifier rubyid_…'>…</span><span class='comma'>,</span> <span class='comment'># ➜ required; Symbol
109
+ </span> <span class='label'>named:</span> <span class='id identifier rubyid_…'>…</span><span class='comma'>,</span> <span class='comment'># ➜ optional; String or Symbol; available only if `within` is also given
110
+ </span> <span class='label'>within:</span> <span class='id identifier rubyid_…'>…</span><span class='comma'>,</span> <span class='comment'># ➜ optional; Class or Module
111
+ </span> <span class='label'>if_unset:</span> <span class='id identifier rubyid_…'>…</span><span class='comma'>,</span> <span class='comment'># ➜ optional; default value (of any type)
112
+ </span> <span class='label'>from_set:</span> <span class='id identifier rubyid_…'>…</span><span class='comma'>,</span> <span class='comment'># ➜ optional; Array or Range
113
+ </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_…'>…</span> <span class='rbrace'>}</span> <span class='comment'># ➜ optional; may also be given as a block
114
+ </span>
115
+ <span class='comment'># Registers all ENV variables as spec&#39;ed in &quot;.env_parser.yml&quot;:
116
+ </span><span class='comment'>#
117
+ </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_autoregister'><span class='object_link'><a href="EnvParser.html#autoregister-class_method" title="EnvParser.autoregister (method)">autoregister</a></span></span> <span class='comment'># Note this is automatically called if your
118
+ </span> <span class='comment'># Gemfile included the &quot;env_parser&quot; gem with
119
+ </span> <span class='comment'># the &quot;require: &#39;env_parser/autoregister&#39;&quot; option.
120
+ </span>
121
+ <span class='comment'># Lets you call &quot;parse&quot; and &quot;register&quot; on ENV itself:
122
+ </span><span class='comment'>#
123
+ </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_add_env_bindings'><span class='object_link'><a href="EnvParser.html#add_env_bindings-class_method" title="EnvParser.add_env_bindings (method)">add_env_bindings</a></span></span> <span class='comment'># ENV.parse will now be a proxy for EnvParser.parse
124
+ </span> <span class='comment'># and ENV.register will now be a proxy for EnvParser.register
125
+ </span></code></pre>
126
+ <h2 id="Extended_How_To_Use">Extended How-To-Use</h2>
127
+ <h4 id="Basic_Usage">Basic Usage</h4>
140
128
  <ul>
141
- <li>
142
- <p><strong>Parsing <code>ENV</code> Values</strong></p>
143
-
144
- <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>
145
-
146
- <p><code>ruby
147
- # Returns ENV['TIMEOUT_MS'] as an Integer,
148
- # or a sensible default (0) if ENV['TIMEOUT_MS'] is unset.
149
- #
150
- timeout_ms = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
151
- </code></p>
152
-
153
- <p>You can check the full documentation for <a href="http://nestor-custodio.github.io/env_parser/EnvParser/Types.html">a list of all <strong><em>as</em></strong> types available right out of the box</a>.</p>
154
- </li>
155
- <li>
156
- <p><strong>How About Less Typing?</strong></p>
157
-
158
- <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>
159
-
160
- <p><code>ruby
161
- # YAY, LESS TYPING! 😃
162
- # These two are the same:
163
- #
164
- more_typing = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
165
- less_typing = EnvParser.parse :TIMEOUT_MS, as: :integer
166
- </code></p>
167
- </li>
168
- <li>
169
- <p><strong>Registering Constants From <code>ENV</code> Values</strong></p>
170
-
171
- <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>
172
-
173
- <p>```ruby
174
- ENV[‘API_KEY’] # =&gt; ‘unbreakable p4$$w0rd’</p>
175
-
176
- <p>EnvParser.register :API_KEY, as: :string
177
- API_KEY # =&gt; ‘unbreakable p4$$w0rd’
178
- ```</p>
179
-
180
- <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>
181
-
182
- <p>```ruby
183
- ENV[‘BEST_VIDEO’] # =&gt; ‘https://youtu.be/L_jWHffIx5E’</p>
184
-
185
- <p>EnvParser.register :BEST_VIDEO, as: :string, within: URI
186
- URI::BEST_VIDEO # =&gt; ‘https://youtu.be/L_jWHffIx5E’
187
- BEST_VIDEO # =&gt; raises NameError
188
- ```</p>
189
-
190
- <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>
191
-
192
- <p>```ruby
193
- ENV[‘CUSTOM_CLIENT_DEFAULT_HOSTNAME’] # =&gt; ‘localhost’
194
- ENV[‘CUSTOM_CLIENT_DEFAULT_PORT’ ] # =&gt; ‘3000’</p>
195
-
196
- <p>EnvParser.register :CUSTOM_CLIENT_DEFAULT_HOSTNAME, as: :string , named: :DEFAULT_HOSTNAME, within: CustomClient
197
- EnvParser.register :CUSTOM_CLIENT_DEFAULT_PORT , as: :integer, named: :DEFAULT_PORT , within: CustomClient
198
- CustomClient::DEFAULT_HOSTNAME # =&gt; ‘localhost’
199
- CustomClient::DEFAULT_PORT # =&gt; 3000
200
- ```</p>
201
-
202
- <p>You can also register multiple constants with a single call, which is a bit cleaner.</p>
203
-
204
- <p>```ruby
205
- EnvParser.register :USERNAME, as: :string
129
+ <li>
130
+ <p><strong>Parsing <code>ENV</code> Values</strong></p>
131
+ <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>
132
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Returns ENV[&#39;TIMEOUT_MS&#39;] as an Integer,
133
+ </span><span class='comment'># or a sensible default (0) if ENV[&#39;TIMEOUT_MS&#39;] is unset.
134
+ </span><span class='comment'>#
135
+ </span><span class='id identifier rubyid_timeout_ms'>timeout_ms</span> <span class='op'>=</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='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>TIMEOUT_MS</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span>
136
+ </code></pre>
137
+ <p>You can check the full documentation for <a href="https://nestor-custodio.github.io/env_parser/EnvParser/Types.html">a list of all <strong><em>as</em></strong> types available right out of the box</a>.</p>
138
+ </li>
139
+ <li>
140
+ <p><strong>How About Less Typing?</strong></p>
141
+ <p>EnvParser is all about <del>simplification</del> <del>less typing</del> <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>
142
+ <pre class="code ruby"><code class="ruby"><span class='comment'># YAY, LESS TYPING! 😃
143
+ </span><span class='comment'># These two are the same:
144
+ </span><span class='comment'>#
145
+ </span><span class='id identifier rubyid_more_typing'>more_typing</span> <span class='op'>=</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='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>TIMEOUT_MS</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span>
146
+ <span class='id identifier rubyid_less_typing'>less_typing</span> <span class='op'>=</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'>:TIMEOUT_MS</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span>
147
+ </code></pre>
148
+ </li>
149
+ <li>
150
+ <p><strong>Registering Constants From <code>ENV</code> Values</strong></p>
151
+ <p>The <code>EnvParser.register</code> method lets you &quot;promote&quot; <code>ENV</code> variables into their own constants, already parsed into the correct type.</p>
152
+ <pre class="code ruby"><code class="ruby"><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>API_KEY</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'># =&gt; &#39;unbreakable p4$$w0rd&#39;
153
+ </span>
154
+ <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_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:API_KEY</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span>
155
+ <span class='const'>API_KEY</span> <span class='comment'># =&gt; &#39;unbreakable p4$$w0rd&#39;
156
+ </span></code></pre>
157
+ <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>
158
+ <pre class="code ruby"><code class="ruby"><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>BEST_VIDEO</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'># =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39;
159
+ </span>
160
+ <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_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:BEST_VIDEO</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='comma'>,</span> <span class='label'>within:</span> <span class='const'>URI</span>
161
+ <span class='const'>URI</span><span class='op'>::</span><span class='const'>BEST_VIDEO</span> <span class='comment'># =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39;
162
+ </span><span class='const'>BEST_VIDEO</span> <span class='comment'># =&gt; raises NameError
163
+ </span></code></pre>
164
+ <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>
165
+ <pre class="code ruby"><code class="ruby"><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>CUSTOM_CLIENT_DEFAULT_HOSTNAME</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'># =&gt; &#39;localhost&#39;
166
+ </span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>CUSTOM_CLIENT_DEFAULT_PORT</span><span class='tstring_end'>&#39;</span></span> <span class='rbracket'>]</span> <span class='comment'># =&gt; &#39;3000&#39;
167
+ </span>
168
+ <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_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:CUSTOM_CLIENT_DEFAULT_HOSTNAME</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span> <span class='comma'>,</span> <span class='label'>named:</span> <span class='symbol'>:DEFAULT_HOSTNAME</span><span class='comma'>,</span> <span class='label'>within:</span> <span class='const'>CustomClient</span>
169
+ <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_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:CUSTOM_CLIENT_DEFAULT_PORT</span> <span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>named:</span> <span class='symbol'>:DEFAULT_PORT</span> <span class='comma'>,</span> <span class='label'>within:</span> <span class='const'>CustomClient</span>
170
+ <span class='const'>CustomClient</span><span class='op'>::</span><span class='const'>DEFAULT_HOSTNAME</span> <span class='comment'># =&gt; &#39;localhost&#39;
171
+ </span><span class='const'>CustomClient</span><span class='op'>::</span><span class='const'>DEFAULT_PORT</span> <span class='comment'># =&gt; 3000
172
+ </span></code></pre>
173
+ <p>You can also register multiple constants with a single call, which is a bit cleaner.</p>
174
+ <pre class="code ruby"><code class="ruby">EnvParser.register :USERNAME, as: :string
206
175
  EnvParser.register :PASSWORD, as: :string
207
- EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
176
+ EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }
208
177
 
209
- <h1 id="is-equivalent-to-">… is equivalent to …</h1>
178
+ # ... is equivalent to ... #
210
179
 
211
- <p>EnvParser.register USERNAME: { as: :string },
180
+ EnvParser.register USERNAME: { as: :string },
212
181
  PASSWORD: { as: :string },
213
182
  MOCK_API: { as: :boolean, within: MyClassOrModule }
214
- ```</p>
215
- </li>
216
- <li>
217
- <p><strong>Okay, But… How About Even Less Typing?</strong></p>
218
-
219
- <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>
220
-
221
- <p>```ruby
222
- ENV[‘SHORT_PI’] # =&gt; ‘3.1415926’
223
- ENV[‘BETTER_PI’] # =&gt; ‘[“flaky crust”, “strawberry filling”]’</p>
224
-
225
- <h1 id="bind-the-proxy-methods">Bind the proxy methods.</h1>
226
- <p>#
227
- EnvParser.add_env_bindings</p>
228
-
229
- <p>ENV.parse :SHORT_PI, as: :float # =&gt; 3.1415926
230
- ENV.register :BETTER_PI, as: :array # Your constant is set!
231
- ```</p>
232
-
233
- <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>
234
-
235
- <p>```ruby
236
- ENV[‘SHORT_PI’] # =&gt; ‘3.1415926’</p>
237
-
238
- <p>EnvParser.parse ‘SHORT_PI’, as: :float # =&gt; ‘SHORT_PI’ as a float: 0.0
239
- EnvParser.parse :SHORT_PI , as: :float # =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926</p>
240
-
241
- <h1 id="bind-the-proxy-methods-1">Bind the proxy methods.</h1>
242
- <p>#
243
- EnvParser.add_env_bindings</p>
244
-
245
- <p>ENV.parse ‘SHORT_PI’, as: :float # =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926
246
- ENV.parse :SHORT_PI , as: :float # =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926
247
- ```</p>
248
-
249
- <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>
250
-
251
- <p><strong>All additional examples below will assume that <code>ENV</code> bindings are already in place, for brevity’s sake.</strong></p>
252
- </li>
183
+ </code></pre>
184
+ </li>
185
+ <li>
186
+ <p><strong>Okay, But... How About Even Less Typing?</strong></p>
187
+ <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>
188
+ <pre class="code ruby"><code class="ruby"><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'># =&gt; &#39;3.1415926&#39;
189
+ </span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>BETTER_PI</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'># =&gt; &#39;[&quot;flaky crust&quot;, &quot;strawberry filling&quot;]&#39;
190
+ </span>
191
+ <span class='comment'># Bind the proxy methods.
192
+ </span><span class='comment'>#
193
+ </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_add_env_bindings'><span class='object_link'><a href="EnvParser.html#add_env_bindings-class_method" title="EnvParser.add_env_bindings (method)">add_env_bindings</a></span></span>
194
+
195
+ <span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:SHORT_PI</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:float</span> <span class='comment'># =&gt; 3.1415926
196
+ </span><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_register'>register</span> <span class='symbol'>:BETTER_PI</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:array</span> <span class='comment'># Your constant is set!
197
+ </span></code></pre>
198
+ <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>
199
+ <pre class="code ruby"><code class="ruby"><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'># =&gt; &#39;3.1415926&#39;
200
+ </span>
201
+ <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='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:float</span> <span class='comment'># =&gt; &#39;SHORT_PI&#39; as a float: 0.0
202
+ </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'>:SHORT_PI</span> <span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:float</span> <span class='comment'># =&gt; ENV[&#39;SHORT_PI&#39;] as a float: 3.1415926
203
+ </span>
204
+ <span class='comment'># Bind the proxy methods.
205
+ </span><span class='comment'>#
206
+ </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_add_env_bindings'><span class='object_link'><a href="EnvParser.html#add_env_bindings-class_method" title="EnvParser.add_env_bindings (method)">add_env_bindings</a></span></span>
207
+
208
+ <span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:float</span> <span class='comment'># =&gt; ENV[&#39;SHORT_PI&#39;] as a float: 3.1415926
209
+ </span><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:SHORT_PI</span> <span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:float</span> <span class='comment'># =&gt; ENV[&#39;SHORT_PI&#39;] as a float: 3.1415926
210
+ </span></code></pre>
211
+ <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>
212
+ <p><strong>All additional examples below will assume that <code>ENV</code> bindings are already in place, for brevity's sake.</strong></p>
213
+ </li>
253
214
  </ul>
254
-
255
- <h4 id="ensuring-usable-values">Ensuring Usable Values</h4>
256
-
215
+ <h4 id="Ensuring_Usable_Values">Ensuring Usable Values</h4>
257
216
  <ul>
258
- <li>
259
- <p><strong>Sensible Defaults</strong></p>
260
-
261
- <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>
262
-
263
- <p><code>ruby
264
- ENV.parse :MISSING_VAR, as: :integer # =&gt; 0
265
- ENV.parse :MISSING_VAR, as: :integer, if_unset: 250 # =&gt; 250
266
- </code></p>
267
-
268
- <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>
269
-
270
- <p><code>ruby
271
- ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!' # =&gt; 'Careful!' (NOT AN INTEGER)
272
- </code></p>
273
- </li>
274
- <li>
275
- <p><strong>Selecting From A Set</strong></p>
276
-
277
- <p>Sometimes setting the <strong><em>as</em></strong> type is a bit too open-ended. The <strong><em>from_set</em></strong> option lets you restrict the domain of allowed values.</p>
278
-
279
- <p>```ruby
280
- ENV.parse :API_TO_USE, as: :symbol, from_set: %i[internal external]
281
- ENV.parse :NETWORK_PORT, as: :integer, from_set: (1..65535), if_unset: 80</p>
282
-
283
- <h1 id="and-if-the-value-is-not-in-the-allowed-set-">And if the value is not in the allowed set …</h1>
284
- <p>#
285
- ENV.parse :TWELVE, as: :integer, from_set: (1..5) # =&gt; raises EnvParser::ValueNotAllowedError
286
- ```</p>
287
- </li>
288
- <li>
289
- <p><strong>Custom Validation Of Parsed Values</strong></p>
290
-
291
- <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>
292
-
293
- <p>```ruby
294
- # Via a “validated_by” lambda …
295
- #
296
- ENV.parse :MUST_BE_LOWERCASE, as: :string, validated_by: -&gt;(value) { value == value.downcase }</p>
297
-
298
- <h1 id="or-with-a-block">… or with a block!</h1>
299
- <p>#
300
- ENV.parse(:MUST_BE_LOWERCASE, as: :string) { |value| value == value.downcase }
301
- ENV.parse(:CONNECTION_RETRIES, as: :integer, &amp;:positive?)
302
- ```</p>
303
- </li>
304
- <li>
305
- <p><strong>Defining Your Own EnvParser “<em>as</em>” Types</strong></p>
306
-
307
- <p>If you use a particular validation many times or are often manipulating values in the same way after EnvParser has done its thing, you may want to register a new type altogether. Defining a new type makes your code both more maintainable (all the logic for your special type is only defined once) and more readable (your <code>parse</code> calls aren’t littered with type-checking cruft).</p>
308
-
309
- <p>Something as repetitive as:</p>
310
-
311
- <p>```ruby
312
- a = ENV.parse :A, as: :int, if_unset: 6
313
- raise unless passes_all_my_checks?(a)</p>
314
-
315
- <p>b = ENV.parse :B, as: :int, if_unset: 6
316
- raise unless passes_all_my_checks?(b)
317
- ```</p>
318
-
319
- <p>… is perhaps best handled by defining a new type:</p>
320
-
321
- <p>```ruby
322
- EnvParser.define_type(:my_special_type_of_number, if_unset: 6) do |value|
323
- value = value.to_i
324
- unless passes_all_my_checks?(value)
325
- raise(EnvParser::ValueNotConvertibleError, ‘cannot parse as a “special type number”’)
326
- end</p>
327
-
328
- <p>value
329
- end</p>
330
-
331
- <p>a = ENV.parse :A, as: :my_special_type_of_number
332
- b = ENV.parse :B, as: :my_special_type_of_number
333
- ```</p>
334
- </li>
217
+ <li>
218
+ <p><strong>Sensible Defaults</strong></p>
219
+ <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>
220
+ <pre class="code ruby"><code class="ruby"><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:MISSING_VAR</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span> <span class='comment'># =&gt; 0
221
+ </span><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:MISSING_VAR</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>250</span> <span class='comment'># =&gt; 250
222
+ </span></code></pre>
223
+ <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>
224
+ <pre class="code ruby"><code class="ruby"><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:MISSING_VAR</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Careful!</span><span class='tstring_end'>&#39;</span></span> <span class='comment'># =&gt; &#39;Careful!&#39; (NOT AN INTEGER)
225
+ </span></code></pre>
226
+ </li>
227
+ <li>
228
+ <p><strong>Selecting From A Set</strong></p>
229
+ <p>Sometimes setting the <strong><em>as</em></strong> type is a bit too open-ended. The <strong><em>from_set</em></strong> option lets you restrict the domain of allowed values.</p>
230
+ <pre class="code ruby"><code class="ruby"><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:API_TO_USE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:symbol</span><span class='comma'>,</span> <span class='label'>from_set:</span> <span class='qsymbols_beg'>%i[</span><span class='tstring_content'>internal</span><span class='words_sep'> </span><span class='tstring_content'>external</span><span class='tstring_end'>]</span></span>
231
+ <span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:NETWORK_PORT</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'>65535</span><span class='rparen'>)</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>80</span>
232
+
233
+ <span class='comment'># And if the value is not in the allowed set ...
234
+ </span><span class='comment'>#
235
+ </span><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:TWELVE</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::ValueNotAllowedError
236
+ </span></code></pre>
237
+ </li>
238
+ <li>
239
+ <p><strong>Custom Validation Of Parsed Values</strong></p>
240
+ <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>
241
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Via a &quot;validated_by&quot; lambda ...
242
+ </span><span class='comment'>#
243
+ </span><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</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>
244
+
245
+ <span class='comment'># ... or with a block!
246
+ </span><span class='comment'>#
247
+ </span><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</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>
248
+ <span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</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'>:positive?</span><span class='rparen'>)</span>
249
+ </code></pre>
250
+ </li>
251
+ <li>
252
+ <p><strong>Defining Your Own EnvParser &quot;<em>as</em>&quot; Types</strong></p>
253
+ <p>If you use a particular validation many times or are often manipulating values in the same way after EnvParser has done its thing, you may want to register a new type altogether. Defining a new type makes your code both more maintainable (all the logic for your special type is only defined once) and more readable (your <code>parse</code> calls aren't littered with type-checking cruft).</p>
254
+ <p>Something as repetitive as:</p>
255
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_a'>a</span> <span class='op'>=</span> <span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:A</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:int</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>6</span>
256
+ <span class='id identifier rubyid_raise'>raise</span> <span class='kw'>unless</span> <span class='id identifier rubyid_passes_all_my_checks?'>passes_all_my_checks?</span><span class='lparen'>(</span><span class='id identifier rubyid_a'>a</span><span class='rparen'>)</span>
257
+
258
+ <span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:B</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:int</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>6</span>
259
+ <span class='id identifier rubyid_raise'>raise</span> <span class='kw'>unless</span> <span class='id identifier rubyid_passes_all_my_checks?'>passes_all_my_checks?</span><span class='lparen'>(</span><span class='id identifier rubyid_b'>b</span><span class='rparen'>)</span>
260
+ </code></pre>
261
+ <p>... is perhaps best handled by defining a new type:</p>
262
+ <pre class="code ruby"><code class="ruby"><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_define_type'><span class='object_link'><a href="EnvParser.html#define_type-class_method" title="EnvParser.define_type (method)">define_type</a></span></span><span class='lparen'>(</span><span class='symbol'>:my_special_type_of_number</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>6</span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_value'>value</span><span class='op'>|</span>
263
+ <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_i'>to_i</span>
264
+ <span class='kw'>unless</span> <span class='id identifier rubyid_passes_all_my_checks?'>passes_all_my_checks?</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span>
265
+ <span class='id identifier rubyid_raise'>raise</span><span class='lparen'>(</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="EnvParser/ValueNotConvertibleError.html" title="EnvParser::ValueNotConvertibleError (class)">ValueNotConvertibleError</a></span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>cannot parse as a &quot;special type number&quot;</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
266
+ <span class='kw'>end</span>
267
+
268
+ <span class='id identifier rubyid_value'>value</span>
269
+ <span class='kw'>end</span>
270
+
271
+ <span class='id identifier rubyid_a'>a</span> <span class='op'>=</span> <span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:A</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:my_special_type_of_number</span>
272
+ <span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:B</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:my_special_type_of_number</span>
273
+ </code></pre>
274
+ </li>
335
275
  </ul>
336
-
337
- <h4 id="auto-registering-constants">Auto-Registering Constants</h4>
338
-
276
+ <h4 id="Auto_Registering_Constants">Auto-Registering Constants</h4>
339
277
  <ul>
340
- <li>
341
- <p><strong>The <code>autoregister</code> Call</strong></p>
342
-
343
- <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>
344
-
345
- <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>
346
-
347
- <p><code>ruby
348
- gem 'env_parser', require: 'env_parser/autoregister'
349
- </code></p>
350
-
351
- <p>… will automatically make the autoregistration call for you as soon as the gem is loaded (which should be early enough for most uses). If this is <em>still</em> not early enough for your needs, you can always <code>require 'env_parser/autoregister'</code> yourself even before <code>bundler/setup</code> is invoked.</p>
352
- </li>
353
- <li>
354
- <p><strong>The “.env_parser.yml” File</strong></p>
355
-
356
- <p>If you recall, multiple constants can be registered via a single <code>EnvParser.register</code> call:</p>
357
-
358
- <p>```ruby
359
- EnvParser.register :USERNAME, as: :string
278
+ <li>
279
+ <p><strong>The <code>autoregister</code> Call</strong></p>
280
+ <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>&quot;.env_parser.yml&quot;</code> is assumed.</p>
281
+ <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>
282
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>env_parser</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>require:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>env_parser/autoregister</span><span class='tstring_end'>&#39;</span></span>
283
+ </code></pre>
284
+ <p>... will automatically make the autoregistration call for you as soon as the gem is loaded (which should be early enough for most uses). If this is <em>still</em> not early enough for your needs, you can always <code>require 'env_parser/autoregister'</code> yourself even before <code>bundler/setup</code> is invoked.</p>
285
+ </li>
286
+ <li>
287
+ <p><strong>The &quot;.env_parser.yml&quot; File</strong></p>
288
+ <p>If you recall, multiple constants can be registered via a single <code>EnvParser.register</code> call:</p>
289
+ <pre class="code ruby"><code class="ruby">EnvParser.register :USERNAME, as: :string
360
290
  EnvParser.register :PASSWORD, as: :string
361
- EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
291
+ EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }
362
292
 
363
- <h1 id="is-equivalent-to--1">… is equivalent to …</h1>
293
+ # ... is equivalent to ... #
364
294
 
365
- <p>EnvParser.register USERNAME: { as: :string },
295
+ EnvParser.register USERNAME: { as: :string },
366
296
  PASSWORD: { as: :string },
367
297
  MOCK_API: { as: :boolean, within: MyClassOrModule }
368
- ```</p>
369
-
370
- <p>The autoregistraton file is intended to read as a YAML version of what you’d pass to the single-call version of <code>EnvParser.register</code>: a single hash with keys for each of the constants you’d like to register, with each value being the set of options to parse that constant.</p>
371
-
372
- <p>The equivalent autoregistration file for the above would be:</p>
373
-
374
- <p>```yaml
375
- USERNAME:
376
- as: :string</p>
298
+ </code></pre>
299
+ <p>The autoregistraton file is intended to read as a YAML version of what you'd pass to the single-call version of <code>EnvParser.register</code>: a single hash with keys for each of the constants you'd like to register, with each value being the set of options to parse that constant.</p>
300
+ <p>The equivalent autoregistration file for the above would be:</p>
301
+ <pre class="code yaml"><code class="yaml">USERNAME:
302
+ as: :string
377
303
 
378
- <p>PASSWORD:
379
- as: :string</p>
304
+ PASSWORD:
305
+ as: :string
380
306
 
381
- <p>MOCK_API:
307
+ MOCK_API:
382
308
  as: :boolean
383
309
  within: MyClassOrModule
384
- ```</p>
385
-
386
- <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>
387
- </li>
310
+ </code></pre>
311
+ <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>
312
+ </li>
388
313
  </ul>
389
-
390
- <h2 id="feature-roadmap--future-development">Feature Roadmap / Future Development</h2>
391
-
314
+ <h2 id="Feature_Roadmap___Future_Development">Feature Roadmap / Future Development</h2>
392
315
  <p>Additional features coming in the future:</p>
393
-
394
316
  <ul>
395
- <li>Continue to round out the <strong><em>as</em></strong> type selection as ideas come to mind, suggestions are made, and pull requests are submitted.</li>
317
+ <li>Continue to round out the <strong><em>as</em></strong> type selection as ideas come to mind, suggestions are made, and pull requests are submitted.</li>
396
318
  </ul>
397
-
398
- <h2 id="contribution--development">Contribution / Development</h2>
399
-
400
- <p>Bug reports and pull requests are welcome at: <a href="https://github.com/nestor-custodio/env_parser">https://github.com/nestor-custodio/env_parser</a></p>
401
-
319
+ <h2 id="Contribution___Development">Contribution / Development</h2>
320
+ <p>Bug reports and pull requests are welcome at: <a href="https://github.com/nestor-custodio/env_parser"><a href="https://github.com/nestor-custodio/env_parser">https://github.com/nestor-custodio/env_parser</a></a></p>
402
321
  <p>After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run <code>bundle exec rspec</code> to run the tests. You can also run <code>bin/console</code> for an interactive prompt that will allow you to experiment.</p>
403
-
404
322
  <p>Linting is courtesy of <a href="https://docs.rubocop.org/">Rubocop</a> (<code>bundle exec rubocop</code>) and documentation is built using <a href="https://yardoc.org/">Yard</a> (<code>bundle exec yard</code>). Please ensure you have a clean bill of health from Rubocop and that any new features and/or changes to behaviour are reflected in the documentation before submitting a pull request.</p>
405
-
406
- <h2 id="license">License</h2>
407
-
408
- <p>EnvParser is available as open source under the terms of the <a href="https://tldrlegal.com/license/mit-license">MIT License</a>.</p>
409
- </div></div>
323
+ <h2 id="License">License</h2>
324
+ <p>EnvParser is available as open source under the terms of the <a href="https://tldrlegal.com/license/mit-license">MIT License</a>.</p></div></div>
410
325
 
411
326
  <div id="footer">
412
- Generated on Mon Jun 9 14:00:25 2025 by
327
+ Generated on Sun Jun 21 01:17:51 2026 by
413
328
  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
414
- 0.9.37 (ruby-3.4.2).
329
+ 0.9.44 (ruby-3.4.8).
415
330
  </div>
416
331
 
417
332
  </div>
418
333
  </body>
419
- </html>
334
+ </html>