env_parser 1.3.0 → 1.3.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/.circleci/config.yml +1 -1
- data/.rubocop.yml +15 -7
- data/.ruby-version +1 -1
- data/Gemfile.lock +47 -41
- data/docs/EnvParser.html +39 -98
- data/docs/EnvParser/AutoregisterFileNotFound.html +7 -8
- data/docs/EnvParser/Error.html +6 -6
- data/docs/EnvParser/TypeAlreadyDefinedError.html +6 -6
- data/docs/EnvParser/Types.html +7 -8
- data/docs/EnvParser/Types/BaseTypes.html +7 -8
- data/docs/EnvParser/Types/ChronologyTypes.html +6 -6
- data/docs/EnvParser/Types/InternetTypes.html +6 -6
- data/docs/EnvParser/UnknownTypeError.html +6 -6
- data/docs/EnvParser/UnparseableAutoregisterSpec.html +7 -8
- data/docs/EnvParser/ValueNotAllowedError.html +7 -9
- data/docs/EnvParser/ValueNotConvertibleError.html +7 -8
- data/docs/_index.html +7 -7
- data/docs/class_list.html +2 -2
- data/docs/css/style.css +3 -2
- data/docs/file.README.html +67 -195
- data/docs/file_list.html +2 -2
- data/docs/frames.html +2 -2
- data/docs/index.html +67 -195
- data/docs/js/app.js +14 -3
- data/docs/method_list.html +2 -2
- data/docs/top-level-namespace.html +6 -6
- data/env_parser.gemspec +3 -3
- data/lib/env_parser.rb +1 -4
- data/lib/env_parser/types/chronology_types.rb +1 -1
- data/lib/env_parser/types/internet_types.rb +1 -1
- data/lib/env_parser/version.rb +1 -1
- metadata +13 -14
data/docs/frames.html
CHANGED
@@ -2,9 +2,9 @@
|
|
2
2
|
<html>
|
3
3
|
<head>
|
4
4
|
<meta charset="utf-8">
|
5
|
-
<title>Documentation by YARD 0.9.
|
5
|
+
<title>Documentation by YARD 0.9.26</title>
|
6
6
|
</head>
|
7
|
-
<script type="text/javascript"
|
7
|
+
<script type="text/javascript">
|
8
8
|
var match = unescape(window.location.hash).match(/^#!(.+)/);
|
9
9
|
var name = match ? match[1] : 'index.html';
|
10
10
|
name = name.replace(/^(\w+):\/\//, '').replace(/^\/\//, '');
|
data/docs/index.html
CHANGED
@@ -6,15 +6,15 @@
|
|
6
6
|
<title>
|
7
7
|
File: README
|
8
8
|
|
9
|
-
— Documentation by YARD 0.9.
|
9
|
+
— Documentation by YARD 0.9.26
|
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
|
-
<script type="text/javascript"
|
17
|
+
<script type="text/javascript">
|
18
18
|
pathId = "README";
|
19
19
|
relpath = '';
|
20
20
|
</script>
|
@@ -58,38 +58,19 @@
|
|
58
58
|
</div>
|
59
59
|
|
60
60
|
<div id="content"><div id='filecontents'>
|
61
|
-
<p><a href="https://rubygems.org/gems/env_parser"><img
|
62
|
-
src="https://img.shields.io/github/v/release/nestor-custodio/env_parser?color=green&label=gem%20version"></a>
|
63
|
-
<a
|
64
|
-
href="https://github.com/nestor-custodio/env_parser/blob/master/LICENSE.txt"><img
|
65
|
-
src="https://img.shields.io/github/license/nestor-custodio/env_parser"></a></p>
|
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>
|
66
62
|
|
67
63
|
<h1 id="label-EnvParser">EnvParser</h1>
|
68
64
|
|
69
|
-
<p>If your code uses environment variables, you know that <code>ENV</code>
|
70
|
-
|
71
|
-
|
72
|
-
|
73
|
-
|
74
|
-
'true'</code>) … maybe you want to set non-trivial defaults
|
75
|
-
(something other than <code>0</code> or <code>''</code>)? … maybe
|
76
|
-
you only want to allow values from a limited set? …</p>
|
77
|
-
|
78
|
-
<p>Things can get out of control pretty fast, especially as the number of
|
79
|
-
environment variables in play grows. Tools like <a
|
80
|
-
href="https://github.com/bkeepers/dotenv">dotenv</a> help to make sure
|
81
|
-
you're loading the correct <strong>set</strong> of variables, but <a
|
82
|
-
href="https://github.com/nestor-custodio/env_parser">EnvParser</a> makes
|
83
|
-
<strong>the values themselves</strong> usable with a minimum of effort.</p>
|
84
|
-
|
85
|
-
<p><a href="http://nestor-custodio.github.io/env_parser/EnvParser.html">Full
|
86
|
-
documentation is available here</a>, but do read below for a crash course
|
87
|
-
on availble featues!</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
|
+
|
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>
|
88
70
|
|
89
71
|
<h2 id="label-Installation">Installation</h2>
|
90
72
|
<ul><li>
|
91
|
-
<p>If your project uses <a
|
92
|
-
href="https://github.com/bundler/bundler">Bundler</a>:</p>
|
73
|
+
<p>If your project uses <a href="https://github.com/bundler/bundler">Bundler</a>:</p>
|
93
74
|
</li><li>
|
94
75
|
<p>Add one of the following to your application's Gemfile: "`ruby</p>
|
95
76
|
|
@@ -105,8 +86,7 @@ href="https://github.com/bundler/bundler">Bundler</a>:</p>
|
|
105
86
|
</li><li>
|
106
87
|
<p>And then run a: <code>shell $ bundle install </code></p>
|
107
88
|
</li><li>
|
108
|
-
<p>Or, you can keep things simple with a manual install: <code>shell $ gem
|
109
|
-
install env_parser </code></p>
|
89
|
+
<p>Or, you can keep things simple with a manual install: <code>shell $ gem install env_parser </code></p>
|
110
90
|
</li></ul>
|
111
91
|
|
112
92
|
<h2 id="label-Syntax+Cheat+Sheet">Syntax Cheat Sheet</h2>
|
@@ -147,236 +127,145 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
147
127
|
<p><strong>Parsing <code>ENV</code> Values</strong></p>
|
148
128
|
</li></ul>
|
149
129
|
|
150
|
-
<p>At its core, EnvParser is a straight-forward parser for string values
|
151
|
-
(since that's all <code>ENV</code> ever gives you), allowing you to
|
152
|
-
read a given string <strong><em>as</em></strong> a variety of types.</p>
|
130
|
+
<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>
|
153
131
|
|
154
|
-
<p><code>ruby ## Returns ENV['TIMEOUT_MS'] as an Integer, ## or a sensible
|
155
|
-
default (0) if ENV['TIMEOUT_MS'] is unset. ## timeout_ms =
|
156
|
-
EnvParser.parse ENV['TIMEOUT_MS'], as: :integer </code></p>
|
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>
|
157
133
|
|
158
|
-
<p>You can check the full documentation for <a
|
159
|
-
href="http://nestor-custodio.github.io/env_parser/EnvParser/Types.html">a
|
160
|
-
list of all as types available right out of the box</a>.</p>
|
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>
|
161
135
|
<ul><li>
|
162
136
|
<p><strong>How About Less Typing?</strong></p>
|
163
137
|
</li></ul>
|
164
138
|
|
165
|
-
<p>EnvParser is all about
|
166
|
-
<em>laziness</em>. If you pass in a symbol instead of a string, EnvParser
|
167
|
-
will look to <code>ENV</code> and use the value from the corresponding
|
168
|
-
(string) key.</p>
|
139
|
+
<p>EnvParser is all about ~simplification~ <s>less typing</s> <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>
|
169
140
|
|
170
|
-
<p><code>ruby ## YAY, LESS TYPING! 😃 ## These two are the same: ##
|
171
|
-
more_typing = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer less_typing
|
172
|
-
= EnvParser.parse :TIMEOUT_MS, as: :integer </code></p>
|
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>
|
173
142
|
<ul><li>
|
174
143
|
<p><strong>Registering Constants From <code>ENV</code> Values</strong></p>
|
175
144
|
</li></ul>
|
176
145
|
|
177
|
-
<p>The <code>EnvParser.register</code> method lets you “promote”
|
178
|
-
<code>ENV</code> variables into their own constants, already parsed into
|
179
|
-
the correct type.</p>
|
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>
|
180
147
|
|
181
148
|
<p>“`ruby <a href="'API_KEY'">ENV</a> ## => 'unbreakable p4$$w0rd'</p>
|
182
149
|
|
183
|
-
<p>EnvParser.register :API_KEY, as: :string API_KEY ## => 'unbreakable
|
184
|
-
p4$$w0rd' “`</p>
|
150
|
+
<p>EnvParser.register :API_KEY, as: :string API_KEY ## => 'unbreakable p4$$w0rd' “`</p>
|
185
151
|
|
186
|
-
<p>By default, <code>EnvParser.register</code> will create the requested
|
187
|
-
constant within the Kernel module (making it available everywhere), but you
|
188
|
-
can specify any class or module you like.</p>
|
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>
|
189
153
|
|
190
|
-
<p>“`ruby <a href="'BEST_VIDEO'">ENV</a> ## => '<a
|
191
|
-
href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>'</p>
|
154
|
+
<p>“`ruby <a href="'BEST_VIDEO'">ENV</a> ## => '<a href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>'</p>
|
192
155
|
|
193
|
-
<p>EnvParser.register :BEST_VIDEO, as: :string, within: URI URI::BEST_VIDEO
|
194
|
-
## => '<a
|
195
|
-
href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>'
|
196
|
-
BEST_VIDEO ## => raises NameError “`</p>
|
156
|
+
<p>EnvParser.register :BEST_VIDEO, as: :string, within: URI URI::BEST_VIDEO ## => '<a href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>' BEST_VIDEO ## => raises NameError “`</p>
|
197
157
|
|
198
|
-
<p>You can also register multiple constants with a single call, which is a bit
|
199
|
-
cleaner.</p>
|
158
|
+
<p>You can also register multiple constants with a single call, which is a bit cleaner.</p>
|
200
159
|
|
201
|
-
<p>“`ruby EnvParser.register :USERNAME, as: :string EnvParser.register
|
202
|
-
:PASSWORD, as: :string EnvParser.register :MOCK_API, as: :boolean, within:
|
203
|
-
MyClassOrModule }</p>
|
160
|
+
<p>“`ruby EnvParser.register :USERNAME, as: :string EnvParser.register :PASSWORD, as: :string EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
|
204
161
|
|
205
162
|
<p>## … is equivalent to … ##</p>
|
206
163
|
|
207
|
-
<p>EnvParser.register USERNAME: { as: :string }, PASSWORD: { as: :string },
|
208
|
-
MOCK_API: { as: :boolean, within: MyClassOrModule } “`</p>
|
164
|
+
<p>EnvParser.register USERNAME: { as: :string }, PASSWORD: { as: :string }, MOCK_API: { as: :boolean, within: MyClassOrModule } “`</p>
|
209
165
|
<ul><li>
|
210
166
|
<p><strong>Okay, But… How About Even Less Typing?</strong></p>
|
211
167
|
</li></ul>
|
212
168
|
|
213
|
-
<p>Calling <code>EnvParser.add_env_bindings</code> binds proxy
|
214
|
-
<code>parse</code> and <code>register</code> methods onto <code>ENV</code>.
|
215
|
-
With these bindings in place, you can call <code>parse</code> or
|
216
|
-
<code>register</code> on <code>ENV</code> itself, which is more legible and
|
217
|
-
feels more straight-forward.</p>
|
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>
|
218
170
|
|
219
|
-
<p>“`ruby <a href="'SHORT_PI'">ENV</a> ## => '3.1415926' <a
|
220
|
-
href="'BETTER_PI'">ENV</a> ## => '[“flaky crust”, “strawberry
|
221
|
-
filling”]'</p>
|
171
|
+
<p>“`ruby <a href="'SHORT_PI'">ENV</a> ## => '3.1415926' <a href="'BETTER_PI'">ENV</a> ## => '[“flaky crust”, “strawberry filling”]'</p>
|
222
172
|
|
223
173
|
<p>## Bind the proxy methods. ## EnvParser.add_env_bindings</p>
|
224
174
|
|
225
|
-
<p>ENV.parse :SHORT_PI, as: :float ## => 3.1415926 ENV.register
|
226
|
-
:BETTER_PI, as: :array ## Your constant is set! “`</p>
|
175
|
+
<p>ENV.parse :SHORT_PI, as: :float ## => 3.1415926 ENV.register :BETTER_PI, as: :array ## Your constant is set! “`</p>
|
227
176
|
|
228
|
-
<p>Note that the proxy <code>ENV.parse</code> method will (naturally)
|
229
|
-
<em>always</em> interpret the value given as an <code>ENV</code> key
|
230
|
-
(converting it to a string, if necessary), which is slightly different from
|
231
|
-
the original <code>EnvParser.parse</code> method.</p>
|
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>
|
232
178
|
|
233
179
|
<p>“`ruby <a href="'SHORT_PI'">ENV</a> ## => '3.1415926'</p>
|
234
180
|
|
235
|
-
<p>EnvParser.parse 'SHORT_PI', as: :float ## => 'SHORT_PI'
|
236
|
-
as a float: 0.0 EnvParser.parse :SHORT_PI , as: :float ## => <a
|
237
|
-
href="'SHORT_PI'">ENV</a> as a float: 3.1415926</p>
|
181
|
+
<p>EnvParser.parse 'SHORT_PI', as: :float ## => 'SHORT_PI' as a float: 0.0 EnvParser.parse :SHORT_PI , as: :float ## => <a href="'SHORT_PI'">ENV</a> as a float: 3.1415926</p>
|
238
182
|
|
239
183
|
<p>## Bind the proxy methods. ## EnvParser.add_env_bindings</p>
|
240
184
|
|
241
|
-
<p>ENV.parse 'SHORT_PI', as: :float ## => <a
|
242
|
-
href="'SHORT_PI'">ENV</a> as a float: 3.1415926 ENV.parse :SHORT_PI , as:
|
243
|
-
:float ## => <a href="'SHORT_PI'">ENV</a> as a float: 3.1415926 “`</p>
|
185
|
+
<p>ENV.parse 'SHORT_PI', as: :float ## => <a href="'SHORT_PI'">ENV</a> as a float: 3.1415926 ENV.parse :SHORT_PI , as: :float ## => <a href="'SHORT_PI'">ENV</a> as a float: 3.1415926 “`</p>
|
244
186
|
|
245
|
-
<p>Note also that the <code>ENV.parse</code> and <code>ENV.register</code>
|
246
|
-
binding is done safely and without polluting the method space for other
|
247
|
-
objects.</p>
|
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>
|
248
188
|
|
249
|
-
<p><strong>All additional examples below will assume that <code>ENV</code>
|
250
|
-
bindings are already in place, for brevity's sake.</strong></p>
|
189
|
+
<p><strong>All additional examples below will assume that <code>ENV</code> bindings are already in place, for brevity's sake.</strong></p>
|
251
190
|
|
252
191
|
<h4 id="label-Ensuring+Usable+Values">Ensuring Usable Values</h4>
|
253
192
|
<ul><li>
|
254
193
|
<p><strong>Sensible Defaults</strong></p>
|
255
194
|
</li></ul>
|
256
195
|
|
257
|
-
<p>If the <code>ENV</code> variable you want is unset (<code>nil</code>) or
|
258
|
-
blank (<code>''</code>), the return value is a sensible default for
|
259
|
-
the given <strong><em>as</em></strong> type: 0 or 0.0 for numbers, an empty
|
260
|
-
string/array/hash, etc. Sometimes you want a non-trivial default, however.
|
261
|
-
The <strong><em>if_unset</em></strong> option lets you specify a default
|
262
|
-
that better meets your needs.</p>
|
196
|
+
<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>
|
263
197
|
|
264
|
-
<p><code>ruby ENV.parse :MISSING_VAR, as: :integer ## => 0 ENV.parse
|
265
|
-
:MISSING_VAR, as: :integer, if_unset: 250 ## => 250 </code></p>
|
198
|
+
<p><code>ruby ENV.parse :MISSING_VAR, as: :integer ## => 0 ENV.parse :MISSING_VAR, as: :integer, if_unset: 250 ## => 250 </code></p>
|
266
199
|
|
267
|
-
<p>Note these default values are used as-is with no type conversion, so
|
268
|
-
exercise caution.</p>
|
200
|
+
<p>Note these default values are used as-is with no type conversion, so exercise caution.</p>
|
269
201
|
|
270
|
-
<p><code>ruby ENV.parse :MISSING_VAR, as: :integer, if_unset:
|
271
|
-
'Careful!' ## => 'Careful!' (NOT AN INTEGER) </code></p>
|
202
|
+
<p><code>ruby ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!' ## => 'Careful!' (NOT AN INTEGER) </code></p>
|
272
203
|
<ul><li>
|
273
204
|
<p><strong>Selecting From A Set</strong></p>
|
274
205
|
</li></ul>
|
275
206
|
|
276
|
-
<p>Sometimes setting the <strong><em>as</em></strong> type is a bit too
|
277
|
-
open-ended. The <strong><em>from_set</em></strong> option lets you restrict
|
278
|
-
the domain of allowed values.</p>
|
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>
|
279
208
|
|
280
|
-
<p>“`ruby 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>
|
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>
|
282
210
|
|
283
|
-
<p>## And if the value is not in the allowed set … ## ENV.parse :TWELVE, as:
|
284
|
-
:integer, from_set: (1..5) ## => raises EnvParser::ValueNotAllowedError
|
285
|
-
“`</p>
|
211
|
+
<p>## And if the value is not in the allowed set … ## ENV.parse :TWELVE, as: :integer, from_set: (1..5) ## => raises EnvParser::ValueNotAllowedError “`</p>
|
286
212
|
<ul><li>
|
287
213
|
<p><strong>Custom Validation Of Parsed Values</strong></p>
|
288
214
|
</li></ul>
|
289
215
|
|
290
|
-
<p>You can write your own, more complex validations by passing in a
|
291
|
-
<strong><em>validated_by</em></strong> lambda or an equivalent block. The
|
292
|
-
lambda/block should take one value and return true if the given value
|
293
|
-
passes the custom validation.</p>
|
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>
|
294
217
|
|
295
|
-
<p>“`ruby ## Via a “validated_by” lambda … ## ENV.parse :MUST_BE_LOWERCASE,
|
296
|
-
as: :string, validated_by: ->(value) { value == value.downcase }</p>
|
218
|
+
<p>“`ruby ## Via a “validated_by” lambda … ## ENV.parse :MUST_BE_LOWERCASE, as: :string, validated_by: ->(value) { value == value.downcase }</p>
|
297
219
|
|
298
|
-
<p>## … or with a block! ## ENV.parse(:MUST_BE_LOWERCASE, as: :string) {
|
299
|
-
|value| value == value.downcase } ENV.parse(:CONNECTION_RETRIES, as:
|
300
|
-
:integer, &:positive?) “`</p>
|
220
|
+
<p>## … or with a block! ## ENV.parse(:MUST_BE_LOWERCASE, as: :string) { |value| value == value.downcase } ENV.parse(:CONNECTION_RETRIES, as: :integer, &:positive?) “`</p>
|
301
221
|
<ul><li>
|
302
222
|
<p><strong>Defining Your Own EnvParser “<em>as</em>” Types</strong></p>
|
303
223
|
</li></ul>
|
304
224
|
|
305
|
-
<p>If you use a particular validation many times or are often manipulating
|
306
|
-
values in the same way after EnvParser has done its thing, you may want to
|
307
|
-
register a new type altogether. Defining a new type makes your code both
|
308
|
-
more maintainable (all the logic for your special type is only defined
|
309
|
-
once) and more readable (your <code>parse</code> calls aren't littered
|
310
|
-
with type-checking cruft).</p>
|
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't littered with type-checking cruft).</p>
|
311
226
|
|
312
227
|
<p>Something as repetitive as:</p>
|
313
228
|
|
314
|
-
<p>“`ruby a = ENV.parse :A, as: :int, if_unset: 6 raise unless
|
315
|
-
passes_all_my_checks?(a)</p>
|
229
|
+
<p>“`ruby a = ENV.parse :A, as: :int, if_unset: 6 raise unless passes_all_my_checks?(a)</p>
|
316
230
|
|
317
|
-
<p>b = ENV.parse :B, as: :int, if_unset: 6 raise unless
|
318
|
-
passes_all_my_checks?(b) “`</p>
|
231
|
+
<p>b = ENV.parse :B, as: :int, if_unset: 6 raise unless passes_all_my_checks?(b) “`</p>
|
319
232
|
|
320
233
|
<p>… is perhaps best handled by defining a new type:</p>
|
321
234
|
|
322
|
-
<p>“`ruby EnvParser.define_type(:my_special_type_of_number, if_unset: 6) do
|
323
|
-
|value| value = value.to_i unless passes_all_my_checks?(value)
|
324
|
-
raise(EnvParser::ValueNotConvertibleError, 'cannot parse as a “special
|
325
|
-
type number”') end</p>
|
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, 'cannot parse as a “special type number”') end</p>
|
326
236
|
|
327
237
|
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_value'>value</span>
|
328
238
|
</code></pre>
|
329
239
|
|
330
240
|
<p>end</p>
|
331
241
|
|
332
|
-
<p>a = ENV.parse :A, as: :my_special_type_of_number b = ENV.parse :B, as:
|
333
|
-
:my_special_type_of_number “`</p>
|
242
|
+
<p>a = ENV.parse :A, as: :my_special_type_of_number b = ENV.parse :B, as: :my_special_type_of_number “`</p>
|
334
243
|
|
335
244
|
<h4 id="label-Auto-Registering+Constants">Auto-Registering Constants</h4>
|
336
245
|
<ul><li>
|
337
246
|
<p><strong>The <code>autoregister</code> Call</strong></p>
|
338
247
|
</li></ul>
|
339
248
|
|
340
|
-
<p>Consolidating all of your <code>EnvParser.register</code> calls into a
|
341
|
-
|
342
|
-
call
|
343
|
-
|
344
|
-
<code
|
345
|
-
|
346
|
-
<p>
|
347
|
-
early in your application as possible. For Rails applications (and other
|
348
|
-
frameworks that call <code>require 'bundler/setup'</code>),
|
349
|
-
requiring the EnvParser gem via …</p>
|
350
|
-
|
351
|
-
<p><code>ruby gem 'env_parser', require:
|
352
|
-
'env_parser/autoregister' </code></p>
|
353
|
-
|
354
|
-
<p>… will automatically make the autoregistration call for you as soon as the
|
355
|
-
gem is loaded (which should be early enough for most uses). If this is
|
356
|
-
<em>still</em> not early enough for your needs, you can always
|
357
|
-
<code>require 'env_parser/autoregister'</code> yourself even before
|
358
|
-
<code>bundler/setup</code> is invoked.</p>
|
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>".env_parser.yml"</code> is assumed.</p>
|
250
|
+
|
251
|
+
<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>
|
252
|
+
|
253
|
+
<p><code>ruby gem 'env_parser', require: 'env_parser/autoregister' </code></p>
|
254
|
+
|
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 'env_parser/autoregister'</code> yourself even before <code>bundler/setup</code> is invoked.</p>
|
359
256
|
<ul><li>
|
360
257
|
<p><strong>The “.env_parser.yml” File</strong></p>
|
361
258
|
</li></ul>
|
362
259
|
|
363
|
-
<p>If you recall, multiple constants can be registered via a single
|
364
|
-
<code>EnvParser.register</code> call:</p>
|
260
|
+
<p>If you recall, multiple constants can be registered via a single <code>EnvParser.register</code> call:</p>
|
365
261
|
|
366
|
-
<p>“`ruby EnvParser.register :USERNAME, as: :string EnvParser.register
|
367
|
-
:PASSWORD, as: :string EnvParser.register :MOCK_API, as: :boolean, within:
|
368
|
-
MyClassOrModule }</p>
|
262
|
+
<p>“`ruby EnvParser.register :USERNAME, as: :string EnvParser.register :PASSWORD, as: :string EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }</p>
|
369
263
|
|
370
264
|
<p>## … is equivalent to … ##</p>
|
371
265
|
|
372
|
-
<p>EnvParser.register USERNAME: { as: :string }, PASSWORD: { as: :string },
|
373
|
-
MOCK_API: { as: :boolean, within: MyClassOrModule } “`</p>
|
266
|
+
<p>EnvParser.register USERNAME: { as: :string }, PASSWORD: { as: :string }, MOCK_API: { as: :boolean, within: MyClassOrModule } “`</p>
|
374
267
|
|
375
|
-
<p>The autoregistraton file is intended to read as a YAML version of what
|
376
|
-
you'd pass to the single-call version of
|
377
|
-
<code>EnvParser.register</code>: a single hash with keys for each of the
|
378
|
-
constants you'd like to register, with each value being the set of
|
379
|
-
options to parse that constant.</p>
|
268
|
+
<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>
|
380
269
|
|
381
270
|
<p>The equivalent autoregistration file for the above would be:</p>
|
382
271
|
|
@@ -386,49 +275,32 @@ options to parse that constant.</p>
|
|
386
275
|
|
387
276
|
<p>MOCK_API: as: :boolean within: MyClassOrModule “`</p>
|
388
277
|
|
389
|
-
<p>Because no Ruby <em>statements</em> can be safely represented via YAML, the
|
390
|
-
set of <code>EnvParser.register</code> options available via
|
391
|
-
autoregistration is limited to <strong><em>as</em></strong>,
|
392
|
-
<strong><em>within</em></strong>, <strong><em>if_unset</em></strong>, and
|
393
|
-
<strong><em>from_set</em></strong>. As an additional restriction,
|
394
|
-
<strong><em>from_set</em></strong> (if given) must be an array, as ranges
|
395
|
-
cannot be represented in YAML.</p>
|
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>
|
396
279
|
|
397
280
|
<h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
|
398
281
|
|
399
282
|
<p>Additional features coming in the future:</p>
|
400
283
|
<ul><li>
|
401
|
-
<p>Continue to round out the <strong><em>as</em></strong> type selection as
|
402
|
-
ideas come to mind, suggestions are made, and pull requests are submitted.</p>
|
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>
|
403
285
|
</li></ul>
|
404
286
|
|
405
287
|
<h2 id="label-Contribution+-2F+Development">Contribution / Development</h2>
|
406
288
|
|
407
|
-
<p>Bug reports and pull requests are welcome at: <a
|
408
|
-
href="https://github.com/nestor-custodio/env_parser">github.com/nestor-custodio/env_parser</a></p>
|
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>
|
409
290
|
|
410
|
-
<p>After checking out the repo, run <code>bin/setup</code> to install
|
411
|
-
dependencies. Then, run <code>bundle exec rspec</code> to run the tests.
|
412
|
-
You can also run <code>bin/console</code> for an interactive prompt that
|
413
|
-
will allow you to experiment.</p>
|
291
|
+
<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>
|
414
292
|
|
415
|
-
<p>Linting is courtesy of <a href="https://docs.rubocop.org/">Rubocop</a>
|
416
|
-
(<code>bundle exec rubocop</code>) and documentation is built using <a
|
417
|
-
href="https://yardoc.org/">Yard</a> (<code>bundle exec yard</code>). Please
|
418
|
-
ensure you have a clean bill of health from Rubocop and that any new
|
419
|
-
features and/or changes to behaviour are reflected in the documentation
|
420
|
-
before submitting a pull request.</p>
|
293
|
+
<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>
|
421
294
|
|
422
295
|
<h2 id="label-License">License</h2>
|
423
296
|
|
424
|
-
<p>EnvParser is available as open source under the terms of the <a
|
425
|
-
href="https://tldrlegal.com/license/mit-license">MIT License</a>.</p>
|
297
|
+
<p>EnvParser is available as open source under the terms of the <a href="https://tldrlegal.com/license/mit-license">MIT License</a>.</p>
|
426
298
|
</div></div>
|
427
299
|
|
428
300
|
<div id="footer">
|
429
|
-
Generated on
|
301
|
+
Generated on Sat Jan 2 17:31:16 2021 by
|
430
302
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
431
|
-
0.9.
|
303
|
+
0.9.26 (ruby-2.7.2).
|
432
304
|
</div>
|
433
305
|
|
434
306
|
</div>
|
data/docs/js/app.js
CHANGED
@@ -171,6 +171,7 @@ function generateTOC() {
|
|
171
171
|
var counter = 0;
|
172
172
|
var tags = ['h2', 'h3', 'h4', 'h5', 'h6'];
|
173
173
|
var i;
|
174
|
+
var curli;
|
174
175
|
if ($('#filecontents h1').length > 1) tags.unshift('h1');
|
175
176
|
for (i = 0; i < tags.length; i++) { tags[i] = '#filecontents ' + tags[i]; }
|
176
177
|
var lastTag = parseInt(tags[0][1], 10);
|
@@ -190,15 +191,25 @@ function generateTOC() {
|
|
190
191
|
}
|
191
192
|
if (thisTag > lastTag) {
|
192
193
|
for (i = 0; i < thisTag - lastTag; i++) {
|
193
|
-
|
194
|
+
if ( typeof(curli) == "undefined" ) {
|
195
|
+
curli = $('<li/>');
|
196
|
+
toc.append(curli);
|
197
|
+
}
|
198
|
+
toc = $('<ol/>');
|
199
|
+
curli.append(toc);
|
200
|
+
curli = undefined;
|
194
201
|
}
|
195
202
|
}
|
196
203
|
if (thisTag < lastTag) {
|
197
|
-
for (i = 0; i < lastTag - thisTag; i++)
|
204
|
+
for (i = 0; i < lastTag - thisTag; i++) {
|
205
|
+
toc = toc.parent();
|
206
|
+
toc = toc.parent();
|
207
|
+
}
|
198
208
|
}
|
199
209
|
var title = $(this).attr('toc-title');
|
200
210
|
if (typeof(title) == "undefined") title = $(this).text();
|
201
|
-
|
211
|
+
curli =$('<li><a href="#' + this.id + '">' + title + '</a></li>');
|
212
|
+
toc.append(curli);
|
202
213
|
lastTag = thisTag;
|
203
214
|
});
|
204
215
|
if (!show) return;
|