env_parser 1.3.1 → 1.3.2

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 +1 -1
  3. data/.rubocop.yml +22 -35
  4. data/.ruby-version +1 -1
  5. data/Gemfile.lock +44 -42
  6. data/README.md +1 -1
  7. data/docs/EnvParser/AutoregisterFileNotFound.html +6 -6
  8. data/docs/EnvParser/Error.html +5 -6
  9. data/docs/EnvParser/TypeAlreadyDefinedError.html +5 -6
  10. data/docs/EnvParser/Types/BaseTypes.html +9 -7
  11. data/docs/EnvParser/Types/ChronologyTypes.html +7 -6
  12. data/docs/EnvParser/Types/InternetTypes.html +7 -6
  13. data/docs/EnvParser/Types.html +6 -6
  14. data/docs/EnvParser/UnknownTypeError.html +5 -6
  15. data/docs/EnvParser/UnparseableAutoregisterSpec.html +6 -6
  16. data/docs/EnvParser/ValueNotAllowedError.html +7 -6
  17. data/docs/EnvParser/ValueNotConvertibleError.html +5 -6
  18. data/docs/EnvParser.html +117 -121
  19. data/docs/_index.html +5 -7
  20. data/docs/file.README.html +241 -143
  21. data/docs/frames.html +1 -1
  22. data/docs/index.html +241 -143
  23. data/docs/method_list.html +1 -9
  24. data/docs/top-level-namespace.html +4 -82
  25. data/env_parser.gemspec +14 -14
  26. data/lib/env_parser/errors.rb +18 -18
  27. data/lib/env_parser/types/base_types.rb +69 -69
  28. data/lib/env_parser/types/chronology_types.rb +54 -54
  29. data/lib/env_parser/types/internet_types.rb +50 -50
  30. data/lib/env_parser/types.rb +2 -2
  31. data/lib/env_parser/version.rb +1 -1
  32. data/lib/env_parser.rb +205 -213
  33. data/spec/env_parser/types/base_types_spec.rb +98 -0
  34. data/spec/env_parser/types/chronology_types_spec.rb +49 -0
  35. data/spec/env_parser/types/internet_types_spec.rb +45 -0
  36. data/spec/env_parser_spec.rb +192 -0
  37. data/spec/spec_helper.rb +14 -0
  38. metadata +53 -48
  39. data/.travis.yml +0 -5
data/docs/_index.html CHANGED
@@ -4,7 +4,7 @@
4
4
  <meta charset="utf-8">
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
6
  <title>
7
- Documentation by YARD 0.9.26
7
+ Documentation by YARD 0.9.28
8
8
 
9
9
  </title>
10
10
 
@@ -52,7 +52,7 @@
52
52
  <div class="clear"></div>
53
53
  </div>
54
54
 
55
- <div id="content"><h1 class="noborder title">Documentation by YARD 0.9.26</h1>
55
+ <div id="content"><h1 class="noborder title">Documentation by YARD 0.9.28</h1>
56
56
  <div id="listing">
57
57
  <h1 class="alphaindex">Alphabetic Index</h1>
58
58
 
@@ -69,8 +69,6 @@
69
69
  <h2>Namespace Listing A-Z</h2>
70
70
 
71
71
 
72
- <ul class="toplevel"><li><span class='object_link'><a href="top-level-namespace.html" title="Top Level Namespace (root)">Top Level Namespace</a></span></li></ul>
73
-
74
72
 
75
73
 
76
74
  <table>
@@ -235,9 +233,9 @@
235
233
  </div>
236
234
 
237
235
  <div id="footer">
238
- Generated on Sat Jan 2 17:31:14 2021 by
239
- <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
240
- 0.9.26 (ruby-2.7.2).
236
+ Generated on Sun Dec 25 19:19:23 2022 by
237
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
238
+ 0.9.28 (ruby-3.0.4).
241
239
  </div>
242
240
 
243
241
  </div>
@@ -6,7 +6,7 @@
6
6
  <title>
7
7
  File: README
8
8
 
9
- &mdash; Documentation by YARD 0.9.26
9
+ &mdash; Documentation by YARD 0.9.28
10
10
 
11
11
  </title>
12
12
 
@@ -57,250 +57,348 @@
57
57
  <div class="clear"></div>
58
58
  </div>
59
59
 
60
- <div id="content"><div id='filecontents'>
61
- <p><a href="https://rubygems.org/gems/env_parser"><img src="https://img.shields.io/github/v/release/nestor-custodio/env_parser?color=green&label=gem%20version"></a> <a href="https://github.com/nestor-custodio/env_parser/blob/master/LICENSE.txt"><img src="https://img.shields.io/github/license/nestor-custodio/env_parser"></a></p>
60
+ <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
+ <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>
62
62
 
63
- <h1 id="label-EnvParser">EnvParser</h1>
63
+ <h1 id="envparser">EnvParser</h1>
64
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'] == &#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>
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
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&#39;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>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 youre 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
68
 
69
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
70
 
71
- <h2 id="label-Installation">Installation</h2>
72
- <ul><li>
73
- <p>If your project uses <a href="https://github.com/bundler/bundler">Bundler</a>:</p>
74
- </li><li>
75
- <p>Add one of the following to your application&#39;s Gemfile: "`ruby</p>
71
+ <h2 id="installation">Installation</h2>
76
72
 
77
- <h2 id="label-For+on-demand+usage+...">For on-demand usage ...</h2>
78
-
79
- <p>## gem &#39;env_parser&#39;</p>
80
-
81
- <h2 id="label-To+automatically+register+ENV">To automatically register ENV</h2>
82
-
83
- <h2 id="label-constants+per+-22.env_parser.yml-22+...">constants per ".env_parser.yml" ...</h2>
84
-
85
- <p>## gem &#39;env_parser&#39;, require: &#39;env_parser/autoregister&#39; "`</p>
86
- </li><li>
87
- <p>And then run a: <code>shell $ bundle install </code></p>
88
- </li><li>
89
- <p>Or, you can keep things simple with a manual install: <code>shell $ gem install env_parser </code></p>
90
- </li></ul>
91
-
92
- <h2 id="label-Syntax+Cheat+Sheet">Syntax Cheat Sheet</h2>
73
+ <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>
93
82
 
94
- <pre class="code ruby"><code class="ruby">## Returns an ENV value parsed &quot;as&quot; a specific type:
83
+ <h2 id="to-automatically-register-env">To automatically register ENV</h2>
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>
101
+ </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:
95
107
  ##
96
108
  EnvParser.parse env_key_as_a_symbol
97
109
  as: … ## ➜ required
98
110
  if_unset: … ## ➜ optional; default value
99
111
  from_set: … ## ➜ optional; an Array or Range
100
- validated_by: -&gt;(value) { … } ## ➜ optional; may also be given as a block
112
+ validated_by: -&gt;(value) { … } ## ➜ optional; may also be given as a block</p>
101
113
 
102
- ## Parse an ENV value and register it as a constant:
103
- ##
114
+ <h2 id="parse-an-env-value-and-register-it-as-a-constant">Parse an ENV value and register it as a constant:</h2>
115
+ <p>##
104
116
  EnvParser.register env_key_as_a_symbol
105
117
  as: … ## ➜ required
106
118
  within: … ## ➜ optional; Class or Module
107
119
  if_unset: … ## ➜ optional; default value
108
120
  from_set: … ## ➜ optional; an Array or Range
109
- validated_by: -&gt;(value) { … } ## ➜ optional; may also be given as a block
121
+ validated_by: -&gt;(value) { … } ## ➜ optional; may also be given as a block</p>
110
122
 
111
- ## Registers all ENV variables as spec&#39;ed in &quot;.env_parser.yml&quot;:
112
- ##
123
+ <h2 id="registers-all-env-variables-as-speced-in-envparseryml">Registers all ENV variables as speced in “.env_parser.yml”:</h2>
124
+ <p>##
113
125
  EnvParser.autoregister ## Note this is automatically called if your
114
- ## Gemfile included the &quot;env_parser&quot; gem with
115
- ## the &quot;require: &#39;env_parser/autoregister&#39;&quot; option.
126
+ ## Gemfile included the env_parser gem with
127
+ ## the require: env_parser/autoregister’” option.</p>
116
128
 
117
- ## Lets you call &quot;parse&quot; and &quot;register&quot; on ENV itself:
118
- ##
129
+ <h2 id="lets-you-call-parse-and-register-on-env-itself">Lets you call parse and register on ENV itself:</h2>
130
+ <p>##
119
131
  EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
120
132
  ## and ENV.register will now be a proxy for EnvParser.register
121
- </code></pre>
133
+ ```</p>
134
+
135
+ <h2 id="extended-how-to-use">Extended How-To-Use</h2>
136
+
137
+ <h4 id="basic-usage">Basic Usage</h4>
122
138
 
123
- <h2 id="label-Extended+How-To-Use">Extended How-To-Use</h2>
139
+ <ul>
140
+ <li>
141
+ <p><strong>Parsing <code>ENV</code> Values</strong></p>
124
142
 
125
- <h4 id="label-Basic+Usage">Basic Usage</h4>
126
- <ul><li>
127
- <p><strong>Parsing <code>ENV</code> Values</strong></p>
128
- </li></ul>
143
+ <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>
129
144
 
130
- <p>At its core, EnvParser is a straight-forward parser for string values (since that&#39;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
+ <p><code>ruby
146
+ ## Returns ENV['TIMEOUT_MS'] as an Integer,
147
+ ## or a sensible default (0) if ENV['TIMEOUT_MS'] is unset.
148
+ ##
149
+ timeout_ms = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
150
+ </code></p>
131
151
 
132
- <p><code>ruby ## 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>
152
+ <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>
153
+ </li>
154
+ <li>
155
+ <p><strong>How About Less Typing?</strong></p>
133
156
 
134
- <p>You can check the full documentation for <a href="http://nestor-custodio.github.io/env_parser/EnvParser/Types.html">a list of all as types available right out of the box</a>.</p>
135
- <ul><li>
136
- <p><strong>How About Less Typing?</strong></p>
137
- </li></ul>
157
+ <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>
138
158
 
139
- <p>EnvParser is all about ~simplification~ &lt;s&gt;less typing&lt;/s&gt; <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
+ <p><code>ruby
160
+ ## YAY, LESS TYPING! 😃
161
+ ## These two are the same:
162
+ ##
163
+ more_typing = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
164
+ less_typing = EnvParser.parse :TIMEOUT_MS, as: :integer
165
+ </code></p>
166
+ </li>
167
+ <li>
168
+ <p><strong>Registering Constants From <code>ENV</code> Values</strong></p>
140
169
 
141
- <p><code>ruby ## 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>
142
- <ul><li>
143
- <p><strong>Registering Constants From <code>ENV</code> Values</strong></p>
144
- </li></ul>
170
+ <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>
145
171
 
146
- <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
+ <p>```ruby
173
+ ENV[‘API_KEY’] ## =&gt; ‘unbreakable p4$$w0rd’</p>
147
174
 
148
- <p>“`ruby <a href="'API_KEY'">ENV</a> ## =&gt; &#39;unbreakable p4$$w0rd&#39;</p>
175
+ <p>EnvParser.register :API_KEY, as: :string
176
+ API_KEY ## =&gt; ‘unbreakable p4$$w0rd’
177
+ ```</p>
149
178
 
150
- <p>EnvParser.register :API_KEY, as: :string API_KEY ## =&gt; &#39;unbreakable p4$$w0rd&#39; “`</p>
179
+ <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>
151
180
 
152
- <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
+ <p>```ruby
182
+ ENV[‘BEST_VIDEO’] ## =&gt; ‘https://youtu.be/L_jWHffIx5E’</p>
153
183
 
154
- <p>“`ruby <a href="'BEST_VIDEO'">ENV</a> ## =&gt; &#39;<a href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>&#39;</p>
184
+ <p>EnvParser.register :BEST_VIDEO, as: :string, within: URI
185
+ URI::BEST_VIDEO ## =&gt; ‘https://youtu.be/L_jWHffIx5E’
186
+ BEST_VIDEO ## =&gt; raises NameError
187
+ ```</p>
155
188
 
156
- <p>EnvParser.register :BEST_VIDEO, as: :string, within: URI URI::BEST_VIDEO ## =&gt; &#39;<a href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>&#39; BEST_VIDEO ## =&gt; raises NameError “`</p>
189
+ <p>You can also register multiple constants with a single call, which is a bit cleaner.</p>
157
190
 
158
- <p>You can also register multiple constants with a single call, which is a bit cleaner.</p>
191
+ <p>```ruby
192
+ EnvParser.register :USERNAME, as: :string
193
+ EnvParser.register :PASSWORD, as: :string
194
+ EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
159
195
 
160
- <p>“`ruby EnvParser.register :USERNAME, as: :string EnvParser.register :PASSWORD, as: :string EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
196
+ <h2 id="is-equivalent-to-">… is equivalent to …</h2>
161
197
 
162
- <p>## is equivalent to … ##</p>
198
+ <p>EnvParser.register USERNAME: { as: :string },
199
+ PASSWORD: { as: :string },
200
+ MOCK_API: { as: :boolean, within: MyClassOrModule }
201
+ ```</p>
202
+ </li>
203
+ <li>
204
+ <p><strong>Okay, But… How About Even Less Typing?</strong></p>
163
205
 
164
- <p>EnvParser.register USERNAME: { as: :string }, PASSWORD: { as: :string }, MOCK_API: { as: :boolean, within: MyClassOrModule } “`</p>
165
- <ul><li>
166
- <p><strong>Okay, But… How About Even Less Typing?</strong></p>
167
- </li></ul>
206
+ <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>
168
207
 
169
- <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>
208
+ <p>```ruby
209
+ ENV[‘SHORT_PI’] ## =&gt; ‘3.1415926’
210
+ ENV[‘BETTER_PI’] ## =&gt; ‘[“flaky crust”, “strawberry filling”]’</p>
170
211
 
171
- <p>“`ruby <a href="'SHORT_PI'">ENV</a> ## =&gt; &#39;3.1415926&#39; <a href="'BETTER_PI'">ENV</a> ## =&gt; &#39;[“flaky crust”, “strawberry filling”]&#39;</p>
212
+ <h2 id="bind-the-proxy-methods">Bind the proxy methods.</h2>
213
+ <p>##
214
+ EnvParser.add_env_bindings</p>
172
215
 
173
- <p>## Bind the proxy methods. ## EnvParser.add_env_bindings</p>
216
+ <p>ENV.parse :SHORT_PI, as: :float ## =&gt; 3.1415926
217
+ ENV.register :BETTER_PI, as: :array ## Your constant is set!
218
+ ```</p>
174
219
 
175
- <p>ENV.parse :SHORT_PI, as: :float ## =&gt; 3.1415926 ENV.register :BETTER_PI, as: :array ## Your constant is set! “`</p>
220
+ <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>
176
221
 
177
- <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>
222
+ <p>```ruby
223
+ ENV[‘SHORT_PI’] ## =&gt; ‘3.1415926’</p>
178
224
 
179
- <p>“`ruby <a href="'SHORT_PI'">ENV</a> ## =&gt; &#39;3.1415926&#39;</p>
225
+ <p>EnvParser.parse SHORT_PI’, as: :float ## =&gt; ‘SHORT_PI’ as a float: 0.0
226
+ EnvParser.parse :SHORT_PI , as: :float ## =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926</p>
180
227
 
181
- <p>EnvParser.parse &#39;SHORT_PI&#39;, as: :float ## =&gt; &#39;SHORT_PI&#39; as a float: 0.0 EnvParser.parse :SHORT_PI , as: :float ## =&gt; <a href="'SHORT_PI'">ENV</a> as a float: 3.1415926</p>
228
+ <h2 id="bind-the-proxy-methods-1">Bind the proxy methods.</h2>
229
+ <p>##
230
+ EnvParser.add_env_bindings</p>
182
231
 
183
- <p>## Bind the proxy methods. ## EnvParser.add_env_bindings</p>
232
+ <p>ENV.parse ‘SHORT_PI’, as: :float ## =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926
233
+ ENV.parse :SHORT_PI , as: :float ## =&gt; ENV[‘SHORT_PI’] as a float: 3.1415926
234
+ ```</p>
184
235
 
185
- <p>ENV.parse &#39;SHORT_PI&#39;, as: :float ## =&gt; <a href="'SHORT_PI'">ENV</a> as a float: 3.1415926 ENV.parse :SHORT_PI , as: :float ## =&gt; <a href="'SHORT_PI'">ENV</a> as a float: 3.1415926 “`</p>
236
+ <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>
186
237
 
187
- <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>
238
+ <p><strong>All additional examples below will assume that <code>ENV</code> bindings are already in place, for brevity’s sake.</strong></p>
239
+ </li>
240
+ </ul>
188
241
 
189
- <p><strong>All additional examples below will assume that <code>ENV</code> bindings are already in place, for brevity&#39;s sake.</strong></p>
242
+ <h4 id="ensuring-usable-values">Ensuring Usable Values</h4>
190
243
 
191
- <h4 id="label-Ensuring+Usable+Values">Ensuring Usable Values</h4>
192
- <ul><li>
193
- <p><strong>Sensible Defaults</strong></p>
194
- </li></ul>
244
+ <ul>
245
+ <li>
246
+ <p><strong>Sensible Defaults</strong></p>
195
247
 
196
- <p>If the <code>ENV</code> variable you want is unset (<code>nil</code>) or blank (<code>&#39;&#39;</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>
248
+ <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>
197
249
 
198
- <p><code>ruby ENV.parse :MISSING_VAR, as: :integer ## =&gt; 0 ENV.parse :MISSING_VAR, as: :integer, if_unset: 250 ## =&gt; 250 </code></p>
250
+ <p><code>ruby
251
+ ENV.parse :MISSING_VAR, as: :integer ## =&gt; 0
252
+ ENV.parse :MISSING_VAR, as: :integer, if_unset: 250 ## =&gt; 250
253
+ </code></p>
199
254
 
200
- <p>Note these default values are used as-is with no type conversion, so exercise caution.</p>
255
+ <p>Note these default values are used as-is with no type conversion, so exercise caution.</p>
201
256
 
202
- <p><code>ruby ENV.parse :MISSING_VAR, as: :integer, if_unset: &#39;Careful!&#39; ## =&gt; &#39;Careful!&#39; (NOT AN INTEGER) </code></p>
203
- <ul><li>
204
- <p><strong>Selecting From A Set</strong></p>
205
- </li></ul>
257
+ <p><code>ruby
258
+ ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!' ## =&gt; 'Careful!' (NOT AN INTEGER)
259
+ </code></p>
260
+ </li>
261
+ <li>
262
+ <p><strong>Selecting From A Set</strong></p>
206
263
 
207
- <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>
264
+ <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>
208
265
 
209
- <p>“`ruby 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>
266
+ <p>```ruby
267
+ ENV.parse :API_TO_USE, as: :symbol, from_set: %i[internal external]
268
+ ENV.parse :NETWORK_PORT, as: :integer, from_set: (1..65535), if_unset: 80</p>
210
269
 
211
- <p>## And if the value is not in the allowed set … ## ENV.parse :TWELVE, as: :integer, from_set: (1..5) ## =&gt; raises EnvParser::ValueNotAllowedError “`</p>
212
- <ul><li>
213
- <p><strong>Custom Validation Of Parsed Values</strong></p>
214
- </li></ul>
270
+ <h2 id="and-if-the-value-is-not-in-the-allowed-set-">And if the value is not in the allowed set …</h2>
271
+ <p>##
272
+ ENV.parse :TWELVE, as: :integer, from_set: (1..5) ## =&gt; raises EnvParser::ValueNotAllowedError
273
+ ```</p>
274
+ </li>
275
+ <li>
276
+ <p><strong>Custom Validation Of Parsed Values</strong></p>
215
277
 
216
- <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>
278
+ <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>
217
279
 
218
- <p>“`ruby ## Via a “validated_by” lambda … ## ENV.parse :MUST_BE_LOWERCASE, as: :string, validated_by: -&gt;(value) { value == value.downcase }</p>
280
+ <p>```ruby
281
+ ## Via a “validated_by” lambda …
282
+ ##
283
+ ENV.parse :MUST_BE_LOWERCASE, as: :string, validated_by: -&gt;(value) { value == value.downcase }</p>
219
284
 
220
- <p>## or with a block! ## ENV.parse(:MUST_BE_LOWERCASE, as: :string) { |value| value == value.downcase } ENV.parse(:CONNECTION_RETRIES, as: :integer, &amp;:positive?) “`</p>
221
- <ul><li>
222
- <p><strong>Defining Your Own EnvParser “<em>as</em>” Types</strong></p>
223
- </li></ul>
285
+ <h2 id="or-with-a-block">… or with a block!</h2>
286
+ <p>##
287
+ ENV.parse(:MUST_BE_LOWERCASE, as: :string) { |value| value == value.downcase }
288
+ ENV.parse(:CONNECTION_RETRIES, as: :integer, &amp;:positive?)
289
+ ```</p>
290
+ </li>
291
+ <li>
292
+ <p><strong>Defining Your Own EnvParser “<em>as</em>” Types</strong></p>
224
293
 
225
- <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&#39;t littered with type-checking cruft).</p>
294
+ <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 arent littered with type-checking cruft).</p>
226
295
 
227
- <p>Something as repetitive as:</p>
296
+ <p>Something as repetitive as:</p>
228
297
 
229
- <p>“`ruby a = ENV.parse :A, as: :int, if_unset: 6 raise unless passes_all_my_checks?(a)</p>
298
+ <p>```ruby
299
+ a = ENV.parse :A, as: :int, if_unset: 6
300
+ raise unless passes_all_my_checks?(a)</p>
230
301
 
231
- <p>b = ENV.parse :B, as: :int, if_unset: 6 raise unless passes_all_my_checks?(b) “`</p>
302
+ <p>b = ENV.parse :B, as: :int, if_unset: 6
303
+ raise unless passes_all_my_checks?(b)
304
+ ```</p>
232
305
 
233
- <p>… is perhaps best handled by defining a new type:</p>
306
+ <p>… is perhaps best handled by defining a new type:</p>
234
307
 
235
- <p>“`ruby EnvParser.define_type(:my_special_type_of_number, if_unset: 6) do |value| value = value.to_i unless passes_all_my_checks?(value) raise(EnvParser::ValueNotConvertibleError, &#39;cannot parse as a “special type number”&#39;) end</p>
308
+ <p>```ruby
309
+ EnvParser.define_type(:my_special_type_of_number, if_unset: 6) do |value|
310
+ value = value.to_i
311
+ unless passes_all_my_checks?(value)
312
+ raise(EnvParser::ValueNotConvertibleError, ‘cannot parse as a “special type number”’)
313
+ end</p>
236
314
 
237
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_value'>value</span>
238
- </code></pre>
315
+ <p>value
316
+ end</p>
239
317
 
240
- <p>end</p>
318
+ <p>a = ENV.parse :A, as: :my_special_type_of_number
319
+ b = ENV.parse :B, as: :my_special_type_of_number
320
+ ```</p>
321
+ </li>
322
+ </ul>
241
323
 
242
- <p>a = ENV.parse :A, as: :my_special_type_of_number b = ENV.parse :B, as: :my_special_type_of_number “`</p>
324
+ <h4 id="auto-registering-constants">Auto-Registering Constants</h4>
243
325
 
244
- <h4 id="label-Auto-Registering+Constants">Auto-Registering Constants</h4>
245
- <ul><li>
246
- <p><strong>The <code>autoregister</code> Call</strong></p>
247
- </li></ul>
326
+ <ul>
327
+ <li>
328
+ <p><strong>The <code>autoregister</code> Call</strong></p>
248
329
 
249
- <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>&quot;.env_parser.yml&quot;</code> is assumed.</p>
330
+ <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>
250
331
 
251
- <p>You&#39;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 &#39;bundler/setup&#39;</code>), requiring the EnvParser gem via …</p>
332
+ <p>Youll 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>
252
333
 
253
- <p><code>ruby gem &#39;env_parser&#39;, require: &#39;env_parser/autoregister&#39; </code></p>
334
+ <p><code>ruby
335
+ gem 'env_parser', require: 'env_parser/autoregister'
336
+ </code></p>
254
337
 
255
- <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 &#39;env_parser/autoregister&#39;</code> yourself even before <code>bundler/setup</code> is invoked.</p>
256
- <ul><li>
257
- <p><strong>The “.env_parser.yml” File</strong></p>
258
- </li></ul>
338
+ <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>
339
+ </li>
340
+ <li>
341
+ <p><strong>The “.env_parser.yml” File</strong></p>
259
342
 
260
- <p>If you recall, multiple constants can be registered via a single <code>EnvParser.register</code> call:</p>
343
+ <p>If you recall, multiple constants can be registered via a single <code>EnvParser.register</code> call:</p>
261
344
 
262
- <p>“`ruby EnvParser.register :USERNAME, as: :string EnvParser.register :PASSWORD, as: :string EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
345
+ <p>```ruby
346
+ EnvParser.register :USERNAME, as: :string
347
+ EnvParser.register :PASSWORD, as: :string
348
+ EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
263
349
 
264
- <p>## is equivalent to … ##</p>
350
+ <h2 id="is-equivalent-to--1">… is equivalent to …</h2>
265
351
 
266
- <p>EnvParser.register USERNAME: { as: :string }, PASSWORD: { as: :string }, MOCK_API: { as: :boolean, within: MyClassOrModule } “`</p>
352
+ <p>EnvParser.register USERNAME: { as: :string },
353
+ PASSWORD: { as: :string },
354
+ MOCK_API: { as: :boolean, within: MyClassOrModule }
355
+ ```</p>
267
356
 
268
- <p>The autoregistraton file is intended to read as a YAML version of what you&#39;d pass to the single-call version of <code>EnvParser.register</code>: a single hash with keys for each of the constants you&#39;d like to register, with each value being the set of options to parse that constant.</p>
357
+ <p>The autoregistraton file is intended to read as a YAML version of what youd pass to the single-call version of <code>EnvParser.register</code>: a single hash with keys for each of the constants youd like to register, with each value being the set of options to parse that constant.</p>
269
358
 
270
- <p>The equivalent autoregistration file for the above would be:</p>
359
+ <p>The equivalent autoregistration file for the above would be:</p>
271
360
 
272
- <p>“`yaml USERNAME: as: :string</p>
361
+ <p>```yaml
362
+ USERNAME:
363
+ as: :string</p>
273
364
 
274
- <p>PASSWORD: as: :string</p>
365
+ <p>PASSWORD:
366
+ as: :string</p>
275
367
 
276
- <p>MOCK_API: as: :boolean within: MyClassOrModule “`</p>
368
+ <p>MOCK_API:
369
+ as: :boolean
370
+ within: MyClassOrModule
371
+ ```</p>
277
372
 
278
- <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>
373
+ <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>
374
+ </li>
375
+ </ul>
279
376
 
280
- <h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
377
+ <h2 id="feature-roadmap--future-development">Feature Roadmap / Future Development</h2>
281
378
 
282
379
  <p>Additional features coming in the future:</p>
283
- <ul><li>
284
- <p>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.</p>
285
- </li></ul>
286
380
 
287
- <h2 id="label-Contribution+-2F+Development">Contribution / Development</h2>
381
+ <ul>
382
+ <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>
383
+ </ul>
384
+
385
+ <h2 id="contribution--development">Contribution / Development</h2>
288
386
 
289
- <p>Bug reports and pull requests are welcome at: <a href="https://github.com/nestor-custodio/env_parser">github.com/nestor-custodio/env_parser</a></p>
387
+ <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>
290
388
 
291
389
  <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>
292
390
 
293
391
  <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>
294
392
 
295
- <h2 id="label-License">License</h2>
393
+ <h2 id="license">License</h2>
296
394
 
297
395
  <p>EnvParser is available as open source under the terms of the <a href="https://tldrlegal.com/license/mit-license">MIT License</a>.</p>
298
396
  </div></div>
299
397
 
300
398
  <div id="footer">
301
- Generated on Sat Jan 2 17:31:17 2021 by
302
- <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
303
- 0.9.26 (ruby-2.7.2).
399
+ Generated on Sun Dec 25 19:19:23 2022 by
400
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
401
+ 0.9.28 (ruby-3.0.4).
304
402
  </div>
305
403
 
306
404
  </div>
data/docs/frames.html CHANGED
@@ -2,7 +2,7 @@
2
2
  <html>
3
3
  <head>
4
4
  <meta charset="utf-8">
5
- <title>Documentation by YARD 0.9.26</title>
5
+ <title>Documentation by YARD 0.9.28</title>
6
6
  </head>
7
7
  <script type="text/javascript">
8
8
  var match = unescape(window.location.hash).match(/^#!(.+)/);