env_parser 0.8.0 → 1.0.0
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 +4 -4
- data/Gemfile.lock +1 -1
- data/README.md +102 -115
- data/docs/EnvParser.html +128 -123
- data/docs/EnvParser/Error.html +4 -4
- data/docs/EnvParser/TypeAlreadyDefinedError.html +143 -0
- data/docs/EnvParser/UnknownTypeError.html +143 -0
- data/docs/EnvParser/ValueNotAllowedError.html +145 -0
- data/docs/EnvParser/ValueNotConvertibleError.html +144 -0
- data/docs/EnvParserTypes.html +127 -0
- data/docs/EnvParserTypes/BaseTypes.html +160 -0
- data/docs/_index.html +45 -3
- data/docs/class_list.html +1 -1
- data/docs/file.README.html +121 -132
- data/docs/index.html +121 -132
- data/docs/top-level-namespace.html +6 -4
- data/lib/env_parser.rb +66 -79
- data/lib/env_parser/errors.rb +28 -0
- data/lib/env_parser/types.rb +3 -0
- data/lib/env_parser/types/base_types.rb +80 -26
- data/lib/env_parser/version.rb +1 -1
- metadata +10 -2
data/docs/class_list.html
CHANGED
@@ -43,7 +43,7 @@
|
|
43
43
|
|
44
44
|
<ul id="full_list" class="class">
|
45
45
|
<li id="object_" class="odd"><div class="item" style="padding-left:30px"><span class='object_link'><a href="top-level-namespace.html" title="Top Level Namespace (root)">Top Level Namespace</a></span></div></li>
|
46
|
-
<li id='object_EnvParser' class='even'><div class='item' style='padding-left:30px'><a class='toggle'></a> <span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span> < Object<small class='search_info'>Top Level Namespace</small></div><ul><li id='object_EnvParser::Error' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="EnvParser/Error.html" title="EnvParser::Error (class)">Error</a></span> < StandardError<small class='search_info'>EnvParser</small></div></li><li id='object_EnvParser::
|
46
|
+
<li id='object_EnvParser' class='even'><div class='item' style='padding-left:30px'><a class='toggle'></a> <span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span> < Object<small class='search_info'>Top Level Namespace</small></div><ul><li id='object_EnvParser::Error' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="EnvParser/Error.html" title="EnvParser::Error (class)">Error</a></span> < StandardError<small class='search_info'>EnvParser</small></div></li><li id='object_EnvParser::TypeAlreadyDefinedError' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="EnvParser/TypeAlreadyDefinedError.html" title="EnvParser::TypeAlreadyDefinedError (class)">TypeAlreadyDefinedError</a></span> < Error<small class='search_info'>EnvParser</small></div></li><li id='object_EnvParser::UnknownTypeError' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="EnvParser/UnknownTypeError.html" title="EnvParser::UnknownTypeError (class)">UnknownTypeError</a></span> < Error<small class='search_info'>EnvParser</small></div></li><li id='object_EnvParser::ValueNotAllowedError' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="EnvParser/ValueNotAllowedError.html" title="EnvParser::ValueNotAllowedError (class)">ValueNotAllowedError</a></span> < Error<small class='search_info'>EnvParser</small></div></li><li id='object_EnvParser::ValueNotConvertibleError' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="EnvParser/ValueNotConvertibleError.html" title="EnvParser::ValueNotConvertibleError (class)">ValueNotConvertibleError</a></span> < Error<small class='search_info'>EnvParser</small></div></li></ul></li><li id='object_EnvParserTypes' class='even'><div class='item' style='padding-left:30px'><a class='toggle'></a> <span class='object_link'><a href="EnvParserTypes.html" title="EnvParserTypes (module)">EnvParserTypes</a></span><small class='search_info'>Top Level Namespace</small></div><ul><li id='object_EnvParserTypes::BaseTypes' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="EnvParserTypes/BaseTypes.html" title="EnvParserTypes::BaseTypes (module)">BaseTypes</a></span><small class='search_info'>EnvParserTypes</small></div></li></ul></li>
|
47
47
|
|
48
48
|
</ul>
|
49
49
|
</div>
|
data/docs/file.README.html
CHANGED
@@ -63,17 +63,19 @@
|
|
63
63
|
<p>If your code uses environment variables, you know that <code>ENV</code>
|
64
64
|
will always surface these as strings. Interpreting these strings as the
|
65
65
|
value you <em>actually</em> want to see/use takes some work, however: for
|
66
|
-
numbers you need to cast with <code
|
66
|
+
numbers you need to cast with <code>to_i</code> or <code>to_f</code> … for
|
67
67
|
booleans you need to check for a specific value (<code>ENV['SOME_VAR'] ==
|
68
|
-
'true'</code>)
|
69
|
-
(something other than <code>0</code> or <code>''</code>)?
|
70
|
-
only want to allow values from a limited set? …</p>
|
68
|
+
'true'</code>) … maybe you want to set non-trivial defaults
|
69
|
+
(something other than <code>0</code> or <code>''</code>)? … maybe
|
70
|
+
you only want to allow values from a limited set? …</p>
|
71
71
|
|
72
72
|
<p>Things can get out of control pretty fast, especially as the number of
|
73
73
|
environment variables in play grows. Tools like <a
|
74
74
|
href="https://github.com/bkeepers/dotenv">dotenv</a> help to make sure
|
75
|
-
you're loading the correct set of
|
76
|
-
|
75
|
+
you're loading the correct <strong>set</strong> of variables, but <a
|
76
|
+
href="https://github.com/nestor-custodio/env_parser">EnvParser</a> makes
|
77
|
+
<strong><em>the values themselves</em></strong> usable with a minimum of
|
78
|
+
effort.</p>
|
77
79
|
|
78
80
|
<h2 id="label-Installation">Installation</h2>
|
79
81
|
|
@@ -92,68 +94,28 @@ makes <em>the values themselves</em> usable with a minimum of effort.</p>
|
|
92
94
|
|
93
95
|
<h2 id="label-Using+EnvParser">Using EnvParser</h2>
|
94
96
|
|
95
|
-
<
|
97
|
+
<h3 id="label-Basic+Usage">Basic Usage</h3>
|
98
|
+
|
99
|
+
<h4 id="label-Parsing+ENV+Values">Parsing ENV Values</h4>
|
100
|
+
|
101
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Returns ENV['TIMEOUT_MS'] as an Integer,
|
102
|
+
</span><span class='comment'>## or 0 if ENV['TIMEOUT_MS'] is unset or nil.
|
103
|
+
</span>
|
104
|
+
<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>
|
96
105
|
|
97
|
-
<pre class="code ruby"><code class="ruby"><span class='comment'>## Returns ENV['TIMEOUT_MS'] as an Integer.
|
98
|
-
</span><span class='comment'>## Yields 0 if ENV['TIMEOUT_MS'] is unset or nil.
|
99
|
-
</span><span class='comment'>##
|
100
|
-
</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>
|
101
106
|
|
102
107
|
<span class='comment'>## LESS TYPING, PLZ! :(
|
103
108
|
</span><span class='comment'>## If you pass in a Symbol instead of a String, EnvParser
|
104
109
|
</span><span class='comment'>## will use the value behind the matching String key in ENV.
|
105
110
|
</span><span class='comment'>## (i.e. passing in ENV['X'] is equivalent to passing in :X)
|
106
|
-
</span
|
107
|
-
|
111
|
+
</span>
|
112
|
+
<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>
|
108
113
|
</code></pre>
|
109
|
-
<hr>
|
110
114
|
|
111
|
-
<p>
|
112
|
-
|
113
|
-
|
114
|
-
|
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>
|
155
|
-
<p>Note JSON is parsed using <em>quirks-mode</em> (meaning 'true',
|
156
|
-
'25', and 'null' are all considered valid, parseable JSON).</p>
|
115
|
+
<p>For a full list of all “as” types available out-of-the-box, <a
|
116
|
+
href="http://nestor-custodio.github.io/env_parser/EnvParserTypes.html">see
|
117
|
+
the documentation for modules listed under EnvParserTypes</a>.</p>
|
118
|
+
<hr>
|
157
119
|
|
158
120
|
<h4 id="label-Setting+Non-Trivial+Defaults">Setting Non-Trivial Defaults</h4>
|
159
121
|
|
@@ -161,99 +123,130 @@ values is user-expandable, but allowed values out-of-the-box are:</p>
|
|
161
123
|
</span><span class='comment'>## the return value is a sensible default for the given "as" type
|
162
124
|
</span><span class='comment'>## (0 or 0.0 for numbers, an empty tring, an empty Array or Hash, etc).
|
163
125
|
</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
126
|
</span>
|
168
|
-
<span class='
|
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-Validating+Parsed+ENV+Values">Validating 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
|
127
|
+
<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
|
128
|
+
</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
|
184
129
|
</span>
|
185
130
|
|
186
|
-
<span class='comment'>##
|
187
|
-
</span
|
188
|
-
|
189
|
-
|
190
|
-
<
|
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_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span><span class='lparen'>(</span><span class='symbol'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_value'>value</span><span class='op'>|</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
|
192
|
-
<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='lparen'>(</span><span class='symbol'>:CONNECTION_RETRIES</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='op'>&</span><span class='symbol'>:nonzero?</span><span class='rparen'>)</span>
|
193
|
-
</code></pre>
|
131
|
+
<span class='comment'>## Note that "if_unset" values are used as-is, with no type conversion.
|
132
|
+
</span>
|
133
|
+
<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'>Careful!</span><span class='tstring_end'>'</span></span> <span class='comment'>## => 'Careful!'
|
134
|
+
</span></code></pre>
|
135
|
+
<hr>
|
194
136
|
|
195
137
|
<h4 id="label-Setting+Constants+From+ENV+Values">Setting Constants From ENV Values</h4>
|
196
138
|
|
197
139
|
<pre class="code ruby"><code class="ruby"><span class='comment'>## Global constants...
|
198
|
-
</span><span class='comment'>##
|
199
|
-
</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.)
|
200
|
-
</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>
|
201
|
-
<span class='const'>API_KEY</span> <span class='comment'>## => 'unbreakable p4$$w0rd' (registered within the Kernel module, so it's available everywhere)
|
202
140
|
</span>
|
203
|
-
<span class='comment'>##
|
204
|
-
</span
|
205
|
-
|
206
|
-
|
207
|
-
|
208
|
-
|
141
|
+
<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'
|
142
|
+
</span>
|
143
|
+
<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>
|
144
|
+
<span class='const'>API_KEY</span> <span class='comment'>## => 'unbreakable p4$$w0rd' (registered within the Kernel module, so it's available everywhere)
|
145
|
+
</span>
|
146
|
+
|
147
|
+
<span class='comment'>## ... and class/module-level constants!
|
148
|
+
</span>
|
149
|
+
<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'
|
150
|
+
</span>
|
151
|
+
<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>
|
152
|
+
<span class='const'>URI</span><span class='op'>::</span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## => 'https://youtu.be/L_jWHffIx5E'
|
153
|
+
</span>
|
154
|
+
<span class='const'>ULTIMATE_LINK</span> <span class='comment'>## => raises NameError (the un-namespaced constant is only in scope within the URI module)
|
209
155
|
</span>
|
210
156
|
|
157
|
+
|
158
|
+
|
211
159
|
<span class='comment'>## You can also set multiple constants in one call, which is considerably cleaner to read:
|
212
|
-
</span
|
213
|
-
|
160
|
+
</span>
|
161
|
+
<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>
|
214
162
|
<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>
|
215
163
|
<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>
|
216
164
|
|
165
|
+
|
217
166
|
<span class='comment'>## ... is equivalent to ...
|
218
|
-
</span
|
219
|
-
|
167
|
+
</span>
|
168
|
+
<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>
|
220
169
|
<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>
|
221
170
|
<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>
|
222
171
|
<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>
|
223
172
|
<span class='rparen'>)</span>
|
224
173
|
</code></pre>
|
174
|
+
<hr>
|
225
175
|
|
226
176
|
<h4 id="label-Binding+EnvParser+Proxies+Onto+ENV">Binding EnvParser Proxies Onto ENV</h4>
|
227
177
|
|
228
|
-
<pre class="code ruby"><code class="ruby"><span class='comment'>##
|
229
|
-
</span><span class='comment'>## This is done
|
230
|
-
</span><span class='comment'>##
|
231
|
-
</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_add_env_bindings'><span class='object_link'><a href="EnvParser.html#add_env_bindings-class_method" title="EnvParser.add_env_bindings (method)">add_env_bindings</a></span></span> <span class='comment'>## Sets up the proxy methods.
|
178
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## You can bind proxy "parse" and "register" methods onto ENV.
|
179
|
+
</span><span class='comment'>## This is done without polluting the method space for other objects.
|
232
180
|
</span>
|
233
|
-
<span class='
|
234
|
-
</span
|
235
|
-
|
236
|
-
|
237
|
-
</span><span class='
|
238
|
-
</span
|
181
|
+
<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_add_env_bindings'><span class='object_link'><a href="EnvParser.html#add_env_bindings-class_method" title="EnvParser.add_env_bindings (method)">add_env_bindings</a></span></span> <span class='comment'>## Sets up the proxy methods.
|
182
|
+
</span>
|
183
|
+
|
184
|
+
<span class='comment'>## Now you can call "parse" and "register" on ENV itself,
|
185
|
+
</span><span class='comment'>## which is more legible and feels more straight-forward.
|
186
|
+
</span>
|
187
|
+
<span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='comment'>## => '3.1415926'
|
188
|
+
</span>
|
189
|
+
<span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:SHORT_PI</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:float</span> <span class='comment'>## => 3.1415926
|
190
|
+
</span><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_register'>register</span> <span class='symbol'>:SHORT_PI</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:float</span> <span class='comment'>## Your constant is set, my man!
|
191
|
+
</span>
|
192
|
+
|
193
|
+
<span class='comment'>## Note that ENV's proxy "parse" method will *always* interpret the
|
194
|
+
</span><span class='comment'>## value given as an ENV key (converting to a String, if necessary).
|
195
|
+
</span><span class='comment'>## This is different from the non-proxy "parse" method, which will use
|
196
|
+
</span><span class='comment'>## String values as-is and only looks up ENV values when given a Symbol.
|
239
197
|
</span></code></pre>
|
240
198
|
|
241
|
-
<
|
199
|
+
<h3 id="label-Advanced+Usage">Advanced Usage</h3>
|
200
|
+
|
201
|
+
<h4 id="label-Custom+Validation+Of+Parsed+Values">Custom Validation Of Parsed Values</h4>
|
202
|
+
|
203
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Sometimes setting the type alone is a bit too open-ended.
|
204
|
+
</span><span class='comment'>## The "from_set" option lets you restrict the set of allowed values.
|
205
|
+
</span>
|
206
|
+
<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>
|
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_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>
|
208
|
+
|
209
|
+
|
210
|
+
<span class='comment'>## And if the value is not allowed...
|
211
|
+
</span>
|
212
|
+
<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
|
213
|
+
</span>
|
214
|
+
|
242
215
|
|
243
|
-
|
244
|
-
|
245
|
-
</span
|
246
|
-
|
216
|
+
|
217
|
+
<span class='comment'>## The "validated_by" option allows for more complex validation.
|
218
|
+
</span>
|
219
|
+
<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'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='comma'>,</span> <span class='label'>validated_by:</span> <span class='tlambda'>-></span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span> <span class='tlambeg'>{</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
|
220
|
+
|
221
|
+
|
222
|
+
<span class='comment'>## ... but a block will also do the trick!
|
223
|
+
</span>
|
224
|
+
<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='lparen'>(</span><span class='symbol'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_value'>value</span><span class='op'>|</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
|
225
|
+
<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='lparen'>(</span><span class='symbol'>:CONNECTION_RETRIES</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='op'>&</span><span class='symbol'>:nonzero?</span><span class='rparen'>)</span>
|
226
|
+
</code></pre>
|
227
|
+
<hr>
|
228
|
+
|
229
|
+
<h4 id="label-Defining+Your+Own+EnvParser+-22as-22+Types">Defining Your Own EnvParser “as” Types</h4>
|
230
|
+
|
231
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## If you use a particular validation many times,
|
232
|
+
</span><span class='comment'>## or are often manipulating values in the same way
|
233
|
+
</span><span class='comment'>## after EnvParser has done its thing, you may want
|
234
|
+
</span><span class='comment'>## to register a new type altogether.
|
235
|
+
</span>
|
236
|
+
<span class='id identifier rubyid_a'>a</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'>:A</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:int</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>nil</span>
|
247
237
|
<span class='id identifier rubyid_raise'>raise</span> <span class='kw'>unless</span> <span class='id identifier rubyid_passes_all_my_checks?'>passes_all_my_checks?</span><span class='lparen'>(</span><span class='id identifier rubyid_a'>a</span><span class='rparen'>)</span>
|
248
238
|
|
249
239
|
<span class='id identifier rubyid_b'>b</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'>:B</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:int</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>nil</span>
|
250
240
|
<span class='id identifier rubyid_raise'>raise</span> <span class='kw'>unless</span> <span class='id identifier rubyid_passes_all_my_checks?'>passes_all_my_checks?</span><span class='lparen'>(</span><span class='id identifier rubyid_b'>b</span><span class='rparen'>)</span>
|
251
241
|
|
242
|
+
|
252
243
|
<span class='comment'>## ... is perhaps best handled by defining a new type:
|
253
|
-
</span
|
254
|
-
|
244
|
+
</span>
|
245
|
+
<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_define_type'><span class='object_link'><a href="EnvParser.html#define_type-class_method" title="EnvParser.define_type (method)">define_type</a></span></span><span class='lparen'>(</span><span class='symbol'>:my_special_type_of_number</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>nil</span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_value'>value</span><span class='op'>|</span>
|
255
246
|
<span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_to_i'>to_i</span>
|
256
|
-
<span class='
|
247
|
+
<span class='kw'>unless</span> <span class='id identifier rubyid_passes_all_my_checks?'>passes_all_my_checks?</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span>
|
248
|
+
<span class='id identifier rubyid_raise'>raise</span><span class='lparen'>(</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="EnvParser/ValueNotConvertibleError.html" title="EnvParser::ValueNotConvertibleError (class)">ValueNotConvertibleError</a></span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>cannot parse as a "special type number"</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
249
|
+
<span class='kw'>end</span>
|
257
250
|
|
258
251
|
<span class='id identifier rubyid_value'>value</span>
|
259
252
|
<span class='kw'>end</span>
|
@@ -261,14 +254,17 @@ values is user-expandable, but allowed values out-of-the-box are:</p>
|
|
261
254
|
<span class='id identifier rubyid_a'>a</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'>:A</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:my_special_type_of_number</span>
|
262
255
|
<span class='id identifier rubyid_b'>b</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'>:B</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:my_special_type_of_number</span>
|
263
256
|
|
264
|
-
|
265
|
-
|
266
|
-
</span><span class='comment'>##
|
257
|
+
|
258
|
+
<span class='comment'>## Defining a new type makes your code both more maintainable
|
259
|
+
</span><span class='comment'>## (all the logic for your special type is only defined once)
|
260
|
+
</span><span class='comment'>## and more readable (your "parse" calls aren't littered with
|
261
|
+
</span><span class='comment'>## type-checking cruft).
|
267
262
|
</span></code></pre>
|
268
263
|
<hr>
|
269
264
|
|
270
|
-
<p><a
|
271
|
-
|
265
|
+
<p><a
|
266
|
+
href="http://nestor-custodio.github.io/env_parser/EnvParser.html">Consult
|
267
|
+
the repo docs for the full EnvParser documentation.</a></p>
|
272
268
|
|
273
269
|
<h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
|
274
270
|
|
@@ -295,13 +291,6 @@ href="https://github.com/bbatsov/rubocop">Rubocop</a> and documentation is
|
|
295
291
|
built using <a href="https://yardoc.org/">Yard</a>. Neither is included in
|
296
292
|
the Gemspec; you'll need to install these locally to take advantage.</p>
|
297
293
|
|
298
|
-
<p>To install this gem onto your local machine, run <code>bundle exec rake
|
299
|
-
install</code>. To release a new version, update the version number in
|
300
|
-
<code>version.rb</code>, and then run <code>bundle exec rake
|
301
|
-
release</code>, which will create a git tag for the version, push git
|
302
|
-
commits and tags, and push the <code>.gem</code> file to <a
|
303
|
-
href="https://rubygems.org">rubygems.org</a>.</p>
|
304
|
-
|
305
294
|
<h2 id="label-License">License</h2>
|
306
295
|
|
307
296
|
<p>The gem is available as open source under the terms of the <a
|
@@ -309,7 +298,7 @@ href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
|
|
309
298
|
</div></div>
|
310
299
|
|
311
300
|
<div id="footer">
|
312
|
-
Generated on
|
301
|
+
Generated on Mon Dec 25 19:13:02 2017 by
|
313
302
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
314
303
|
0.9.11 (ruby-2.4.2).
|
315
304
|
</div>
|
data/docs/index.html
CHANGED
@@ -63,17 +63,19 @@
|
|
63
63
|
<p>If your code uses environment variables, you know that <code>ENV</code>
|
64
64
|
will always surface these as strings. Interpreting these strings as the
|
65
65
|
value you <em>actually</em> want to see/use takes some work, however: for
|
66
|
-
numbers you need to cast with <code
|
66
|
+
numbers you need to cast with <code>to_i</code> or <code>to_f</code> … for
|
67
67
|
booleans you need to check for a specific value (<code>ENV['SOME_VAR'] ==
|
68
|
-
'true'</code>)
|
69
|
-
(something other than <code>0</code> or <code>''</code>)?
|
70
|
-
only want to allow values from a limited set? …</p>
|
68
|
+
'true'</code>) … maybe you want to set non-trivial defaults
|
69
|
+
(something other than <code>0</code> or <code>''</code>)? … maybe
|
70
|
+
you only want to allow values from a limited set? …</p>
|
71
71
|
|
72
72
|
<p>Things can get out of control pretty fast, especially as the number of
|
73
73
|
environment variables in play grows. Tools like <a
|
74
74
|
href="https://github.com/bkeepers/dotenv">dotenv</a> help to make sure
|
75
|
-
you're loading the correct set of
|
76
|
-
|
75
|
+
you're loading the correct <strong>set</strong> of variables, but <a
|
76
|
+
href="https://github.com/nestor-custodio/env_parser">EnvParser</a> makes
|
77
|
+
<strong><em>the values themselves</em></strong> usable with a minimum of
|
78
|
+
effort.</p>
|
77
79
|
|
78
80
|
<h2 id="label-Installation">Installation</h2>
|
79
81
|
|
@@ -92,68 +94,28 @@ makes <em>the values themselves</em> usable with a minimum of effort.</p>
|
|
92
94
|
|
93
95
|
<h2 id="label-Using+EnvParser">Using EnvParser</h2>
|
94
96
|
|
95
|
-
<
|
97
|
+
<h3 id="label-Basic+Usage">Basic Usage</h3>
|
98
|
+
|
99
|
+
<h4 id="label-Parsing+ENV+Values">Parsing ENV Values</h4>
|
100
|
+
|
101
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Returns ENV['TIMEOUT_MS'] as an Integer,
|
102
|
+
</span><span class='comment'>## or 0 if ENV['TIMEOUT_MS'] is unset or nil.
|
103
|
+
</span>
|
104
|
+
<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>
|
96
105
|
|
97
|
-
<pre class="code ruby"><code class="ruby"><span class='comment'>## Returns ENV['TIMEOUT_MS'] as an Integer.
|
98
|
-
</span><span class='comment'>## Yields 0 if ENV['TIMEOUT_MS'] is unset or nil.
|
99
|
-
</span><span class='comment'>##
|
100
|
-
</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>
|
101
106
|
|
102
107
|
<span class='comment'>## LESS TYPING, PLZ! :(
|
103
108
|
</span><span class='comment'>## If you pass in a Symbol instead of a String, EnvParser
|
104
109
|
</span><span class='comment'>## will use the value behind the matching String key in ENV.
|
105
110
|
</span><span class='comment'>## (i.e. passing in ENV['X'] is equivalent to passing in :X)
|
106
|
-
</span
|
107
|
-
|
111
|
+
</span>
|
112
|
+
<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>
|
108
113
|
</code></pre>
|
109
|
-
<hr>
|
110
114
|
|
111
|
-
<p>
|
112
|
-
|
113
|
-
|
114
|
-
|
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>
|
155
|
-
<p>Note JSON is parsed using <em>quirks-mode</em> (meaning 'true',
|
156
|
-
'25', and 'null' are all considered valid, parseable JSON).</p>
|
115
|
+
<p>For a full list of all “as” types available out-of-the-box, <a
|
116
|
+
href="http://nestor-custodio.github.io/env_parser/EnvParserTypes.html">see
|
117
|
+
the documentation for modules listed under EnvParserTypes</a>.</p>
|
118
|
+
<hr>
|
157
119
|
|
158
120
|
<h4 id="label-Setting+Non-Trivial+Defaults">Setting Non-Trivial Defaults</h4>
|
159
121
|
|
@@ -161,99 +123,130 @@ values is user-expandable, but allowed values out-of-the-box are:</p>
|
|
161
123
|
</span><span class='comment'>## the return value is a sensible default for the given "as" type
|
162
124
|
</span><span class='comment'>## (0 or 0.0 for numbers, an empty tring, an empty Array or Hash, etc).
|
163
125
|
</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
126
|
</span>
|
168
|
-
<span class='
|
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-Validating+Parsed+ENV+Values">Validating 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
|
127
|
+
<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
|
128
|
+
</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
|
184
129
|
</span>
|
185
130
|
|
186
|
-
<span class='comment'>##
|
187
|
-
</span
|
188
|
-
|
189
|
-
|
190
|
-
<
|
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_parse'><span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span></span><span class='lparen'>(</span><span class='symbol'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_value'>value</span><span class='op'>|</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
|
192
|
-
<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='lparen'>(</span><span class='symbol'>:CONNECTION_RETRIES</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='op'>&</span><span class='symbol'>:nonzero?</span><span class='rparen'>)</span>
|
193
|
-
</code></pre>
|
131
|
+
<span class='comment'>## Note that "if_unset" values are used as-is, with no type conversion.
|
132
|
+
</span>
|
133
|
+
<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'>Careful!</span><span class='tstring_end'>'</span></span> <span class='comment'>## => 'Careful!'
|
134
|
+
</span></code></pre>
|
135
|
+
<hr>
|
194
136
|
|
195
137
|
<h4 id="label-Setting+Constants+From+ENV+Values">Setting Constants From ENV Values</h4>
|
196
138
|
|
197
139
|
<pre class="code ruby"><code class="ruby"><span class='comment'>## Global constants...
|
198
|
-
</span><span class='comment'>##
|
199
|
-
</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.)
|
200
|
-
</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>
|
201
|
-
<span class='const'>API_KEY</span> <span class='comment'>## => 'unbreakable p4$$w0rd' (registered within the Kernel module, so it's available everywhere)
|
202
140
|
</span>
|
203
|
-
<span class='comment'>##
|
204
|
-
</span
|
205
|
-
|
206
|
-
|
207
|
-
|
208
|
-
|
141
|
+
<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'
|
142
|
+
</span>
|
143
|
+
<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>
|
144
|
+
<span class='const'>API_KEY</span> <span class='comment'>## => 'unbreakable p4$$w0rd' (registered within the Kernel module, so it's available everywhere)
|
145
|
+
</span>
|
146
|
+
|
147
|
+
<span class='comment'>## ... and class/module-level constants!
|
148
|
+
</span>
|
149
|
+
<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'
|
150
|
+
</span>
|
151
|
+
<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>
|
152
|
+
<span class='const'>URI</span><span class='op'>::</span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## => 'https://youtu.be/L_jWHffIx5E'
|
153
|
+
</span>
|
154
|
+
<span class='const'>ULTIMATE_LINK</span> <span class='comment'>## => raises NameError (the un-namespaced constant is only in scope within the URI module)
|
209
155
|
</span>
|
210
156
|
|
157
|
+
|
158
|
+
|
211
159
|
<span class='comment'>## You can also set multiple constants in one call, which is considerably cleaner to read:
|
212
|
-
</span
|
213
|
-
|
160
|
+
</span>
|
161
|
+
<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>
|
214
162
|
<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>
|
215
163
|
<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>
|
216
164
|
|
165
|
+
|
217
166
|
<span class='comment'>## ... is equivalent to ...
|
218
|
-
</span
|
219
|
-
|
167
|
+
</span>
|
168
|
+
<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>
|
220
169
|
<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>
|
221
170
|
<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>
|
222
171
|
<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>
|
223
172
|
<span class='rparen'>)</span>
|
224
173
|
</code></pre>
|
174
|
+
<hr>
|
225
175
|
|
226
176
|
<h4 id="label-Binding+EnvParser+Proxies+Onto+ENV">Binding EnvParser Proxies Onto ENV</h4>
|
227
177
|
|
228
|
-
<pre class="code ruby"><code class="ruby"><span class='comment'>##
|
229
|
-
</span><span class='comment'>## This is done
|
230
|
-
</span><span class='comment'>##
|
231
|
-
</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_add_env_bindings'><span class='object_link'><a href="EnvParser.html#add_env_bindings-class_method" title="EnvParser.add_env_bindings (method)">add_env_bindings</a></span></span> <span class='comment'>## Sets up the proxy methods.
|
178
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## You can bind proxy "parse" and "register" methods onto ENV.
|
179
|
+
</span><span class='comment'>## This is done without polluting the method space for other objects.
|
232
180
|
</span>
|
233
|
-
<span class='
|
234
|
-
</span
|
235
|
-
|
236
|
-
|
237
|
-
</span><span class='
|
238
|
-
</span
|
181
|
+
<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_add_env_bindings'><span class='object_link'><a href="EnvParser.html#add_env_bindings-class_method" title="EnvParser.add_env_bindings (method)">add_env_bindings</a></span></span> <span class='comment'>## Sets up the proxy methods.
|
182
|
+
</span>
|
183
|
+
|
184
|
+
<span class='comment'>## Now you can call "parse" and "register" on ENV itself,
|
185
|
+
</span><span class='comment'>## which is more legible and feels more straight-forward.
|
186
|
+
</span>
|
187
|
+
<span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='comment'>## => '3.1415926'
|
188
|
+
</span>
|
189
|
+
<span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_parse'>parse</span> <span class='symbol'>:SHORT_PI</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:float</span> <span class='comment'>## => 3.1415926
|
190
|
+
</span><span class='const'>ENV</span><span class='period'>.</span><span class='id identifier rubyid_register'>register</span> <span class='symbol'>:SHORT_PI</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:float</span> <span class='comment'>## Your constant is set, my man!
|
191
|
+
</span>
|
192
|
+
|
193
|
+
<span class='comment'>## Note that ENV's proxy "parse" method will *always* interpret the
|
194
|
+
</span><span class='comment'>## value given as an ENV key (converting to a String, if necessary).
|
195
|
+
</span><span class='comment'>## This is different from the non-proxy "parse" method, which will use
|
196
|
+
</span><span class='comment'>## String values as-is and only looks up ENV values when given a Symbol.
|
239
197
|
</span></code></pre>
|
240
198
|
|
241
|
-
<
|
199
|
+
<h3 id="label-Advanced+Usage">Advanced Usage</h3>
|
200
|
+
|
201
|
+
<h4 id="label-Custom+Validation+Of+Parsed+Values">Custom Validation Of Parsed Values</h4>
|
202
|
+
|
203
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## Sometimes setting the type alone is a bit too open-ended.
|
204
|
+
</span><span class='comment'>## The "from_set" option lets you restrict the set of allowed values.
|
205
|
+
</span>
|
206
|
+
<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>
|
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_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>
|
208
|
+
|
209
|
+
|
210
|
+
<span class='comment'>## And if the value is not allowed...
|
211
|
+
</span>
|
212
|
+
<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
|
213
|
+
</span>
|
214
|
+
|
242
215
|
|
243
|
-
|
244
|
-
|
245
|
-
</span
|
246
|
-
|
216
|
+
|
217
|
+
<span class='comment'>## The "validated_by" option allows for more complex validation.
|
218
|
+
</span>
|
219
|
+
<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'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='comma'>,</span> <span class='label'>validated_by:</span> <span class='tlambda'>-></span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span> <span class='tlambeg'>{</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
|
220
|
+
|
221
|
+
|
222
|
+
<span class='comment'>## ... but a block will also do the trick!
|
223
|
+
</span>
|
224
|
+
<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='lparen'>(</span><span class='symbol'>:MUST_BE_LOWERCASE</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:string</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_value'>value</span><span class='op'>|</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>==</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_downcase'>downcase</span> <span class='rbrace'>}</span>
|
225
|
+
<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='lparen'>(</span><span class='symbol'>:CONNECTION_RETRIES</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:integer</span><span class='comma'>,</span> <span class='op'>&</span><span class='symbol'>:nonzero?</span><span class='rparen'>)</span>
|
226
|
+
</code></pre>
|
227
|
+
<hr>
|
228
|
+
|
229
|
+
<h4 id="label-Defining+Your+Own+EnvParser+-22as-22+Types">Defining Your Own EnvParser “as” Types</h4>
|
230
|
+
|
231
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'>## If you use a particular validation many times,
|
232
|
+
</span><span class='comment'>## or are often manipulating values in the same way
|
233
|
+
</span><span class='comment'>## after EnvParser has done its thing, you may want
|
234
|
+
</span><span class='comment'>## to register a new type altogether.
|
235
|
+
</span>
|
236
|
+
<span class='id identifier rubyid_a'>a</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'>:A</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:int</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>nil</span>
|
247
237
|
<span class='id identifier rubyid_raise'>raise</span> <span class='kw'>unless</span> <span class='id identifier rubyid_passes_all_my_checks?'>passes_all_my_checks?</span><span class='lparen'>(</span><span class='id identifier rubyid_a'>a</span><span class='rparen'>)</span>
|
248
238
|
|
249
239
|
<span class='id identifier rubyid_b'>b</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'>:B</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:int</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>nil</span>
|
250
240
|
<span class='id identifier rubyid_raise'>raise</span> <span class='kw'>unless</span> <span class='id identifier rubyid_passes_all_my_checks?'>passes_all_my_checks?</span><span class='lparen'>(</span><span class='id identifier rubyid_b'>b</span><span class='rparen'>)</span>
|
251
241
|
|
242
|
+
|
252
243
|
<span class='comment'>## ... is perhaps best handled by defining a new type:
|
253
|
-
</span
|
254
|
-
|
244
|
+
</span>
|
245
|
+
<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_define_type'><span class='object_link'><a href="EnvParser.html#define_type-class_method" title="EnvParser.define_type (method)">define_type</a></span></span><span class='lparen'>(</span><span class='symbol'>:my_special_type_of_number</span><span class='comma'>,</span> <span class='label'>if_unset:</span> <span class='kw'>nil</span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_value'>value</span><span class='op'>|</span>
|
255
246
|
<span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_to_i'>to_i</span>
|
256
|
-
<span class='
|
247
|
+
<span class='kw'>unless</span> <span class='id identifier rubyid_passes_all_my_checks?'>passes_all_my_checks?</span><span class='lparen'>(</span><span class='id identifier rubyid_value'>value</span><span class='rparen'>)</span>
|
248
|
+
<span class='id identifier rubyid_raise'>raise</span><span class='lparen'>(</span><span class='const'><span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="EnvParser/ValueNotConvertibleError.html" title="EnvParser::ValueNotConvertibleError (class)">ValueNotConvertibleError</a></span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>cannot parse as a "special type number"</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
249
|
+
<span class='kw'>end</span>
|
257
250
|
|
258
251
|
<span class='id identifier rubyid_value'>value</span>
|
259
252
|
<span class='kw'>end</span>
|
@@ -261,14 +254,17 @@ values is user-expandable, but allowed values out-of-the-box are:</p>
|
|
261
254
|
<span class='id identifier rubyid_a'>a</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'>:A</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:my_special_type_of_number</span>
|
262
255
|
<span class='id identifier rubyid_b'>b</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'>:B</span><span class='comma'>,</span> <span class='label'>as:</span> <span class='symbol'>:my_special_type_of_number</span>
|
263
256
|
|
264
|
-
|
265
|
-
|
266
|
-
</span><span class='comment'>##
|
257
|
+
|
258
|
+
<span class='comment'>## Defining a new type makes your code both more maintainable
|
259
|
+
</span><span class='comment'>## (all the logic for your special type is only defined once)
|
260
|
+
</span><span class='comment'>## and more readable (your "parse" calls aren't littered with
|
261
|
+
</span><span class='comment'>## type-checking cruft).
|
267
262
|
</span></code></pre>
|
268
263
|
<hr>
|
269
264
|
|
270
|
-
<p><a
|
271
|
-
|
265
|
+
<p><a
|
266
|
+
href="http://nestor-custodio.github.io/env_parser/EnvParser.html">Consult
|
267
|
+
the repo docs for the full EnvParser documentation.</a></p>
|
272
268
|
|
273
269
|
<h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
|
274
270
|
|
@@ -295,13 +291,6 @@ href="https://github.com/bbatsov/rubocop">Rubocop</a> and documentation is
|
|
295
291
|
built using <a href="https://yardoc.org/">Yard</a>. Neither is included in
|
296
292
|
the Gemspec; you'll need to install these locally to take advantage.</p>
|
297
293
|
|
298
|
-
<p>To install this gem onto your local machine, run <code>bundle exec rake
|
299
|
-
install</code>. To release a new version, update the version number in
|
300
|
-
<code>version.rb</code>, and then run <code>bundle exec rake
|
301
|
-
release</code>, which will create a git tag for the version, push git
|
302
|
-
commits and tags, and push the <code>.gem</code> file to <a
|
303
|
-
href="https://rubygems.org">rubygems.org</a>.</p>
|
304
|
-
|
305
294
|
<h2 id="label-License">License</h2>
|
306
295
|
|
307
296
|
<p>The gem is available as open source under the terms of the <a
|
@@ -309,7 +298,7 @@ href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
|
|
309
298
|
</div></div>
|
310
299
|
|
311
300
|
<div id="footer">
|
312
|
-
Generated on
|
301
|
+
Generated on Mon Dec 25 19:13:02 2017 by
|
313
302
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
314
303
|
0.9.11 (ruby-2.4.2).
|
315
304
|
</div>
|