env_parser 0.4.1 → 0.5.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Gemfile.lock +1 -1
- data/README.md +90 -26
- data/docs/EnvParser/ValueNotAllowed.html +1 -1
- data/docs/EnvParser.html +47 -23
- data/docs/_index.html +1 -1
- data/docs/file.README.html +130 -86
- data/docs/index.html +130 -86
- data/docs/top-level-namespace.html +1 -1
- data/lib/env_parser/version.rb +1 -1
- data/lib/env_parser.rb +47 -0
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 824a4026a34c07f38be413d43c95c1a58b65794f
|
4
|
+
data.tar.gz: 4a94816516c1925f887aaba58ff670af1189b3f8
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 9ed47eb04f852943956de4fb37cf0a866c0ad9647405734e572c9994f2ff800cb18f57423a7db90766583eeaffd7394d61b5a5b5996d9a9833eec1cb2c54cb1f
|
7
|
+
data.tar.gz: 1e0cbd84c815baf0d9359825279379b8abdc61e8aebadc7aadbb7739bad1e14b335822fec2217ad7fb3c80832a62e562dc9276fa255c6c8e695f43641c7d3756
|
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
@@ -26,7 +26,8 @@ Or install it yourself as:
|
|
26
26
|
|
27
27
|
## Usage
|
28
28
|
|
29
|
-
Basic EnvParser usage:
|
29
|
+
#### Basic EnvParser usage:
|
30
|
+
|
30
31
|
```ruby
|
31
32
|
## Returns ENV['TIMEOUT_MS'] as an Integer.
|
32
33
|
## Yields 0 if ENV['TIMEOUT_MS'] is unset or nil.
|
@@ -36,13 +37,69 @@ timeout_ms = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
|
|
36
37
|
## LESS TYPING, PLZ! :(
|
37
38
|
## If you pass in a Symbol instead of a String, EnvParser
|
38
39
|
## will use the value behind the matching String key in ENV.
|
39
|
-
## (i.e. passing in
|
40
|
+
## (i.e. passing in ENV['X'] is equivalent to passing in :X)
|
40
41
|
##
|
41
42
|
timeout_ms = EnvParser.parse :TIMEOUT_MS, as: :integer
|
43
|
+
```
|
44
|
+
|
45
|
+
---
|
42
46
|
|
43
|
-
|
44
|
-
|
45
|
-
|
47
|
+
The named `:as` parameter is required. Allowed values are:
|
48
|
+
|
49
|
+
<table>
|
50
|
+
<tbody>
|
51
|
+
<tr>
|
52
|
+
<th><code>:as</code> value</th>
|
53
|
+
<th>type returned</th>
|
54
|
+
</tr>
|
55
|
+
</tbody>
|
56
|
+
<tbody>
|
57
|
+
<tr>
|
58
|
+
<td>:string</td>
|
59
|
+
<td>String</td>
|
60
|
+
</tr>
|
61
|
+
<tr>
|
62
|
+
<td>:symbol</td>
|
63
|
+
<td>Symbol</td>
|
64
|
+
</tr>
|
65
|
+
<tr>
|
66
|
+
<td>:boolean</td>
|
67
|
+
<td>TrueValue / FalseValue</td>
|
68
|
+
</tr>
|
69
|
+
<tr>
|
70
|
+
<td>:int / :integer</td>
|
71
|
+
<td>Integer</td>
|
72
|
+
</tr>
|
73
|
+
<tr>
|
74
|
+
<td>:float / :decimal / :number</td>
|
75
|
+
<td>Float</td>
|
76
|
+
</tr>
|
77
|
+
<tr>
|
78
|
+
<td>:json</td>
|
79
|
+
<td>< depends on JSON given ></td>
|
80
|
+
</tr>
|
81
|
+
<tr>
|
82
|
+
<td>:array</td>
|
83
|
+
<td>Array</td>
|
84
|
+
</tr>
|
85
|
+
<tr>
|
86
|
+
<td>:hash</td>
|
87
|
+
<td>Hash</td>
|
88
|
+
</tr>
|
89
|
+
</tbody>
|
90
|
+
</table>
|
91
|
+
|
92
|
+
|
93
|
+
Note JSON is parsed using *quirks-mode* (meaning 'true', '25', and 'null' are all considered valid, parseable JSON).
|
94
|
+
|
95
|
+
|
96
|
+
#### Setting non-trivial defaults:
|
97
|
+
|
98
|
+
```ruby
|
99
|
+
## If the ENV variable you want is unset (nil) or blank (''),
|
100
|
+
## the return value is a sensible default for the given "as" type
|
101
|
+
## (0 or 0.0 for numbers, an empty tring, an empty Array or Hash, etc).
|
102
|
+
## Sometimes you want a non-trivial default, however.
|
46
103
|
##
|
47
104
|
EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer ## => 0
|
48
105
|
EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer, if_unset: 250 ## => 250
|
@@ -50,7 +107,12 @@ EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer, if_unset: 250 ## => 250
|
|
50
107
|
## Note that "if_unset" values are used as-is, with no type conversion.
|
51
108
|
##
|
52
109
|
EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer, if_unset: 'Whoops!' ## => 'Whoops!'
|
110
|
+
```
|
111
|
+
|
53
112
|
|
113
|
+
#### Validation of parsed ENV values:
|
114
|
+
|
115
|
+
```ruby
|
54
116
|
## Sometimes setting the type alone is a bit too open-ended.
|
55
117
|
## The "from_set" option lets you restrict the set of allowed values.
|
56
118
|
##
|
@@ -60,49 +122,51 @@ EnvParser.parse :SOME_CUSTOM_NETWORK_PORT, as: :integer, from_set: (1..65535), i
|
|
60
122
|
## And if the value is not allowed...
|
61
123
|
##
|
62
124
|
EnvParser.parse :NEGATIVE_NUMBER, as: :integer, from_set: (1..5) ## => raises EnvParser::ValueNotAllowed
|
125
|
+
```
|
63
126
|
|
64
|
-
|
127
|
+
#### Turning ENV values into constants:
|
65
128
|
|
129
|
+
```ruby
|
66
130
|
## Global constants...
|
67
131
|
##
|
68
|
-
ENV['API_KEY']
|
132
|
+
ENV['API_KEY'] ## => 'unbreakable p4$$w0rd' (Set elsewhere, like a ".env" file.)
|
69
133
|
EnvParser.register :API_KEY, as: :string
|
70
134
|
API_KEY ## => 'unbreakable p4$$w0rd' (registered within the Kernel module, so it's available everywhere)
|
71
135
|
|
72
136
|
## ... and class/module constants!
|
73
137
|
##
|
74
|
-
ENV['ULTIMATE_LINK']
|
138
|
+
ENV['ULTIMATE_LINK'] ## => 'https://youtu.be/L_jWHffIx5E' (Set elsewhere, like a ".env" file.)
|
75
139
|
EnvParser.register :ULTIMATE_LINK, as: :string, within: URI
|
76
|
-
URI::ULTIMATE_LINK ## =>
|
140
|
+
URI::ULTIMATE_LINK ## => 'https://youtu.be/L_jWHffIx5E' (You know you want to check it out!)
|
77
141
|
ULTIMATE_LINK ## => raises NameError (the un-namespaced constant is only in scope within the URI module)
|
78
142
|
```
|
79
143
|
|
80
|
-
|
81
|
-
|
82
|
-
The named `:as` value is required. Allowed values are:
|
83
|
-
|
84
|
-
| `:as` value | type returned |
|
85
|
-
|-----------------------------|---------------------------------|
|
86
|
-
| :string | String |
|
87
|
-
| :symbol | Symbol |
|
88
|
-
| :boolean | TrueValue / FalseValue |
|
89
|
-
| :int / :integer | Integer |
|
90
|
-
| :float / :decimal / :number | Float |
|
91
|
-
| :json | < depends on JSON given > |
|
92
|
-
| :array | Array |
|
93
|
-
| :hash | Hash |
|
144
|
+
#### Quickly registering multiple ENV-derived constants:
|
94
145
|
|
95
|
-
|
146
|
+
```ruby
|
147
|
+
## You can also set multiple constants in one call, which is considerably cleaner to read:
|
148
|
+
##
|
149
|
+
EnvParser.register :A, as: :string
|
150
|
+
EnvParser.register :B, as: :integer, if_unset: 25
|
151
|
+
EnvParser.register :C, as: :boolean, if_unset: true
|
152
|
+
##
|
153
|
+
## ... is equivalent to ...
|
154
|
+
##
|
155
|
+
EnvParser.register(
|
156
|
+
A: { as: :string },
|
157
|
+
B: { as: :integer, if_unset: 25 },
|
158
|
+
C: { as: :boolean, if_unset: true }
|
159
|
+
)
|
160
|
+
```
|
96
161
|
|
97
162
|
---
|
98
163
|
|
99
|
-
[Consult the repo docs](
|
164
|
+
[Consult the repo docs](http://nestor-custodio.github.io/env_parser) for the full EnvParser documentation.
|
100
165
|
|
101
166
|
|
102
167
|
## Feature Roadmap / Future Development
|
103
168
|
|
104
169
|
Additional features/options coming in the future:
|
105
|
-
- An `EnvParser.register_all` method to shortcut multiple `.register` calls.
|
106
170
|
- A means to **optionally** bind `#parse`, `#regiter`, and `#register_all` methods onto `ENV`. Because `ENV.parse ...` reads better than `EnvParser.parse ...`.
|
107
171
|
- A `validator` option that lets you pass in a validator lambda/block for things more complex than what a simple `from_set` can enforce.
|
108
172
|
- A means to register validation blocks as new "as" types. This will allow for custom "as" types like `:url`, `:email`, etc.
|
@@ -126,7 +126,7 @@ option.</p>
|
|
126
126
|
</div>
|
127
127
|
|
128
128
|
<div id="footer">
|
129
|
-
Generated on
|
129
|
+
Generated on Sun Dec 3 14:43:03 2017 by
|
130
130
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
131
131
|
0.9.11 (ruby-2.4.2).
|
132
132
|
</div>
|
data/docs/EnvParser.html
CHANGED
@@ -130,7 +130,7 @@ different data types.</p>
|
|
130
130
|
<dt id="VERSION-constant" class="">VERSION =
|
131
131
|
|
132
132
|
</dt>
|
133
|
-
<dd><pre class="code"><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>0.
|
133
|
+
<dd><pre class="code"><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>0.5.0</span><span class='tstring_end'>'</span></span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
|
134
134
|
|
135
135
|
</dl>
|
136
136
|
|
@@ -403,7 +403,7 @@ value will raise an ArgumentError exception.</p>
|
|
403
403
|
|
404
404
|
<span class='kw'>return</span> <span class='id identifier rubyid_options'>options</span><span class='lbracket'>[</span><span class='symbol'>:if_unset</span><span class='rbracket'>]</span> <span class='kw'>if</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_blank?'>blank?</span> <span class='op'>&&</span> <span class='id identifier rubyid_options'>options</span><span class='period'>.</span><span class='id identifier rubyid_key?'>key?</span><span class='lparen'>(</span><span class='symbol'>:if_unset</span><span class='rparen'>)</span>
|
405
405
|
|
406
|
-
<span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='kw'>case</span> <span class='id identifier rubyid_options'>options</span><span class='lbracket'>[</span><span class='symbol'>:as</span><span class='rbracket'>]</span
|
406
|
+
<span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='kw'>case</span> <span class='id identifier rubyid_options'>options</span><span class='lbracket'>[</span><span class='symbol'>:as</span><span class='rbracket'>]</span>
|
407
407
|
<span class='kw'>when</span> <span class='symbol'>:string</span> <span class='kw'>then</span> <span class='id identifier rubyid_parse_string'>parse_string</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span>
|
408
408
|
<span class='kw'>when</span> <span class='symbol'>:symbol</span> <span class='kw'>then</span> <span class='id identifier rubyid_parse_symbol'>parse_symbol</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span>
|
409
409
|
<span class='kw'>when</span> <span class='symbol'>:boolean</span> <span class='kw'>then</span> <span class='id identifier rubyid_parse_boolean'>parse_boolean</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span>
|
@@ -438,6 +438,22 @@ value will raise an ArgumentError exception.</p>
|
|
438
438
|
<p>Parses the referenced value and creates a matching constant in the
|
439
439
|
requested context.</p>
|
440
440
|
|
441
|
+
<p>Multiple calls to “register” may be shortcutted by passing in a Hash with
|
442
|
+
the same keys as those in the “from” Hash and each value being the
|
443
|
+
“register” options set for each variable's “register” call.</p>
|
444
|
+
<pre class="code ruby"><code class="ruby">
|
445
|
+
## Example shortcut usage:
|
446
|
+
|
447
|
+
EnvParser.register :A, from: one_hash, as: :integer
|
448
|
+
EnvParser.register :B, from: another_hash, as: :string, if_unset: 'none'
|
449
|
+
|
450
|
+
## ... is equivalent to ...
|
451
|
+
|
452
|
+
EnvParser.register(
|
453
|
+
A: { from: ENV, as: :integer }
|
454
|
+
B: { from: other_hash, as: :string, if_unset: 'none' }
|
455
|
+
)
|
456
|
+
</code></pre>
|
441
457
|
|
442
458
|
</div>
|
443
459
|
</div>
|
@@ -578,24 +594,6 @@ Kernel (making it a global constant).</p>
|
|
578
594
|
<pre class="lines">
|
579
595
|
|
580
596
|
|
581
|
-
101
|
582
|
-
102
|
583
|
-
103
|
584
|
-
104
|
585
|
-
105
|
586
|
-
106
|
587
|
-
107
|
588
|
-
108
|
589
|
-
109
|
590
|
-
110
|
591
|
-
111
|
592
|
-
112
|
593
|
-
113
|
594
|
-
114
|
595
|
-
115
|
596
|
-
116
|
597
|
-
117
|
598
|
-
118
|
599
597
|
119
|
600
598
|
120
|
601
599
|
121
|
@@ -604,12 +602,38 @@ Kernel (making it a global constant).</p>
|
|
604
602
|
124
|
605
603
|
125
|
606
604
|
126
|
607
|
-
127
|
605
|
+
127
|
606
|
+
128
|
607
|
+
129
|
608
|
+
130
|
609
|
+
131
|
610
|
+
132
|
611
|
+
133
|
612
|
+
134
|
613
|
+
135
|
614
|
+
136
|
615
|
+
137
|
616
|
+
138
|
617
|
+
139
|
618
|
+
140
|
619
|
+
141
|
620
|
+
142
|
621
|
+
143
|
622
|
+
144
|
623
|
+
145
|
624
|
+
146
|
625
|
+
147
|
626
|
+
148
|
627
|
+
149</pre>
|
608
628
|
</td>
|
609
629
|
<td>
|
610
|
-
<pre class="code"><span class="info file"># File 'lib/env_parser.rb', line
|
630
|
+
<pre class="code"><span class="info file"># File 'lib/env_parser.rb', line 119</span>
|
611
631
|
|
612
632
|
<span class='kw'>def</span> <span class='id identifier rubyid_register'>register</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
|
633
|
+
<span class='comment'>## We want to allow for registering multiple variables simultaneously via a single `.register`
|
634
|
+
</span> <span class='comment'>## method call.
|
635
|
+
</span> <span class='kw'>return</span> <span class='id identifier rubyid_register_all'>register_all</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span> <span class='kw'>if</span> <span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_is_a?'>is_a?</span> <span class='const'>Hash</span>
|
636
|
+
|
613
637
|
<span class='id identifier rubyid_from'>from</span> <span class='op'>=</span> <span class='id identifier rubyid_options'>options</span><span class='period'>.</span><span class='id identifier rubyid_fetch'>fetch</span><span class='lparen'>(</span><span class='symbol'>:from</span><span class='comma'>,</span> <span class='const'>ENV</span><span class='rparen'>)</span>
|
614
638
|
<span class='id identifier rubyid_within'>within</span> <span class='op'>=</span> <span class='id identifier rubyid_options'>options</span><span class='period'>.</span><span class='id identifier rubyid_fetch'>fetch</span><span class='lparen'>(</span><span class='symbol'>:within</span><span class='comma'>,</span> <span class='const'>Kernel</span><span class='rparen'>)</span>
|
615
639
|
|
@@ -646,7 +670,7 @@ Kernel (making it a global constant).</p>
|
|
646
670
|
</div>
|
647
671
|
|
648
672
|
<div id="footer">
|
649
|
-
Generated on
|
673
|
+
Generated on Sun Dec 3 14:43:03 2017 by
|
650
674
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
651
675
|
0.9.11 (ruby-2.4.2).
|
652
676
|
</div>
|
data/docs/_index.html
CHANGED
@@ -112,7 +112,7 @@
|
|
112
112
|
</div>
|
113
113
|
|
114
114
|
<div id="footer">
|
115
|
-
Generated on
|
115
|
+
Generated on Sun Dec 3 14:43:03 2017 by
|
116
116
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
117
117
|
0.9.11 (ruby-2.4.2).
|
118
118
|
</div>
|
data/docs/file.README.html
CHANGED
@@ -93,100 +93,144 @@ simple.</p>
|
|
93
93
|
|
94
94
|
<h2 id="label-Usage">Usage</h2>
|
95
95
|
|
96
|
-
<
|
97
|
-
|
98
|
-
<
|
99
|
-
|
100
|
-
|
101
|
-
|
102
|
-
|
103
|
-
:
|
104
|
-
|
105
|
-
|
106
|
-
|
107
|
-
|
108
|
-
|
109
|
-
|
110
|
-
|
111
|
-
<h2 id="label-28i.e.+passing+in+ENV-5B-27X-27-5D+is+equivalent+to+passing+in+-3AX-29">(i.e. passing in <code>ENV['X']</code> is equivalent to passing in <code>:X</code>)</h2>
|
112
|
-
|
113
|
-
<p>## timeout_ms = EnvParser.parse :TIMEOUT_MS, as: :integer</p>
|
114
|
-
|
115
|
-
<h2 id="label-If+the+ENV+variable+you+want+is+unset+-28nil-29+or+blank+-28-27-27-29-2C">If the ENV variable you want is unset (<code>nil</code>) or blank (<code>''</code>),</h2>
|
116
|
-
|
117
|
-
<h2 id="label-the+return+value+is+a+sensible+default+for+the+given+-22as-22+type.">the return value is a sensible default for the given “as” type.</h2>
|
118
|
-
|
119
|
-
<h2 id="label-Sometimes+you+want+a+non-trivial+default+-28not+just+0-2C+-27-27-2C+etc-29-2C+however.">Sometimes you want a non-trivial default (not just 0, '', etc), however.</h2>
|
120
|
-
|
121
|
-
<p>## EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer ## => 0
|
122
|
-
EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer, if_unset: 250 ## =>
|
123
|
-
250</p>
|
124
|
-
|
125
|
-
<h2 id="label-Note+that+-22if_unset-22+values+are+used+as-is-2C+with+no+type+conversion.">Note that “if_unset” values are used as-is, with no type conversion.</h2>
|
126
|
-
|
127
|
-
<p>## EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer, if_unset:
|
128
|
-
'Whoops!' ## => 'Whoops!'</p>
|
129
|
-
|
130
|
-
<h2 id="label-Sometimes+setting+the+type+alone+is+a+bit+too+open-ended.">Sometimes setting the type alone is a bit too open-ended.</h2>
|
131
|
-
|
132
|
-
<h2 id="label-The+-22from_set-22+option+lets+you+restrict+the+set+of+allowed+values.">The “from_set” option lets you restrict the set of allowed values.</h2>
|
133
|
-
|
134
|
-
<p>## EnvParser.parse :API_TO_USE, as: :symbol, from_set: %i[internal
|
135
|
-
external] EnvParser.parse :SOME_CUSTOM_NETWORK_PORT, as: :integer,
|
136
|
-
from_set: (1..65535), if_unset: 80</p>
|
137
|
-
|
138
|
-
<h2 id="label-And+if+the+value+is+not+allowed...">And if the value is not allowed…</h2>
|
139
|
-
|
140
|
-
<p>## EnvParser.parse :NEGATIVE_NUMBER, as: :integer, from_set: (1..5) ##
|
141
|
-
=> raises EnvParser::ValueNotAllowed</p>
|
142
|
-
|
143
|
-
<h2 id="label-You+can+also+SET+CONSTANTS+DIRECTLY+FROM+YOUR+ENV+VARIABLES.">You can also SET CONSTANTS DIRECTLY FROM YOUR ENV VARIABLES.</h2>
|
144
|
-
|
145
|
-
<h2 id="label-Global+constants...">Global constants…</h2>
|
146
|
-
|
147
|
-
<p>## <a href="'API_KEY'">ENV</a> = 'unbreakable p4$$w0rd'
|
148
|
-
EnvParser.register :API_KEY, as: :string API_KEY ## => 'unbreakable
|
149
|
-
p4$$w0rd' (registered within the Kernel module, so it's available
|
150
|
-
everywhere)</p>
|
151
|
-
|
152
|
-
<h2 id="label-...+and+class-2Fmodule+constants-21">… and class/module constants!</h2>
|
153
|
-
|
154
|
-
<p>## <a href="'ULTIMATE_LINK'">ENV</a> = '<a
|
155
|
-
href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>'
|
156
|
-
EnvParser.register :ULTIMATE_LINK, as: :string, within: URI
|
157
|
-
URI::ULTIMATE_LINK ## => That sweet, sweet link we just set.
|
158
|
-
ULTIMATE_LINK ## => raises NameError (the un-namespaced constant is only
|
159
|
-
in scope within the URI module) “`</p>
|
96
|
+
<h4 id="label-Basic+EnvParser+usage-3A">Basic EnvParser usage:</h4>
|
97
|
+
|
98
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Returns ENV['TIMEOUT_MS'] as an Integer.
|
99
|
+
</span><span class='comment'>## Yields 0 if ENV['TIMEOUT_MS'] is unset or nil.
|
100
|
+
</span><span class='comment'>##
|
101
|
+
</span><span class='id identifier rubyid_timeout_ms'>timeout_ms</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TIMEOUT_MS</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span>
|
102
|
+
|
103
|
+
<span class='comment'>## LESS TYPING, PLZ! :(
|
104
|
+
</span><span class='comment'>## If you pass in a Symbol instead of a String, EnvParser
|
105
|
+
</span><span class='comment'>## will use the value behind the matching String key in ENV.
|
106
|
+
</span><span class='comment'>## (i.e. passing in ENV['X'] is equivalent to passing in :X)
|
107
|
+
</span><span class='comment'>##
|
108
|
+
</span><span class='id identifier rubyid_timeout_ms'>timeout_ms</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:TIMEOUT_MS</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span>
|
109
|
+
</code></pre>
|
160
110
|
<hr>
|
161
111
|
|
162
|
-
<p>The named <code>:as</code>
|
163
|
-
|
164
|
-
<
|
165
|
-
|
166
|
-
|
167
|
-
|
168
|
-
|
169
|
-
|
112
|
+
<p>The named <code>:as</code> parameter is required. Allowed values are:</p>
|
113
|
+
<table>
|
114
|
+
<tbody>
|
115
|
+
<tr>
|
116
|
+
<th><code>:as</code> value</th>
|
117
|
+
<th>type returned</th>
|
118
|
+
</tr>
|
119
|
+
</tbody>
|
120
|
+
<tbody>
|
121
|
+
<tr>
|
122
|
+
<td>:string</td>
|
123
|
+
<td>String</td>
|
124
|
+
</tr>
|
125
|
+
<tr>
|
126
|
+
<td>:symbol</td>
|
127
|
+
<td>Symbol</td>
|
128
|
+
</tr>
|
129
|
+
<tr>
|
130
|
+
<td>:boolean</td>
|
131
|
+
<td>TrueValue / FalseValue</td>
|
132
|
+
</tr>
|
133
|
+
<tr>
|
134
|
+
<td>:int / :integer</td>
|
135
|
+
<td>Integer</td>
|
136
|
+
</tr>
|
137
|
+
<tr>
|
138
|
+
<td>:float / :decimal / :number</td>
|
139
|
+
<td>Float</td>
|
140
|
+
</tr>
|
141
|
+
<tr>
|
142
|
+
<td>:json</td>
|
143
|
+
<td>< depends on JSON given ></td>
|
144
|
+
</tr>
|
145
|
+
<tr>
|
146
|
+
<td>:array</td>
|
147
|
+
<td>Array</td>
|
148
|
+
</tr>
|
149
|
+
<tr>
|
150
|
+
<td>:hash</td>
|
151
|
+
<td>Hash</td>
|
152
|
+
</tr>
|
153
|
+
</tbody>
|
154
|
+
</table>
|
170
155
|
<p>Note JSON is parsed using <em>quirks-mode</em> (meaning 'true',
|
171
156
|
'25', and 'null' are all considered valid, parseable JSON).</p>
|
157
|
+
|
158
|
+
<h4 id="label-Setting+non-trivial+defaults-3A">Setting non-trivial defaults:</h4>
|
159
|
+
|
160
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## If the ENV variable you want is unset (nil) or blank (''),
|
161
|
+
</span><span class='comment'>## the return value is a sensible default for the given "as" type
|
162
|
+
</span><span class='comment'>## (0 or 0.0 for numbers, an empty tring, an empty Array or Hash, etc).
|
163
|
+
</span><span class='comment'>## Sometimes you want a non-trivial default, however.
|
164
|
+
</span><span class='comment'>##
|
165
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:MISSING_ENV_VARIABLE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span> <span class='comment'>## => 0
|
166
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:MISSING_ENV_VARIABLE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>250</span> <span class='comment'>## => 250
|
167
|
+
</span>
|
168
|
+
<span class='comment'>## Note that "if_unset" values are used as-is, with no type conversion.
|
169
|
+
</span><span class='comment'>##
|
170
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:MISSING_ENV_VARIABLE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Whoops!</span><span class='tstring_end'>'</span></span> <span class='comment'>## => 'Whoops!'
|
171
|
+
</span></code></pre>
|
172
|
+
|
173
|
+
<h4 id="label-Validation+of+parsed+ENV+values-3A">Validation of parsed ENV values:</h4>
|
174
|
+
|
175
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Sometimes setting the type alone is a bit too open-ended.
|
176
|
+
</span><span class='comment'>## The "from_set" option lets you restrict the set of allowed values.
|
177
|
+
</span><span class='comment'>##
|
178
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:API_TO_USE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:symbol</span><span class='comma'>,</span> <span class='label'>from_set:</span> <span class='qsymbols_beg'>%i[</span><span class='tstring_content'>internal</span><span class='words_sep'> </span><span class='tstring_content'>external</span><span class='words_sep'>]</span>
|
179
|
+
<span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:SOME_CUSTOM_NETWORK_PORT</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>from_set:</span> <span class='lparen'>(</span><span class='int'>1</span><span class='op'>..</span><span class='int'>65535</span><span class='rparen'>)</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>80</span>
|
180
|
+
|
181
|
+
<span class='comment'>## And if the value is not allowed...
|
182
|
+
</span><span class='comment'>##
|
183
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:NEGATIVE_NUMBER</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>from_set:</span> <span class='lparen'>(</span><span class='int'>1</span><span class='op'>..</span><span class='int'>5</span><span class='rparen'>)</span> <span class='comment'>## => raises EnvParser::ValueNotAllowed
|
184
|
+
</span></code></pre>
|
185
|
+
|
186
|
+
<h4 id="label-Turning+ENV+values+into+constants-3A">Turning ENV values into constants:</h4>
|
187
|
+
|
188
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Global constants...
|
189
|
+
</span><span class='comment'>##
|
190
|
+
</span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>API_KEY</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='comment'>## => 'unbreakable p4$$w0rd' (Set elsewhere, like a ".env" file.)
|
191
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:API_KEY</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span>
|
192
|
+
<span class='const'>API_KEY</span> <span class='comment'>## => 'unbreakable p4$$w0rd' (registered within the Kernel module, so it's available everywhere)
|
193
|
+
</span>
|
194
|
+
<span class='comment'>## ... and class/module constants!
|
195
|
+
</span><span class='comment'>##
|
196
|
+
</span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>ULTIMATE_LINK</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='comment'>## => 'https://youtu.be/L_jWHffIx5E' (Set elsewhere, like a ".env" file.)
|
197
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:ULTIMATE_LINK</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='comma'>,</span> <span class='label'>within:</span> <span class='const'>URI</span>
|
198
|
+
<span class='const'>URI</span><span class='op'>::</span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## => 'https://youtu.be/L_jWHffIx5E' (You know you want to check it out!)
|
199
|
+
</span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## => raises NameError (the un-namespaced constant is only in scope within the URI module)
|
200
|
+
</span></code></pre>
|
201
|
+
|
202
|
+
<h4 id="label-Quickly+registering+multiple+ENV-derived+constants-3A">Quickly registering multiple ENV-derived constants:</h4>
|
203
|
+
|
204
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## You can also set multiple constants in one call, which is considerably cleaner to read:
|
205
|
+
</span><span class='comment'>##
|
206
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:A</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span>
|
207
|
+
<span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:B</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>25</span>
|
208
|
+
<span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:C</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:boolean</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>true</span>
|
209
|
+
<span class='comment'>##
|
210
|
+
</span><span class='comment'>## ... is equivalent to ...
|
211
|
+
</span><span class='comment'>##
|
212
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span><span class='lparen'>(</span>
|
213
|
+
<span class='label'>A:</span> <span class='lbrace'>{</span> <span class='label'>as:</span> <span class='symbol'>:string</span> <span class='rbrace'>}</span><span class='comma'>,</span>
|
214
|
+
<span class='label'>B:</span> <span class='lbrace'>{</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>25</span> <span class='rbrace'>}</span><span class='comma'>,</span>
|
215
|
+
<span class='label'>C:</span> <span class='lbrace'>{</span> <span class='label'>as:</span> <span class='symbol'>:boolean</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>true</span> <span class='rbrace'>}</span>
|
216
|
+
<span class='rparen'>)</span>
|
217
|
+
</code></pre>
|
172
218
|
<hr>
|
173
219
|
|
174
|
-
<p><a
|
175
|
-
|
176
|
-
the repo docs</a> for the full EnvParser documentation.</p>
|
220
|
+
<p><a href="http://nestor-custodio.github.io/env_parser">Consult the repo
|
221
|
+
docs</a> for the full EnvParser documentation.</p>
|
177
222
|
|
178
223
|
<h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
|
179
224
|
|
180
|
-
<p>Additional features/options coming in the future: -
|
181
|
-
<
|
182
|
-
<code
|
183
|
-
<code
|
184
|
-
|
185
|
-
|
186
|
-
|
187
|
-
|
188
|
-
|
189
|
-
“as” types like <code>:url</code>, <code>:email</code>, etc. - … ?</p>
|
225
|
+
<p>Additional features/options coming in the future: - A means to
|
226
|
+
<strong>optionally</strong> bind <code>#parse</code>,
|
227
|
+
<code>#regiter</code>, and <code>#register_all</code> methods onto
|
228
|
+
<code>ENV</code>. Because <code>ENV.parse ...</code> reads better than
|
229
|
+
<code>EnvParser.parse ...</code>. - A <code>validator</code> option that
|
230
|
+
lets you pass in a validator lambda/block for things more complex than what
|
231
|
+
a simple <code>from_set</code> can enforce. - A means to register
|
232
|
+
validation blocks as new “as” types. This will allow for custom “as” types
|
233
|
+
like <code>:url</code>, <code>:email</code>, etc. - … ?</p>
|
190
234
|
|
191
235
|
<h2 id="label-Contribution+-2F+Development">Contribution / Development</h2>
|
192
236
|
|
@@ -217,7 +261,7 @@ href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
|
|
217
261
|
</div></div>
|
218
262
|
|
219
263
|
<div id="footer">
|
220
|
-
Generated on
|
264
|
+
Generated on Sun Dec 3 14:43:03 2017 by
|
221
265
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
222
266
|
0.9.11 (ruby-2.4.2).
|
223
267
|
</div>
|
data/docs/index.html
CHANGED
@@ -93,100 +93,144 @@ simple.</p>
|
|
93
93
|
|
94
94
|
<h2 id="label-Usage">Usage</h2>
|
95
95
|
|
96
|
-
<
|
97
|
-
|
98
|
-
<
|
99
|
-
|
100
|
-
|
101
|
-
|
102
|
-
|
103
|
-
:
|
104
|
-
|
105
|
-
|
106
|
-
|
107
|
-
|
108
|
-
|
109
|
-
|
110
|
-
|
111
|
-
<h2 id="label-28i.e.+passing+in+ENV-5B-27X-27-5D+is+equivalent+to+passing+in+-3AX-29">(i.e. passing in <code>ENV['X']</code> is equivalent to passing in <code>:X</code>)</h2>
|
112
|
-
|
113
|
-
<p>## timeout_ms = EnvParser.parse :TIMEOUT_MS, as: :integer</p>
|
114
|
-
|
115
|
-
<h2 id="label-If+the+ENV+variable+you+want+is+unset+-28nil-29+or+blank+-28-27-27-29-2C">If the ENV variable you want is unset (<code>nil</code>) or blank (<code>''</code>),</h2>
|
116
|
-
|
117
|
-
<h2 id="label-the+return+value+is+a+sensible+default+for+the+given+-22as-22+type.">the return value is a sensible default for the given “as” type.</h2>
|
118
|
-
|
119
|
-
<h2 id="label-Sometimes+you+want+a+non-trivial+default+-28not+just+0-2C+-27-27-2C+etc-29-2C+however.">Sometimes you want a non-trivial default (not just 0, '', etc), however.</h2>
|
120
|
-
|
121
|
-
<p>## EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer ## => 0
|
122
|
-
EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer, if_unset: 250 ## =>
|
123
|
-
250</p>
|
124
|
-
|
125
|
-
<h2 id="label-Note+that+-22if_unset-22+values+are+used+as-is-2C+with+no+type+conversion.">Note that “if_unset” values are used as-is, with no type conversion.</h2>
|
126
|
-
|
127
|
-
<p>## EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer, if_unset:
|
128
|
-
'Whoops!' ## => 'Whoops!'</p>
|
129
|
-
|
130
|
-
<h2 id="label-Sometimes+setting+the+type+alone+is+a+bit+too+open-ended.">Sometimes setting the type alone is a bit too open-ended.</h2>
|
131
|
-
|
132
|
-
<h2 id="label-The+-22from_set-22+option+lets+you+restrict+the+set+of+allowed+values.">The “from_set” option lets you restrict the set of allowed values.</h2>
|
133
|
-
|
134
|
-
<p>## EnvParser.parse :API_TO_USE, as: :symbol, from_set: %i[internal
|
135
|
-
external] EnvParser.parse :SOME_CUSTOM_NETWORK_PORT, as: :integer,
|
136
|
-
from_set: (1..65535), if_unset: 80</p>
|
137
|
-
|
138
|
-
<h2 id="label-And+if+the+value+is+not+allowed...">And if the value is not allowed…</h2>
|
139
|
-
|
140
|
-
<p>## EnvParser.parse :NEGATIVE_NUMBER, as: :integer, from_set: (1..5) ##
|
141
|
-
=> raises EnvParser::ValueNotAllowed</p>
|
142
|
-
|
143
|
-
<h2 id="label-You+can+also+SET+CONSTANTS+DIRECTLY+FROM+YOUR+ENV+VARIABLES.">You can also SET CONSTANTS DIRECTLY FROM YOUR ENV VARIABLES.</h2>
|
144
|
-
|
145
|
-
<h2 id="label-Global+constants...">Global constants…</h2>
|
146
|
-
|
147
|
-
<p>## <a href="'API_KEY'">ENV</a> = 'unbreakable p4$$w0rd'
|
148
|
-
EnvParser.register :API_KEY, as: :string API_KEY ## => 'unbreakable
|
149
|
-
p4$$w0rd' (registered within the Kernel module, so it's available
|
150
|
-
everywhere)</p>
|
151
|
-
|
152
|
-
<h2 id="label-...+and+class-2Fmodule+constants-21">… and class/module constants!</h2>
|
153
|
-
|
154
|
-
<p>## <a href="'ULTIMATE_LINK'">ENV</a> = '<a
|
155
|
-
href="https://youtu.be/L_jWHffIx5E">youtu.be/L_jWHffIx5E</a>'
|
156
|
-
EnvParser.register :ULTIMATE_LINK, as: :string, within: URI
|
157
|
-
URI::ULTIMATE_LINK ## => That sweet, sweet link we just set.
|
158
|
-
ULTIMATE_LINK ## => raises NameError (the un-namespaced constant is only
|
159
|
-
in scope within the URI module) “`</p>
|
96
|
+
<h4 id="label-Basic+EnvParser+usage-3A">Basic EnvParser usage:</h4>
|
97
|
+
|
98
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Returns ENV['TIMEOUT_MS'] as an Integer.
|
99
|
+
</span><span class='comment'>## Yields 0 if ENV['TIMEOUT_MS'] is unset or nil.
|
100
|
+
</span><span class='comment'>##
|
101
|
+
</span><span class='id identifier rubyid_timeout_ms'>timeout_ms</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>TIMEOUT_MS</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span>
|
102
|
+
|
103
|
+
<span class='comment'>## LESS TYPING, PLZ! :(
|
104
|
+
</span><span class='comment'>## If you pass in a Symbol instead of a String, EnvParser
|
105
|
+
</span><span class='comment'>## will use the value behind the matching String key in ENV.
|
106
|
+
</span><span class='comment'>## (i.e. passing in ENV['X'] is equivalent to passing in :X)
|
107
|
+
</span><span class='comment'>##
|
108
|
+
</span><span class='id identifier rubyid_timeout_ms'>timeout_ms</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:TIMEOUT_MS</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span>
|
109
|
+
</code></pre>
|
160
110
|
<hr>
|
161
111
|
|
162
|
-
<p>The named <code>:as</code>
|
163
|
-
|
164
|
-
<
|
165
|
-
|
166
|
-
|
167
|
-
|
168
|
-
|
169
|
-
|
112
|
+
<p>The named <code>:as</code> parameter is required. Allowed values are:</p>
|
113
|
+
<table>
|
114
|
+
<tbody>
|
115
|
+
<tr>
|
116
|
+
<th><code>:as</code> value</th>
|
117
|
+
<th>type returned</th>
|
118
|
+
</tr>
|
119
|
+
</tbody>
|
120
|
+
<tbody>
|
121
|
+
<tr>
|
122
|
+
<td>:string</td>
|
123
|
+
<td>String</td>
|
124
|
+
</tr>
|
125
|
+
<tr>
|
126
|
+
<td>:symbol</td>
|
127
|
+
<td>Symbol</td>
|
128
|
+
</tr>
|
129
|
+
<tr>
|
130
|
+
<td>:boolean</td>
|
131
|
+
<td>TrueValue / FalseValue</td>
|
132
|
+
</tr>
|
133
|
+
<tr>
|
134
|
+
<td>:int / :integer</td>
|
135
|
+
<td>Integer</td>
|
136
|
+
</tr>
|
137
|
+
<tr>
|
138
|
+
<td>:float / :decimal / :number</td>
|
139
|
+
<td>Float</td>
|
140
|
+
</tr>
|
141
|
+
<tr>
|
142
|
+
<td>:json</td>
|
143
|
+
<td>< depends on JSON given ></td>
|
144
|
+
</tr>
|
145
|
+
<tr>
|
146
|
+
<td>:array</td>
|
147
|
+
<td>Array</td>
|
148
|
+
</tr>
|
149
|
+
<tr>
|
150
|
+
<td>:hash</td>
|
151
|
+
<td>Hash</td>
|
152
|
+
</tr>
|
153
|
+
</tbody>
|
154
|
+
</table>
|
170
155
|
<p>Note JSON is parsed using <em>quirks-mode</em> (meaning 'true',
|
171
156
|
'25', and 'null' are all considered valid, parseable JSON).</p>
|
157
|
+
|
158
|
+
<h4 id="label-Setting+non-trivial+defaults-3A">Setting non-trivial defaults:</h4>
|
159
|
+
|
160
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## If the ENV variable you want is unset (nil) or blank (''),
|
161
|
+
</span><span class='comment'>## the return value is a sensible default for the given "as" type
|
162
|
+
</span><span class='comment'>## (0 or 0.0 for numbers, an empty tring, an empty Array or Hash, etc).
|
163
|
+
</span><span class='comment'>## Sometimes you want a non-trivial default, however.
|
164
|
+
</span><span class='comment'>##
|
165
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:MISSING_ENV_VARIABLE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span> <span class='comment'>## => 0
|
166
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:MISSING_ENV_VARIABLE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>250</span> <span class='comment'>## => 250
|
167
|
+
</span>
|
168
|
+
<span class='comment'>## Note that "if_unset" values are used as-is, with no type conversion.
|
169
|
+
</span><span class='comment'>##
|
170
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:MISSING_ENV_VARIABLE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Whoops!</span><span class='tstring_end'>'</span></span> <span class='comment'>## => 'Whoops!'
|
171
|
+
</span></code></pre>
|
172
|
+
|
173
|
+
<h4 id="label-Validation+of+parsed+ENV+values-3A">Validation of parsed ENV values:</h4>
|
174
|
+
|
175
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Sometimes setting the type alone is a bit too open-ended.
|
176
|
+
</span><span class='comment'>## The "from_set" option lets you restrict the set of allowed values.
|
177
|
+
</span><span class='comment'>##
|
178
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:API_TO_USE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:symbol</span><span class='comma'>,</span> <span class='label'>from_set:</span> <span class='qsymbols_beg'>%i[</span><span class='tstring_content'>internal</span><span class='words_sep'> </span><span class='tstring_content'>external</span><span class='words_sep'>]</span>
|
179
|
+
<span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:SOME_CUSTOM_NETWORK_PORT</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>from_set:</span> <span class='lparen'>(</span><span class='int'>1</span><span class='op'>..</span><span class='int'>65535</span><span class='rparen'>)</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>80</span>
|
180
|
+
|
181
|
+
<span class='comment'>## And if the value is not allowed...
|
182
|
+
</span><span class='comment'>##
|
183
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span> <span class='symbol'>:NEGATIVE_NUMBER</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>from_set:</span> <span class='lparen'>(</span><span class='int'>1</span><span class='op'>..</span><span class='int'>5</span><span class='rparen'>)</span> <span class='comment'>## => raises EnvParser::ValueNotAllowed
|
184
|
+
</span></code></pre>
|
185
|
+
|
186
|
+
<h4 id="label-Turning+ENV+values+into+constants-3A">Turning ENV values into constants:</h4>
|
187
|
+
|
188
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Global constants...
|
189
|
+
</span><span class='comment'>##
|
190
|
+
</span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>API_KEY</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='comment'>## => 'unbreakable p4$$w0rd' (Set elsewhere, like a ".env" file.)
|
191
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:API_KEY</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span>
|
192
|
+
<span class='const'>API_KEY</span> <span class='comment'>## => 'unbreakable p4$$w0rd' (registered within the Kernel module, so it's available everywhere)
|
193
|
+
</span>
|
194
|
+
<span class='comment'>## ... and class/module constants!
|
195
|
+
</span><span class='comment'>##
|
196
|
+
</span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>ULTIMATE_LINK</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='comment'>## => 'https://youtu.be/L_jWHffIx5E' (Set elsewhere, like a ".env" file.)
|
197
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:ULTIMATE_LINK</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='comma'>,</span> <span class='label'>within:</span> <span class='const'>URI</span>
|
198
|
+
<span class='const'>URI</span><span class='op'>::</span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## => 'https://youtu.be/L_jWHffIx5E' (You know you want to check it out!)
|
199
|
+
</span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## => raises NameError (the un-namespaced constant is only in scope within the URI module)
|
200
|
+
</span></code></pre>
|
201
|
+
|
202
|
+
<h4 id="label-Quickly+registering+multiple+ENV-derived+constants-3A">Quickly registering multiple ENV-derived constants:</h4>
|
203
|
+
|
204
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## You can also set multiple constants in one call, which is considerably cleaner to read:
|
205
|
+
</span><span class='comment'>##
|
206
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:A</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span>
|
207
|
+
<span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:B</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>25</span>
|
208
|
+
<span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span> <span class='symbol'>:C</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:boolean</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>true</span>
|
209
|
+
<span class='comment'>##
|
210
|
+
</span><span class='comment'>## ... is equivalent to ...
|
211
|
+
</span><span class='comment'>##
|
212
|
+
</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="EnvParser.html#register-class_method" title="EnvParser.register (method)">register</a></span></span><span class='lparen'>(</span>
|
213
|
+
<span class='label'>A:</span> <span class='lbrace'>{</span> <span class='label'>as:</span> <span class='symbol'>:string</span> <span class='rbrace'>}</span><span class='comma'>,</span>
|
214
|
+
<span class='label'>B:</span> <span class='lbrace'>{</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='int'>25</span> <span class='rbrace'>}</span><span class='comma'>,</span>
|
215
|
+
<span class='label'>C:</span> <span class='lbrace'>{</span> <span class='label'>as:</span> <span class='symbol'>:boolean</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>true</span> <span class='rbrace'>}</span>
|
216
|
+
<span class='rparen'>)</span>
|
217
|
+
</code></pre>
|
172
218
|
<hr>
|
173
219
|
|
174
|
-
<p><a
|
175
|
-
|
176
|
-
the repo docs</a> for the full EnvParser documentation.</p>
|
220
|
+
<p><a href="http://nestor-custodio.github.io/env_parser">Consult the repo
|
221
|
+
docs</a> for the full EnvParser documentation.</p>
|
177
222
|
|
178
223
|
<h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
|
179
224
|
|
180
|
-
<p>Additional features/options coming in the future: -
|
181
|
-
<
|
182
|
-
<code
|
183
|
-
<code
|
184
|
-
|
185
|
-
|
186
|
-
|
187
|
-
|
188
|
-
|
189
|
-
“as” types like <code>:url</code>, <code>:email</code>, etc. - … ?</p>
|
225
|
+
<p>Additional features/options coming in the future: - A means to
|
226
|
+
<strong>optionally</strong> bind <code>#parse</code>,
|
227
|
+
<code>#regiter</code>, and <code>#register_all</code> methods onto
|
228
|
+
<code>ENV</code>. Because <code>ENV.parse ...</code> reads better than
|
229
|
+
<code>EnvParser.parse ...</code>. - A <code>validator</code> option that
|
230
|
+
lets you pass in a validator lambda/block for things more complex than what
|
231
|
+
a simple <code>from_set</code> can enforce. - A means to register
|
232
|
+
validation blocks as new “as” types. This will allow for custom “as” types
|
233
|
+
like <code>:url</code>, <code>:email</code>, etc. - … ?</p>
|
190
234
|
|
191
235
|
<h2 id="label-Contribution+-2F+Development">Contribution / Development</h2>
|
192
236
|
|
@@ -217,7 +261,7 @@ href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
|
|
217
261
|
</div></div>
|
218
262
|
|
219
263
|
<div id="footer">
|
220
|
-
Generated on
|
264
|
+
Generated on Sun Dec 3 14:43:03 2017 by
|
221
265
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
222
266
|
0.9.11 (ruby-2.4.2).
|
223
267
|
</div>
|
@@ -100,7 +100,7 @@
|
|
100
100
|
</div>
|
101
101
|
|
102
102
|
<div id="footer">
|
103
|
-
Generated on
|
103
|
+
Generated on Sun Dec 3 14:43:03 2017 by
|
104
104
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
105
105
|
0.9.11 (ruby-2.4.2).
|
106
106
|
</div>
|
data/lib/env_parser/version.rb
CHANGED
data/lib/env_parser.rb
CHANGED
@@ -76,6 +76,24 @@ class EnvParser
|
|
76
76
|
|
77
77
|
## Parses the referenced value and creates a matching constant in the requested context.
|
78
78
|
##
|
79
|
+
## Multiple calls to "register" may be shortcutted by passing in a Hash with the same keys as
|
80
|
+
## those in the "from" Hash and each value being the "register" options set for each variable's
|
81
|
+
## "register" call.
|
82
|
+
##
|
83
|
+
## <pre>
|
84
|
+
## ## Example shortcut usage:
|
85
|
+
##
|
86
|
+
## EnvParser.register :A, from: one_hash, as: :integer
|
87
|
+
## EnvParser.register :B, from: another_hash, as: :string, if_unset: 'none'
|
88
|
+
##
|
89
|
+
## ## ... is equivalent to ...
|
90
|
+
##
|
91
|
+
## EnvParser.register(
|
92
|
+
## A: { from: ENV, as: :integer }
|
93
|
+
## B: { from: other_hash, as: :string, if_unset: 'none' }
|
94
|
+
## )
|
95
|
+
## </pre>
|
96
|
+
##
|
79
97
|
## @param name
|
80
98
|
## The name of the value to parse/interpret from the "from" Hash. If the "from" value is ENV,
|
81
99
|
## you may give a Symbol and the corresponding String key will be used instead.
|
@@ -99,6 +117,10 @@ class EnvParser
|
|
99
117
|
## @raise [ArgumentError]
|
100
118
|
##
|
101
119
|
def register(name, options = {})
|
120
|
+
## We want to allow for registering multiple variables simultaneously via a single `.register`
|
121
|
+
## method call.
|
122
|
+
return register_all(name) if name.is_a? Hash
|
123
|
+
|
102
124
|
from = options.fetch(:from, ENV)
|
103
125
|
within = options.fetch(:within, Kernel)
|
104
126
|
|
@@ -178,6 +200,14 @@ class EnvParser
|
|
178
200
|
decoded_json
|
179
201
|
end
|
180
202
|
|
203
|
+
## Verifies that the given "value" is included in the "set".
|
204
|
+
##
|
205
|
+
## @param value
|
206
|
+
##
|
207
|
+
## @param set [Array, Range]
|
208
|
+
##
|
209
|
+
## @raise [ArgumentError, EnvParser::ValueNotAllowed]
|
210
|
+
##
|
181
211
|
def check_for_set_inclusion(value, set: nil)
|
182
212
|
if value.respond_to?(:each)
|
183
213
|
raise ArgumentError, "`from_set` option is not compatible with #{value.class} values"
|
@@ -189,5 +219,22 @@ class EnvParser
|
|
189
219
|
|
190
220
|
raise ValueNotAllowed, 'parsed value not in allowed list/range' unless set.include?(value)
|
191
221
|
end
|
222
|
+
|
223
|
+
## Receives a list of "register" calls to make, as a Hash keyed with variable names and the
|
224
|
+
## values being each "register" call's option set.
|
225
|
+
##
|
226
|
+
## @param list [Hash]
|
227
|
+
##
|
228
|
+
## @return [Hash]
|
229
|
+
##
|
230
|
+
## @raise [ArgumentError]
|
231
|
+
##
|
232
|
+
def register_all(list)
|
233
|
+
raise ArgumentError, "invalid 'list' parameter type: #{list.class}" unless list.is_a?(Hash)
|
234
|
+
|
235
|
+
list.to_a.each_with_object({}) do |tuple, output|
|
236
|
+
output[tuple.first] = register(tuple.first, tuple.second)
|
237
|
+
end
|
238
|
+
end
|
192
239
|
end
|
193
240
|
end
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: env_parser
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.5.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Nestor Custodio
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date: 2017-12-
|
11
|
+
date: 2017-12-03 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: bundler
|