env_parser 1.3.0 → 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.
- checksums.yaml +5 -5
- data/.circleci/config.yml +1 -1
- data/.rubocop.yml +25 -30
- data/.ruby-version +1 -1
- data/Gemfile.lock +51 -43
- data/README.md +1 -1
- data/docs/EnvParser/AutoregisterFileNotFound.html +9 -10
- data/docs/EnvParser/Error.html +8 -9
- data/docs/EnvParser/TypeAlreadyDefinedError.html +8 -9
- data/docs/EnvParser/Types/BaseTypes.html +12 -11
- data/docs/EnvParser/Types/ChronologyTypes.html +10 -9
- data/docs/EnvParser/Types/InternetTypes.html +10 -9
- data/docs/EnvParser/Types.html +9 -10
- data/docs/EnvParser/UnknownTypeError.html +8 -9
- data/docs/EnvParser/UnparseableAutoregisterSpec.html +9 -10
- data/docs/EnvParser/ValueNotAllowedError.html +10 -11
- data/docs/EnvParser/ValueNotConvertibleError.html +8 -10
- data/docs/EnvParser.html +123 -186
- data/docs/_index.html +8 -10
- data/docs/class_list.html +2 -2
- data/docs/css/style.css +3 -2
- data/docs/file.README.html +254 -284
- data/docs/file_list.html +2 -2
- data/docs/frames.html +2 -2
- data/docs/index.html +254 -284
- data/docs/js/app.js +14 -3
- data/docs/method_list.html +3 -11
- data/docs/top-level-namespace.html +7 -85
- data/env_parser.gemspec +14 -14
- data/lib/env_parser/errors.rb +18 -18
- data/lib/env_parser/types/base_types.rb +69 -69
- data/lib/env_parser/types/chronology_types.rb +54 -54
- data/lib/env_parser/types/internet_types.rb +51 -51
- data/lib/env_parser/types.rb +2 -2
- data/lib/env_parser/version.rb +1 -1
- data/lib/env_parser.rb +206 -217
- data/spec/env_parser/types/base_types_spec.rb +98 -0
- data/spec/env_parser/types/chronology_types_spec.rb +49 -0
- data/spec/env_parser/types/internet_types_spec.rb +45 -0
- data/spec/env_parser_spec.rb +192 -0
- data/spec/spec_helper.rb +14 -0
- metadata +54 -50
- data/.travis.yml +0 -5
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.28
|
|
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>
|
|
@@ -57,378 +57,348 @@
|
|
|
57
57
|
<div class="clear"></div>
|
|
58
58
|
</div>
|
|
59
59
|
|
|
60
|
-
<div id="content"><div id='filecontents'>
|
|
61
|
-
<
|
|
62
|
-
|
|
63
|
-
<
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
<
|
|
68
|
-
|
|
69
|
-
<p>
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
<
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
<
|
|
90
|
-
<
|
|
91
|
-
<
|
|
92
|
-
|
|
93
|
-
</
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
<
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
</li><li>
|
|
108
|
-
<p>Or, you can keep things simple with a manual install: <code>shell $ gem
|
|
109
|
-
install env_parser </code></p>
|
|
110
|
-
</li></ul>
|
|
111
|
-
|
|
112
|
-
<h2 id="label-Syntax+Cheat+Sheet">Syntax Cheat Sheet</h2>
|
|
113
|
-
|
|
114
|
-
<pre class="code ruby"><code class="ruby">## Returns an ENV value parsed "as" a specific type:
|
|
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&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
|
+
|
|
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
|
+
|
|
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>
|
|
82
|
+
|
|
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:
|
|
115
107
|
##
|
|
116
108
|
EnvParser.parse env_key_as_a_symbol
|
|
117
109
|
as: … ## ➜ required
|
|
118
110
|
if_unset: … ## ➜ optional; default value
|
|
119
111
|
from_set: … ## ➜ optional; an Array or Range
|
|
120
|
-
validated_by: ->(value) { … } ## ➜ optional; may also be given as a block
|
|
112
|
+
validated_by: ->(value) { … } ## ➜ optional; may also be given as a block</p>
|
|
121
113
|
|
|
122
|
-
|
|
123
|
-
|
|
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>##
|
|
124
116
|
EnvParser.register env_key_as_a_symbol
|
|
125
117
|
as: … ## ➜ required
|
|
126
118
|
within: … ## ➜ optional; Class or Module
|
|
127
119
|
if_unset: … ## ➜ optional; default value
|
|
128
120
|
from_set: … ## ➜ optional; an Array or Range
|
|
129
|
-
validated_by: ->(value) { … } ## ➜ optional; may also be given as a block
|
|
121
|
+
validated_by: ->(value) { … } ## ➜ optional; may also be given as a block</p>
|
|
130
122
|
|
|
131
|
-
|
|
132
|
-
|
|
123
|
+
<h2 id="registers-all-env-variables-as-speced-in-envparseryml">Registers all ENV variables as spec’ed in “.env_parser.yml”:</h2>
|
|
124
|
+
<p>##
|
|
133
125
|
EnvParser.autoregister ## Note this is automatically called if your
|
|
134
|
-
## Gemfile included the
|
|
135
|
-
## the
|
|
126
|
+
## Gemfile included the “env_parser” gem with
|
|
127
|
+
## the “require: ‘env_parser/autoregister’” option.</p>
|
|
136
128
|
|
|
137
|
-
|
|
138
|
-
|
|
129
|
+
<h2 id="lets-you-call-parse-and-register-on-env-itself">Lets you call “parse” and “register” on ENV itself:</h2>
|
|
130
|
+
<p>##
|
|
139
131
|
EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
140
132
|
## and ENV.register will now be a proxy for EnvParser.register
|
|
141
|
-
|
|
133
|
+
```</p>
|
|
142
134
|
|
|
143
|
-
<h2 id="
|
|
135
|
+
<h2 id="extended-how-to-use">Extended How-To-Use</h2>
|
|
144
136
|
|
|
145
|
-
<h4 id="
|
|
146
|
-
<ul><li>
|
|
147
|
-
<p><strong>Parsing <code>ENV</code> Values</strong></p>
|
|
148
|
-
</li></ul>
|
|
137
|
+
<h4 id="basic-usage">Basic Usage</h4>
|
|
149
138
|
|
|
150
|
-
<
|
|
151
|
-
|
|
152
|
-
|
|
139
|
+
<ul>
|
|
140
|
+
<li>
|
|
141
|
+
<p><strong>Parsing <code>ENV</code> Values</strong></p>
|
|
153
142
|
|
|
154
|
-
<p
|
|
155
|
-
default (0) if ENV['TIMEOUT_MS'] is unset. ## timeout_ms =
|
|
156
|
-
EnvParser.parse ENV['TIMEOUT_MS'], as: :integer </code></p>
|
|
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>
|
|
157
144
|
|
|
158
|
-
<p>
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
</
|
|
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>
|
|
164
151
|
|
|
165
|
-
<p>EnvParser
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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>
|
|
169
156
|
|
|
170
|
-
<p
|
|
171
|
-
more_typing = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer less_typing
|
|
172
|
-
= EnvParser.parse :TIMEOUT_MS, as: :integer </code></p>
|
|
173
|
-
<ul><li>
|
|
174
|
-
<p><strong>Registering Constants From <code>ENV</code> Values</strong></p>
|
|
175
|
-
</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>
|
|
176
158
|
|
|
177
|
-
<p
|
|
178
|
-
|
|
179
|
-
the
|
|
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>
|
|
180
169
|
|
|
181
|
-
<p
|
|
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>
|
|
182
171
|
|
|
183
|
-
<p
|
|
184
|
-
p4$$w0rd
|
|
172
|
+
<p>```ruby
|
|
173
|
+
ENV[‘API_KEY’] ## => ‘unbreakable p4$$w0rd’</p>
|
|
185
174
|
|
|
186
|
-
<p>
|
|
187
|
-
|
|
188
|
-
|
|
175
|
+
<p>EnvParser.register :API_KEY, as: :string
|
|
176
|
+
API_KEY ## => ‘unbreakable p4$$w0rd’
|
|
177
|
+
```</p>
|
|
189
178
|
|
|
190
|
-
<p
|
|
191
|
-
href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>'</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>
|
|
192
180
|
|
|
193
|
-
<p
|
|
194
|
-
## =>
|
|
195
|
-
href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>'
|
|
196
|
-
BEST_VIDEO ## => raises NameError “`</p>
|
|
181
|
+
<p>```ruby
|
|
182
|
+
ENV[‘BEST_VIDEO’] ## => ‘https://youtu.be/L_jWHffIx5E’</p>
|
|
197
183
|
|
|
198
|
-
<p>
|
|
199
|
-
|
|
184
|
+
<p>EnvParser.register :BEST_VIDEO, as: :string, within: URI
|
|
185
|
+
URI::BEST_VIDEO ## => ‘https://youtu.be/L_jWHffIx5E’
|
|
186
|
+
BEST_VIDEO ## => raises NameError
|
|
187
|
+
```</p>
|
|
200
188
|
|
|
201
|
-
<p
|
|
202
|
-
:PASSWORD, as: :string EnvParser.register :MOCK_API, as: :boolean, within:
|
|
203
|
-
MyClassOrModule }</p>
|
|
189
|
+
<p>You can also register multiple constants with a single call, which is a bit cleaner.</p>
|
|
204
190
|
|
|
205
|
-
<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>
|
|
206
195
|
|
|
207
|
-
<
|
|
208
|
-
MOCK_API: { as: :boolean, within: MyClassOrModule } “`</p>
|
|
209
|
-
<ul><li>
|
|
210
|
-
<p><strong>Okay, But… How About Even Less Typing?</strong></p>
|
|
211
|
-
</li></ul>
|
|
196
|
+
<h2 id="is-equivalent-to-">… is equivalent to …</h2>
|
|
212
197
|
|
|
213
|
-
<p>
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
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>
|
|
218
205
|
|
|
219
|
-
<p
|
|
220
|
-
href="'BETTER_PI'">ENV</a> ## => '[“flaky crust”, “strawberry
|
|
221
|
-
filling”]'</p>
|
|
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>
|
|
222
207
|
|
|
223
|
-
<p
|
|
208
|
+
<p>```ruby
|
|
209
|
+
ENV[‘SHORT_PI’] ## => ‘3.1415926’
|
|
210
|
+
ENV[‘BETTER_PI’] ## => ‘[“flaky crust”, “strawberry filling”]’</p>
|
|
224
211
|
|
|
225
|
-
<
|
|
226
|
-
|
|
212
|
+
<h2 id="bind-the-proxy-methods">Bind the proxy methods.</h2>
|
|
213
|
+
<p>##
|
|
214
|
+
EnvParser.add_env_bindings</p>
|
|
227
215
|
|
|
228
|
-
<p>
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
the original <code>EnvParser.parse</code> method.</p>
|
|
216
|
+
<p>ENV.parse :SHORT_PI, as: :float ## => 3.1415926
|
|
217
|
+
ENV.register :BETTER_PI, as: :array ## Your constant is set!
|
|
218
|
+
```</p>
|
|
232
219
|
|
|
233
|
-
<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>
|
|
234
221
|
|
|
235
|
-
<p
|
|
236
|
-
|
|
237
|
-
href="'SHORT_PI'">ENV</a> as a float: 3.1415926</p>
|
|
222
|
+
<p>```ruby
|
|
223
|
+
ENV[‘SHORT_PI’] ## => ‘3.1415926’</p>
|
|
238
224
|
|
|
239
|
-
<p
|
|
225
|
+
<p>EnvParser.parse ‘SHORT_PI’, as: :float ## => ‘SHORT_PI’ as a float: 0.0
|
|
226
|
+
EnvParser.parse :SHORT_PI , as: :float ## => ENV[‘SHORT_PI’] as a float: 3.1415926</p>
|
|
240
227
|
|
|
241
|
-
<
|
|
242
|
-
|
|
243
|
-
|
|
228
|
+
<h2 id="bind-the-proxy-methods-1">Bind the proxy methods.</h2>
|
|
229
|
+
<p>##
|
|
230
|
+
EnvParser.add_env_bindings</p>
|
|
244
231
|
|
|
245
|
-
<p>
|
|
246
|
-
|
|
247
|
-
|
|
232
|
+
<p>ENV.parse ‘SHORT_PI’, as: :float ## => ENV[‘SHORT_PI’] as a float: 3.1415926
|
|
233
|
+
ENV.parse :SHORT_PI , as: :float ## => ENV[‘SHORT_PI’] as a float: 3.1415926
|
|
234
|
+
```</p>
|
|
248
235
|
|
|
249
|
-
<p
|
|
250
|
-
bindings are already in place, for brevity's sake.</strong></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>
|
|
251
237
|
|
|
252
|
-
<
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
</li></ul>
|
|
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>
|
|
256
241
|
|
|
257
|
-
<
|
|
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>
|
|
242
|
+
<h4 id="ensuring-usable-values">Ensuring Usable Values</h4>
|
|
263
243
|
|
|
264
|
-
<
|
|
265
|
-
|
|
244
|
+
<ul>
|
|
245
|
+
<li>
|
|
246
|
+
<p><strong>Sensible Defaults</strong></p>
|
|
266
247
|
|
|
267
|
-
<p>
|
|
268
|
-
exercise caution.</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>
|
|
269
249
|
|
|
270
|
-
<p><code>ruby
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
</li></ul>
|
|
250
|
+
<p><code>ruby
|
|
251
|
+
ENV.parse :MISSING_VAR, as: :integer ## => 0
|
|
252
|
+
ENV.parse :MISSING_VAR, as: :integer, if_unset: 250 ## => 250
|
|
253
|
+
</code></p>
|
|
275
254
|
|
|
276
|
-
<p>
|
|
277
|
-
open-ended. The <strong><em>from_set</em></strong> option lets you restrict
|
|
278
|
-
the domain of allowed values.</p>
|
|
255
|
+
<p>Note these default values are used as-is with no type conversion, so exercise caution.</p>
|
|
279
256
|
|
|
280
|
-
<p
|
|
257
|
+
<p><code>ruby
|
|
258
|
+
ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!' ## => 'Careful!' (NOT AN INTEGER)
|
|
259
|
+
</code></p>
|
|
260
|
+
</li>
|
|
261
|
+
<li>
|
|
262
|
+
<p><strong>Selecting From A Set</strong></p>
|
|
263
|
+
|
|
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>
|
|
265
|
+
|
|
266
|
+
<p>```ruby
|
|
267
|
+
ENV.parse :API_TO_USE, as: :symbol, from_set: %i[internal external]
|
|
281
268
|
ENV.parse :NETWORK_PORT, as: :integer, from_set: (1..65535), if_unset: 80</p>
|
|
282
269
|
|
|
283
|
-
<
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
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) ## => raises EnvParser::ValueNotAllowedError
|
|
273
|
+
```</p>
|
|
274
|
+
</li>
|
|
275
|
+
<li>
|
|
276
|
+
<p><strong>Custom Validation Of Parsed Values</strong></p>
|
|
289
277
|
|
|
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>
|
|
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>
|
|
294
279
|
|
|
295
|
-
<p
|
|
296
|
-
|
|
280
|
+
<p>```ruby
|
|
281
|
+
## Via a “validated_by” lambda …
|
|
282
|
+
##
|
|
283
|
+
ENV.parse :MUST_BE_LOWERCASE, as: :string, validated_by: ->(value) { value == value.downcase }</p>
|
|
297
284
|
|
|
298
|
-
<
|
|
299
|
-
|
|
300
|
-
:
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
</li
|
|
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, &:positive?)
|
|
289
|
+
```</p>
|
|
290
|
+
</li>
|
|
291
|
+
<li>
|
|
292
|
+
<p><strong>Defining Your Own EnvParser “<em>as</em>” Types</strong></p>
|
|
304
293
|
|
|
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>
|
|
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 aren’t littered with type-checking cruft).</p>
|
|
311
295
|
|
|
312
|
-
<p>Something as repetitive as:</p>
|
|
296
|
+
<p>Something as repetitive as:</p>
|
|
313
297
|
|
|
314
|
-
<p
|
|
315
|
-
|
|
298
|
+
<p>```ruby
|
|
299
|
+
a = ENV.parse :A, as: :int, if_unset: 6
|
|
300
|
+
raise unless passes_all_my_checks?(a)</p>
|
|
316
301
|
|
|
317
|
-
<p>b = ENV.parse :B, as: :int, if_unset: 6
|
|
318
|
-
passes_all_my_checks?(b)
|
|
302
|
+
<p>b = ENV.parse :B, as: :int, if_unset: 6
|
|
303
|
+
raise unless passes_all_my_checks?(b)
|
|
304
|
+
```</p>
|
|
319
305
|
|
|
320
|
-
<p>… is perhaps best handled by defining a new type:</p>
|
|
306
|
+
<p>… is perhaps best handled by defining a new type:</p>
|
|
321
307
|
|
|
322
|
-
<p
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
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>
|
|
326
314
|
|
|
327
|
-
<
|
|
328
|
-
</
|
|
315
|
+
<p>value
|
|
316
|
+
end</p>
|
|
329
317
|
|
|
330
|
-
<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>
|
|
331
323
|
|
|
332
|
-
<
|
|
333
|
-
:my_special_type_of_number “`</p>
|
|
324
|
+
<h4 id="auto-registering-constants">Auto-Registering Constants</h4>
|
|
334
325
|
|
|
335
|
-
<
|
|
336
|
-
<
|
|
337
|
-
<p><strong>The <code>autoregister</code> Call</strong></p>
|
|
338
|
-
</li></ul>
|
|
326
|
+
<ul>
|
|
327
|
+
<li>
|
|
328
|
+
<p><strong>The <code>autoregister</code> Call</strong></p>
|
|
339
329
|
|
|
340
|
-
<p>Consolidating all of your <code>EnvParser.register</code> calls into a
|
|
341
|
-
single place only makes sense. A single <code>EnvParser.autoregister</code>
|
|
342
|
-
call take a filename to read and process as a series of constant
|
|
343
|
-
registration requests. If no filename is given, the default
|
|
344
|
-
<code>".env_parser.yml"</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>
|
|
345
331
|
|
|
346
|
-
<p>You
|
|
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>
|
|
332
|
+
<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>
|
|
350
333
|
|
|
351
|
-
<p><code>ruby
|
|
352
|
-
|
|
334
|
+
<p><code>ruby
|
|
335
|
+
gem 'env_parser', require: 'env_parser/autoregister'
|
|
336
|
+
</code></p>
|
|
353
337
|
|
|
354
|
-
<p>… will automatically make the autoregistration call for you as soon as the
|
|
355
|
-
|
|
356
|
-
<
|
|
357
|
-
<
|
|
358
|
-
<code>bundler/setup</code> is invoked.</p>
|
|
359
|
-
<ul><li>
|
|
360
|
-
<p><strong>The “.env_parser.yml” File</strong></p>
|
|
361
|
-
</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>
|
|
362
342
|
|
|
363
|
-
<p>If you recall, multiple constants can be registered via a single
|
|
364
|
-
<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>
|
|
365
344
|
|
|
366
|
-
<p
|
|
367
|
-
|
|
368
|
-
|
|
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>
|
|
369
349
|
|
|
370
|
-
<
|
|
350
|
+
<h2 id="is-equivalent-to--1">… is equivalent to …</h2>
|
|
371
351
|
|
|
372
|
-
<p>EnvParser.register USERNAME: { as: :string
|
|
373
|
-
|
|
352
|
+
<p>EnvParser.register USERNAME: { as: :string },
|
|
353
|
+
PASSWORD: { as: :string },
|
|
354
|
+
MOCK_API: { as: :boolean, within: MyClassOrModule }
|
|
355
|
+
```</p>
|
|
374
356
|
|
|
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>
|
|
357
|
+
<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
358
|
|
|
381
|
-
<p>The equivalent autoregistration file for the above would be:</p>
|
|
359
|
+
<p>The equivalent autoregistration file for the above would be:</p>
|
|
382
360
|
|
|
383
|
-
<p
|
|
361
|
+
<p>```yaml
|
|
362
|
+
USERNAME:
|
|
363
|
+
as: :string</p>
|
|
384
364
|
|
|
385
|
-
<p>PASSWORD:
|
|
365
|
+
<p>PASSWORD:
|
|
366
|
+
as: :string</p>
|
|
386
367
|
|
|
387
|
-
<p>MOCK_API:
|
|
368
|
+
<p>MOCK_API:
|
|
369
|
+
as: :boolean
|
|
370
|
+
within: MyClassOrModule
|
|
371
|
+
```</p>
|
|
388
372
|
|
|
389
|
-
<p>Because no Ruby <em>statements</em> can be safely represented via YAML, the
|
|
390
|
-
|
|
391
|
-
|
|
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>
|
|
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>
|
|
396
376
|
|
|
397
|
-
<h2 id="
|
|
377
|
+
<h2 id="feature-roadmap--future-development">Feature Roadmap / Future Development</h2>
|
|
398
378
|
|
|
399
379
|
<p>Additional features coming in the future:</p>
|
|
400
|
-
<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>
|
|
403
|
-
</li></ul>
|
|
404
380
|
|
|
405
|
-
<
|
|
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>
|
|
406
386
|
|
|
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>
|
|
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>
|
|
409
388
|
|
|
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>
|
|
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>
|
|
414
390
|
|
|
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>
|
|
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>
|
|
421
392
|
|
|
422
|
-
<h2 id="
|
|
393
|
+
<h2 id="license">License</h2>
|
|
423
394
|
|
|
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>
|
|
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>
|
|
426
396
|
</div></div>
|
|
427
397
|
|
|
428
398
|
<div id="footer">
|
|
429
|
-
Generated on Sun
|
|
430
|
-
<a href="
|
|
431
|
-
0.9.
|
|
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).
|
|
432
402
|
</div>
|
|
433
403
|
|
|
434
404
|
</div>
|