env_parser 1.3.3 → 1.6.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Gemfile.lock +3 -5
- data/README.md +66 -66
- data/docs/EnvParser/AutoregisterFileNotFound.html +1 -1
- data/docs/EnvParser/Error.html +1 -1
- data/docs/EnvParser/TypeAlreadyDefinedError.html +1 -1
- data/docs/EnvParser/Types/BaseTypes.html +1 -1
- data/docs/EnvParser/Types/ChronologyTypes.html +1 -1
- data/docs/EnvParser/Types/InternetTypes.html +13 -1
- data/docs/EnvParser/Types.html +1 -1
- data/docs/EnvParser/UnknownTypeError.html +1 -1
- data/docs/EnvParser/UnparseableAutoregisterSpec.html +1 -1
- data/docs/EnvParser/ValueNotAllowedError.html +1 -1
- data/docs/EnvParser/ValueNotConvertibleError.html +1 -1
- data/docs/EnvParser.html +86 -53
- data/docs/_index.html +1 -1
- data/docs/file.README.html +66 -66
- data/docs/index.html +66 -66
- data/docs/top-level-namespace.html +1 -1
- data/env_parser.gemspec +2 -3
- data/lib/env_parser/types/internet_types.rb +22 -0
- data/lib/env_parser/version.rb +1 -1
- data/lib/env_parser.rb +20 -4
- data/spec/env_parser/types/internet_types_spec.rb +50 -0
- data/spec/env_parser_spec.rb +25 -3
- metadata +6 -20
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 897f5a82aae1f8d7c418937e61f72669eba8d846c5ee282bffd7f4ee72970f96
|
4
|
+
data.tar.gz: 6b90041b9ea794d896c9f603e8117377482fdaecb682cda49a925fd9dbdc22a9
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: cc132c2bdb3feffef9f294dae4ae929533e65da860e93b360290e655625011640f773f02596cfda8570e87e95877bc5a3c814cc8b23f43078bcf0b99dea4cdf9
|
7
|
+
data.tar.gz: c5d8ff0e7378ff6c94f104bcf1d35ec71ab4952b7fd3826854818b7d01f6a45f000697b5dcc173babcafa073dc6eb25def9721df60210b47be4afc936e4eebfe
|
data/Gemfile.lock
CHANGED
@@ -1,10 +1,10 @@
|
|
1
1
|
PATH
|
2
2
|
remote: .
|
3
3
|
specs:
|
4
|
-
env_parser (1.
|
4
|
+
env_parser (1.6.0)
|
5
5
|
activesupport (>= 6.1.0, < 7.1)
|
6
|
-
chronic
|
7
|
-
chronic_duration
|
6
|
+
chronic (~> 0)
|
7
|
+
chronic_duration (~> 0)
|
8
8
|
|
9
9
|
GEM
|
10
10
|
remote: https://rubygems.org/
|
@@ -29,7 +29,6 @@ GEM
|
|
29
29
|
parser (3.1.3.0)
|
30
30
|
ast (~> 2.4.1)
|
31
31
|
rainbow (3.1.1)
|
32
|
-
rake (13.0.6)
|
33
32
|
regexp_parser (2.6.1)
|
34
33
|
rexml (3.2.5)
|
35
34
|
rspec (3.12.0)
|
@@ -73,7 +72,6 @@ PLATFORMS
|
|
73
72
|
DEPENDENCIES
|
74
73
|
bundler (~> 2)
|
75
74
|
env_parser!
|
76
|
-
rake
|
77
75
|
rspec (~> 3)
|
78
76
|
rspec_junit_formatter
|
79
77
|
rubocop
|
data/README.md
CHANGED
@@ -1,5 +1,5 @@
|
|
1
1
|
[![Gem Version](https://img.shields.io/github/v/release/nestor-custodio/env_parser?color=green&label=gem%20version)](https://rubygems.org/gems/env_parser)
|
2
|
-
[![MIT License](https://img.shields.io/github/license/nestor-custodio/env_parser)](https://
|
2
|
+
[![MIT License](https://img.shields.io/github/license/nestor-custodio/env_parser)](https://tldrlegal.com/license/mit-license)
|
3
3
|
|
4
4
|
|
5
5
|
# EnvParser
|
@@ -16,13 +16,13 @@ Things can get out of control pretty fast, especially as the number of environme
|
|
16
16
|
- If your project uses [Bundler](https://github.com/bundler/bundler):
|
17
17
|
- Add one of the following to your application's Gemfile:
|
18
18
|
```ruby
|
19
|
-
|
20
|
-
|
19
|
+
# For on-demand usage ...
|
20
|
+
#
|
21
21
|
gem 'env_parser'
|
22
22
|
|
23
|
-
|
24
|
-
|
25
|
-
|
23
|
+
# To automatically register ENV
|
24
|
+
# constants per ".env_parser.yml" ...
|
25
|
+
#
|
26
26
|
gem 'env_parser', require: 'env_parser/autoregister'
|
27
27
|
```
|
28
28
|
- And then run a:
|
@@ -39,33 +39,33 @@ Things can get out of control pretty fast, especially as the number of environme
|
|
39
39
|
## Syntax Cheat Sheet
|
40
40
|
|
41
41
|
```ruby
|
42
|
-
|
43
|
-
|
42
|
+
# Returns an ENV value parsed "as" a specific type:
|
43
|
+
#
|
44
44
|
EnvParser.parse env_key_as_a_symbol
|
45
|
-
as: …
|
46
|
-
if_unset: …
|
47
|
-
from_set: …
|
48
|
-
validated_by: ->(value) { … }
|
45
|
+
as: … # ➜ required
|
46
|
+
if_unset: … # ➜ optional; default value
|
47
|
+
from_set: … # ➜ optional; an Array or Range
|
48
|
+
validated_by: ->(value) { … } # ➜ optional; may also be given as a block
|
49
49
|
|
50
|
-
|
51
|
-
|
50
|
+
# Parse an ENV value and register it as a constant:
|
51
|
+
#
|
52
52
|
EnvParser.register env_key_as_a_symbol
|
53
|
-
as: …
|
54
|
-
within: …
|
55
|
-
if_unset: …
|
56
|
-
from_set: …
|
57
|
-
validated_by: ->(value) { … }
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
EnvParser.autoregister
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
EnvParser.add_env_bindings
|
68
|
-
|
53
|
+
as: … # ➜ required
|
54
|
+
within: … # ➜ optional; Class or Module
|
55
|
+
if_unset: … # ➜ optional; default value
|
56
|
+
from_set: … # ➜ optional; an Array or Range
|
57
|
+
validated_by: ->(value) { … } # ➜ optional; may also be given as a block
|
58
|
+
|
59
|
+
# Registers all ENV variables as spec'ed in ".env_parser.yml":
|
60
|
+
#
|
61
|
+
EnvParser.autoregister # Note this is automatically called if your
|
62
|
+
# Gemfile included the "env_parser" gem with
|
63
|
+
# the "require: 'env_parser/autoregister'" option.
|
64
|
+
|
65
|
+
# Lets you call "parse" and "register" on ENV itself:
|
66
|
+
#
|
67
|
+
EnvParser.add_env_bindings # ENV.parse will now be a proxy for EnvParser.parse
|
68
|
+
# and ENV.register will now be a proxy for EnvParser.register
|
69
69
|
```
|
70
70
|
|
71
71
|
|
@@ -78,9 +78,9 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
78
78
|
At its core, EnvParser is a straight-forward parser for string values (since that's all `ENV` ever gives you), allowing you to read a given string **_as_** a variety of types.
|
79
79
|
|
80
80
|
```ruby
|
81
|
-
|
82
|
-
|
83
|
-
|
81
|
+
# Returns ENV['TIMEOUT_MS'] as an Integer,
|
82
|
+
# or a sensible default (0) if ENV['TIMEOUT_MS'] is unset.
|
83
|
+
#
|
84
84
|
timeout_ms = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
|
85
85
|
```
|
86
86
|
|
@@ -91,9 +91,9 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
91
91
|
EnvParser is all about ~~simplification~~ ~~less typing~~ *laziness*. If you pass in a symbol instead of a string, EnvParser will look to `ENV` and use the value from the corresponding (string) key.
|
92
92
|
|
93
93
|
```ruby
|
94
|
-
|
95
|
-
|
96
|
-
|
94
|
+
# YAY, LESS TYPING! 😃
|
95
|
+
# These two are the same:
|
96
|
+
#
|
97
97
|
more_typing = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
|
98
98
|
less_typing = EnvParser.parse :TIMEOUT_MS, as: :integer
|
99
99
|
```
|
@@ -103,20 +103,20 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
103
103
|
The `EnvParser.register` method lets you "promote" `ENV` variables into their own constants, already parsed into the correct type.
|
104
104
|
|
105
105
|
```ruby
|
106
|
-
ENV['API_KEY']
|
106
|
+
ENV['API_KEY'] # => 'unbreakable p4$$w0rd'
|
107
107
|
|
108
108
|
EnvParser.register :API_KEY, as: :string
|
109
|
-
API_KEY
|
109
|
+
API_KEY # => 'unbreakable p4$$w0rd'
|
110
110
|
```
|
111
111
|
|
112
112
|
By default, `EnvParser.register` will create the requested constant within the Kernel module (making it available everywhere), but you can specify any class or module you like.
|
113
113
|
|
114
114
|
```ruby
|
115
|
-
ENV['BEST_VIDEO']
|
115
|
+
ENV['BEST_VIDEO'] # => 'https://youtu.be/L_jWHffIx5E'
|
116
116
|
|
117
117
|
EnvParser.register :BEST_VIDEO, as: :string, within: URI
|
118
|
-
URI::BEST_VIDEO
|
119
|
-
BEST_VIDEO
|
118
|
+
URI::BEST_VIDEO # => 'https://youtu.be/L_jWHffIx5E'
|
119
|
+
BEST_VIDEO # => raises NameError
|
120
120
|
```
|
121
121
|
|
122
122
|
You can also register multiple constants with a single call, which is a bit cleaner.
|
@@ -126,7 +126,7 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
126
126
|
EnvParser.register :PASSWORD, as: :string
|
127
127
|
EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }
|
128
128
|
|
129
|
-
|
129
|
+
# ... is equivalent to ... #
|
130
130
|
|
131
131
|
EnvParser.register USERNAME: { as: :string },
|
132
132
|
PASSWORD: { as: :string },
|
@@ -138,31 +138,31 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
138
138
|
Calling `EnvParser.add_env_bindings` binds proxy `parse` and `register` methods onto `ENV`. With these bindings in place, you can call `parse` or `register` on `ENV` itself, which is more legible and feels more straight-forward.
|
139
139
|
|
140
140
|
```ruby
|
141
|
-
ENV['SHORT_PI']
|
142
|
-
ENV['BETTER_PI']
|
141
|
+
ENV['SHORT_PI'] # => '3.1415926'
|
142
|
+
ENV['BETTER_PI'] # => '["flaky crust", "strawberry filling"]'
|
143
143
|
|
144
|
-
|
145
|
-
|
144
|
+
# Bind the proxy methods.
|
145
|
+
#
|
146
146
|
EnvParser.add_env_bindings
|
147
147
|
|
148
|
-
ENV.parse :SHORT_PI, as: :float
|
149
|
-
ENV.register :BETTER_PI, as: :array
|
148
|
+
ENV.parse :SHORT_PI, as: :float # => 3.1415926
|
149
|
+
ENV.register :BETTER_PI, as: :array # Your constant is set!
|
150
150
|
```
|
151
151
|
|
152
152
|
Note that the proxy `ENV.parse` method will (naturally) *always* interpret the value given as an `ENV` key (converting it to a string, if necessary), which is slightly different from the original `EnvParser.parse` method.
|
153
153
|
|
154
154
|
```ruby
|
155
|
-
ENV['SHORT_PI']
|
155
|
+
ENV['SHORT_PI'] # => '3.1415926'
|
156
156
|
|
157
|
-
EnvParser.parse 'SHORT_PI', as: :float
|
158
|
-
EnvParser.parse :SHORT_PI , as: :float
|
157
|
+
EnvParser.parse 'SHORT_PI', as: :float # => 'SHORT_PI' as a float: 0.0
|
158
|
+
EnvParser.parse :SHORT_PI , as: :float # => ENV['SHORT_PI'] as a float: 3.1415926
|
159
159
|
|
160
|
-
|
161
|
-
|
160
|
+
# Bind the proxy methods.
|
161
|
+
#
|
162
162
|
EnvParser.add_env_bindings
|
163
163
|
|
164
|
-
ENV.parse 'SHORT_PI', as: :float
|
165
|
-
ENV.parse :SHORT_PI , as: :float
|
164
|
+
ENV.parse 'SHORT_PI', as: :float # => ENV['SHORT_PI'] as a float: 3.1415926
|
165
|
+
ENV.parse :SHORT_PI , as: :float # => ENV['SHORT_PI'] as a float: 3.1415926
|
166
166
|
```
|
167
167
|
|
168
168
|
Note also that the `ENV.parse` and `ENV.register` binding is done safely and without polluting the method space for other objects.
|
@@ -177,14 +177,14 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
177
177
|
If the `ENV` variable you want is unset (`nil`) or blank (`''`), the return value is a sensible default for the given **_as_** type: 0 or 0.0 for numbers, an empty string/array/hash, etc. Sometimes you want a non-trivial default, however. The **_if_unset_** option lets you specify a default that better meets your needs.
|
178
178
|
|
179
179
|
```ruby
|
180
|
-
ENV.parse :MISSING_VAR, as: :integer
|
181
|
-
ENV.parse :MISSING_VAR, as: :integer, if_unset: 250
|
180
|
+
ENV.parse :MISSING_VAR, as: :integer # => 0
|
181
|
+
ENV.parse :MISSING_VAR, as: :integer, if_unset: 250 # => 250
|
182
182
|
```
|
183
183
|
|
184
184
|
Note these default values are used as-is with no type conversion, so exercise caution.
|
185
185
|
|
186
186
|
```ruby
|
187
|
-
ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!'
|
187
|
+
ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!' # => 'Careful!' (NOT AN INTEGER)
|
188
188
|
```
|
189
189
|
|
190
190
|
- **Selecting From A Set**
|
@@ -195,9 +195,9 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
195
195
|
ENV.parse :API_TO_USE, as: :symbol, from_set: %i[internal external]
|
196
196
|
ENV.parse :NETWORK_PORT, as: :integer, from_set: (1..65535), if_unset: 80
|
197
197
|
|
198
|
-
|
199
|
-
|
200
|
-
ENV.parse :TWELVE, as: :integer, from_set: (1..5)
|
198
|
+
# And if the value is not in the allowed set ...
|
199
|
+
#
|
200
|
+
ENV.parse :TWELVE, as: :integer, from_set: (1..5) # => raises EnvParser::ValueNotAllowedError
|
201
201
|
```
|
202
202
|
|
203
203
|
- **Custom Validation Of Parsed Values**
|
@@ -205,12 +205,12 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
205
205
|
You can write your own, more complex validations by passing in a **_validated_by_** lambda or an equivalent block. The lambda/block should take one value and return true if the given value passes the custom validation.
|
206
206
|
|
207
207
|
```ruby
|
208
|
-
|
209
|
-
|
208
|
+
# Via a "validated_by" lambda ...
|
209
|
+
#
|
210
210
|
ENV.parse :MUST_BE_LOWERCASE, as: :string, validated_by: ->(value) { value == value.downcase }
|
211
211
|
|
212
|
-
|
213
|
-
|
212
|
+
# ... or with a block!
|
213
|
+
#
|
214
214
|
ENV.parse(:MUST_BE_LOWERCASE, as: :string) { |value| value == value.downcase }
|
215
215
|
ENV.parse(:CONNECTION_RETRIES, as: :integer, &:positive?)
|
216
216
|
```
|
@@ -269,7 +269,7 @@ EnvParser.add_env_bindings ## ENV.parse will now be a proxy for EnvParser.parse
|
|
269
269
|
EnvParser.register :PASSWORD, as: :string
|
270
270
|
EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }
|
271
271
|
|
272
|
-
|
272
|
+
# ... is equivalent to ... #
|
273
273
|
|
274
274
|
EnvParser.register USERNAME: { as: :string },
|
275
275
|
PASSWORD: { as: :string },
|
@@ -133,7 +133,7 @@ feature).</p>
|
|
133
133
|
</div>
|
134
134
|
|
135
135
|
<div id="footer">
|
136
|
-
Generated on
|
136
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
137
137
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
138
138
|
0.9.28 (ruby-3.0.4).
|
139
139
|
</div>
|
data/docs/EnvParser/Error.html
CHANGED
@@ -128,7 +128,7 @@
|
|
128
128
|
</div>
|
129
129
|
|
130
130
|
<div id="footer">
|
131
|
-
Generated on
|
131
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
132
132
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
133
133
|
0.9.28 (ruby-3.0.4).
|
134
134
|
</div>
|
@@ -132,7 +132,7 @@
|
|
132
132
|
</div>
|
133
133
|
|
134
134
|
<div id="footer">
|
135
|
-
Generated on
|
135
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
136
136
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
137
137
|
0.9.28 (ruby-3.0.4).
|
138
138
|
</div>
|
@@ -169,7 +169,7 @@ valid, parseable JSON).</p>
|
|
169
169
|
</div>
|
170
170
|
|
171
171
|
<div id="footer">
|
172
|
-
Generated on
|
172
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
173
173
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
174
174
|
0.9.28 (ruby-3.0.4).
|
175
175
|
</div>
|
@@ -150,7 +150,7 @@
|
|
150
150
|
</div>
|
151
151
|
|
152
152
|
<div id="footer">
|
153
|
-
Generated on
|
153
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
154
154
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
155
155
|
0.9.28 (ruby-3.0.4).
|
156
156
|
</div>
|
@@ -129,6 +129,18 @@
|
|
129
129
|
Note this does not guarantee RFC5322-conformity.
|
130
130
|
</td>
|
131
131
|
</tr>
|
132
|
+
<tr>
|
133
|
+
<td>:version / :semver</td>
|
134
|
+
<td>MatchData</td>
|
135
|
+
<td><code>nil</code></td>
|
136
|
+
<td>
|
137
|
+
The resulting MatchData has named captures for "major", "minor", "patch", "prerelease", and "buildmetadata".
|
138
|
+
<br />
|
139
|
+
The Regex used for generating this MatchData is available at: https://regex101.com/r/Ly7O1x/3/
|
140
|
+
<br />
|
141
|
+
See https://semver.org for additional info.
|
142
|
+
</td>
|
143
|
+
</tr>
|
132
144
|
</tbody>
|
133
145
|
</table>
|
134
146
|
|
@@ -150,7 +162,7 @@
|
|
150
162
|
</div>
|
151
163
|
|
152
164
|
<div id="footer">
|
153
|
-
Generated on
|
165
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
154
166
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
155
167
|
0.9.28 (ruby-3.0.4).
|
156
168
|
</div>
|
data/docs/EnvParser/Types.html
CHANGED
@@ -118,7 +118,7 @@ Exists only for documentation’s sake.</p>
|
|
118
118
|
</div>
|
119
119
|
|
120
120
|
<div id="footer">
|
121
|
-
Generated on
|
121
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
122
122
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
123
123
|
0.9.28 (ruby-3.0.4).
|
124
124
|
</div>
|
@@ -132,7 +132,7 @@
|
|
132
132
|
</div>
|
133
133
|
|
134
134
|
<div id="footer">
|
135
|
-
Generated on
|
135
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
136
136
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
137
137
|
0.9.28 (ruby-3.0.4).
|
138
138
|
</div>
|
@@ -133,7 +133,7 @@ feature).</p>
|
|
133
133
|
</div>
|
134
134
|
|
135
135
|
<div id="footer">
|
136
|
-
Generated on
|
136
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
137
137
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
138
138
|
0.9.28 (ruby-3.0.4).
|
139
139
|
</div>
|
@@ -134,7 +134,7 @@ check.</p>
|
|
134
134
|
</div>
|
135
135
|
|
136
136
|
<div id="footer">
|
137
|
-
Generated on
|
137
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
138
138
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
139
139
|
0.9.28 (ruby-3.0.4).
|
140
140
|
</div>
|
@@ -132,7 +132,7 @@
|
|
132
132
|
</div>
|
133
133
|
|
134
134
|
<div id="footer">
|
135
|
-
Generated on
|
135
|
+
Generated on Fri Dec 30 17:49:58 2022 by
|
136
136
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
137
137
|
0.9.28 (ruby-3.0.4).
|
138
138
|
</div>
|