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.
@@ -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> &lt; 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> &lt; StandardError<small class='search_info'>EnvParser</small></div></li><li id='object_EnvParser::TypeAlreadyDefined' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="EnvParser/TypeAlreadyDefined.html" title="EnvParser::TypeAlreadyDefined (class)">TypeAlreadyDefined</a></span> &lt; Error<small class='search_info'>EnvParser</small></div></li><li id='object_EnvParser::ValueNotAllowed' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="EnvParser/ValueNotAllowed.html" title="EnvParser::ValueNotAllowed (class)">ValueNotAllowed</a></span> &lt; Error<small class='search_info'>EnvParser</small></div></li></ul></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> &lt; 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> &lt; 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> &lt; 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> &lt; 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> &lt; 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> &lt; 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>
@@ -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>#to_i</code>/<code>#to_f</code>, for
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
- &#39;true&#39;</code>), etc. Maybe you want to set non-trivial defaults
69
- (something other than <code>0</code> or <code>&#39;&#39;</code>)? Maybe you
70
- only want to allow values from a limited set? …</p>
68
+ &#39;true&#39;</code>) maybe you want to set non-trivial defaults
69
+ (something other than <code>0</code> or <code>&#39;&#39;</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&#39;re loading the correct set of <em>variables</em>, but EnvParser
76
- makes <em>the values themselves</em> usable with a minimum of effort.</p>
75
+ you&#39;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
- <h4 id="label-Basic+Usage">Basic Usage</h4>
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[&#39;TIMEOUT_MS&#39;] as an Integer,
102
+ </span><span class='comment'>## or 0 if ENV[&#39;TIMEOUT_MS&#39;] 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'>&#39;</span><span class='tstring_content'>TIMEOUT_MS</span><span class='tstring_end'>&#39;</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[&#39;TIMEOUT_MS&#39;] as an Integer.
98
- </span><span class='comment'>## Yields 0 if ENV[&#39;TIMEOUT_MS&#39;] 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'>&#39;</span><span class='tstring_content'>TIMEOUT_MS</span><span class='tstring_end'>&#39;</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[&#39;X&#39;] is equivalent to passing in :X)
106
- </span><span class='comment'>##
107
- </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>
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>The named <code>:as</code> parameter is required. The list of allowed
112
- values is user-expandable, but allowed values out-of-the-box 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>&lt; depends on JSON given &gt;</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 &#39;true&#39;,
156
- &#39;25&#39;, and &#39;null&#39; 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 &quot;as&quot; 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'>## =&gt; 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'>## =&gt; 250
167
126
  </span>
168
- <span class='comment'>## Note that &quot;if_unset&quot; 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'>&#39;</span><span class='tstring_content'>Whoops!</span><span class='tstring_end'>&#39;</span></span> <span class='comment'>## =&gt; &#39;Whoops!&#39;
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 &quot;from_set&quot; 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'>## =&gt; 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'>## =&gt; 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'>## =&gt; 250
184
129
  </span>
185
130
 
186
- <span class='comment'>## The &quot;validated_by&quot; option allows for more complex validation.
187
- </span><span class='comment'>##
188
- </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'>: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'>-&gt;</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>
189
-
190
- <span class='comment'>## ... but a block will also do the trick!
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'>&amp;</span><span class='symbol'>:nonzero?</span><span class='rparen'>)</span>
193
- </code></pre>
131
+ <span class='comment'>## Note that &quot;if_unset&quot; 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'>&#39;</span><span class='tstring_content'>Careful!</span><span class='tstring_end'>&#39;</span></span> <span class='comment'>## =&gt; &#39;Careful!&#39;
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'>&#39;</span><span class='tstring_content'>API_KEY</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;unbreakable p4$$w0rd&#39; (Set elsewhere, like a &quot;.env&quot; 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'>## =&gt; &#39;unbreakable p4$$w0rd&#39; (registered within the Kernel module, so it&#39;s available everywhere)
202
140
  </span>
203
- <span class='comment'>## ... and class/module constants!
204
- </span><span class='comment'>##
205
- </span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>ULTIMATE_LINK</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39; (Set elsewhere, like a &quot;.env&quot; file.)
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'>: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>
207
- <span class='const'>URI</span><span class='op'>::</span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39; (You know you want to check it out!)
208
- </span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## =&gt; raises NameError (the un-namespaced constant is only in scope within the URI module)
141
+ <span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>API_KEY</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;unbreakable p4$$w0rd&#39;
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'>## =&gt; &#39;unbreakable p4$$w0rd&#39; (registered within the Kernel module, so it&#39;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'>&#39;</span><span class='tstring_content'>ULTIMATE_LINK</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39;
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'>## =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39;
153
+ </span>
154
+ <span class='const'>ULTIMATE_LINK</span> <span class='comment'>## =&gt; 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><span class='comment'>##
213
- </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>
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><span class='comment'>##
219
- </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>
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'>## To allow for even cleaner usage, you can bind proxy &quot;parse&quot; and &quot;register&quot; methods onto ENV.
229
- </span><span class='comment'>## This is done cleanly and without polluting the method space for any other objects.
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 &quot;parse&quot; and &quot;register&quot; 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='comment'>## Now you can call &quot;parse&quot; and &quot;register&quot; on ENV itself. Note that ENV&#39;s proxy &quot;parse&quot; method will
234
- </span><span class='comment'>## attempt to interpret any value given as an ENV key (converting to a String, if necessary).
235
- </span><span class='comment'>##
236
- </span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;3.1415926&#39;
237
- </span><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'>## =&gt; 3.1415926
238
- </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!
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 &quot;parse&quot; and &quot;register&quot; 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'>&#39;</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;3.1415926&#39;
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'>## =&gt; 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&#39;s proxy &quot;parse&quot; 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 &quot;parse&quot; 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
- <h4 id="label-Defining+your+own+types+for+use+with+EnvParser">Defining your own types for use with EnvParser</h4>
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 &quot;from_set&quot; 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'>## =&gt; raises EnvParser::ValueNotAllowed
213
+ </span>
214
+
242
215
 
243
- <pre class="code ruby"><code class="ruby"><span class='comment'>## If you use a particular validation many times, or are often manipulating values in the same way
244
- </span><span class='comment'>## after EnvParser has done its thing, you may want to register a new type altogether.
245
- </span><span class='comment'>##
246
- </span><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>
216
+
217
+ <span class='comment'>## The &quot;validated_by&quot; 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'>-&gt;</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'>&amp;</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><span class='comment'>##
254
- </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_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>
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='id identifier rubyid_raise'>raise</span><span class='lparen'>(</span><span class='const'>StandardError</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>this is not a &quot;special type&quot; number</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</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_value'>value</span><span class='rparen'>)</span>
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'>&#39;</span><span class='tstring_content'>cannot parse as a &quot;special type number&quot;</span><span class='tstring_end'>&#39;</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
- <span class='comment'>## Defining a new type makes your code both more maintainable (all the logic for your special type
265
- </span><span class='comment'>## is only defined once) and more readable (your &quot;parse&quot; calls aren&#39;t littered with type-checking
266
- </span><span class='comment'>## cruft).
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 &quot;parse&quot; calls aren&#39;t littered with
261
+ </span><span class='comment'>## type-checking cruft).
267
262
  </span></code></pre>
268
263
  <hr>
269
264
 
270
- <p><a href="http://nestor-custodio.github.io/env_parser">Consult the repo
271
- docs</a> for the full EnvParser documentation.</p>
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&#39;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 Sun Dec 24 19:33:35 2017 by
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>
@@ -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>#to_i</code>/<code>#to_f</code>, for
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
- &#39;true&#39;</code>), etc. Maybe you want to set non-trivial defaults
69
- (something other than <code>0</code> or <code>&#39;&#39;</code>)? Maybe you
70
- only want to allow values from a limited set? …</p>
68
+ &#39;true&#39;</code>) maybe you want to set non-trivial defaults
69
+ (something other than <code>0</code> or <code>&#39;&#39;</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&#39;re loading the correct set of <em>variables</em>, but EnvParser
76
- makes <em>the values themselves</em> usable with a minimum of effort.</p>
75
+ you&#39;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
- <h4 id="label-Basic+Usage">Basic Usage</h4>
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[&#39;TIMEOUT_MS&#39;] as an Integer,
102
+ </span><span class='comment'>## or 0 if ENV[&#39;TIMEOUT_MS&#39;] 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'>&#39;</span><span class='tstring_content'>TIMEOUT_MS</span><span class='tstring_end'>&#39;</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[&#39;TIMEOUT_MS&#39;] as an Integer.
98
- </span><span class='comment'>## Yields 0 if ENV[&#39;TIMEOUT_MS&#39;] 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'>&#39;</span><span class='tstring_content'>TIMEOUT_MS</span><span class='tstring_end'>&#39;</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[&#39;X&#39;] is equivalent to passing in :X)
106
- </span><span class='comment'>##
107
- </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>
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>The named <code>:as</code> parameter is required. The list of allowed
112
- values is user-expandable, but allowed values out-of-the-box 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>&lt; depends on JSON given &gt;</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 &#39;true&#39;,
156
- &#39;25&#39;, and &#39;null&#39; 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 &quot;as&quot; 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'>## =&gt; 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'>## =&gt; 250
167
126
  </span>
168
- <span class='comment'>## Note that &quot;if_unset&quot; 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'>&#39;</span><span class='tstring_content'>Whoops!</span><span class='tstring_end'>&#39;</span></span> <span class='comment'>## =&gt; &#39;Whoops!&#39;
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 &quot;from_set&quot; 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'>## =&gt; 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'>## =&gt; 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'>## =&gt; 250
184
129
  </span>
185
130
 
186
- <span class='comment'>## The &quot;validated_by&quot; option allows for more complex validation.
187
- </span><span class='comment'>##
188
- </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'>: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'>-&gt;</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>
189
-
190
- <span class='comment'>## ... but a block will also do the trick!
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'>&amp;</span><span class='symbol'>:nonzero?</span><span class='rparen'>)</span>
193
- </code></pre>
131
+ <span class='comment'>## Note that &quot;if_unset&quot; 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'>&#39;</span><span class='tstring_content'>Careful!</span><span class='tstring_end'>&#39;</span></span> <span class='comment'>## =&gt; &#39;Careful!&#39;
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'>&#39;</span><span class='tstring_content'>API_KEY</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;unbreakable p4$$w0rd&#39; (Set elsewhere, like a &quot;.env&quot; 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'>## =&gt; &#39;unbreakable p4$$w0rd&#39; (registered within the Kernel module, so it&#39;s available everywhere)
202
140
  </span>
203
- <span class='comment'>## ... and class/module constants!
204
- </span><span class='comment'>##
205
- </span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>ULTIMATE_LINK</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39; (Set elsewhere, like a &quot;.env&quot; file.)
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'>: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>
207
- <span class='const'>URI</span><span class='op'>::</span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39; (You know you want to check it out!)
208
- </span><span class='const'>ULTIMATE_LINK</span> <span class='comment'>## =&gt; raises NameError (the un-namespaced constant is only in scope within the URI module)
141
+ <span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>API_KEY</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;unbreakable p4$$w0rd&#39;
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'>## =&gt; &#39;unbreakable p4$$w0rd&#39; (registered within the Kernel module, so it&#39;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'>&#39;</span><span class='tstring_content'>ULTIMATE_LINK</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39;
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'>## =&gt; &#39;https://youtu.be/L_jWHffIx5E&#39;
153
+ </span>
154
+ <span class='const'>ULTIMATE_LINK</span> <span class='comment'>## =&gt; 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><span class='comment'>##
213
- </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>
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><span class='comment'>##
219
- </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>
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'>## To allow for even cleaner usage, you can bind proxy &quot;parse&quot; and &quot;register&quot; methods onto ENV.
229
- </span><span class='comment'>## This is done cleanly and without polluting the method space for any other objects.
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 &quot;parse&quot; and &quot;register&quot; 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='comment'>## Now you can call &quot;parse&quot; and &quot;register&quot; on ENV itself. Note that ENV&#39;s proxy &quot;parse&quot; method will
234
- </span><span class='comment'>## attempt to interpret any value given as an ENV key (converting to a String, if necessary).
235
- </span><span class='comment'>##
236
- </span><span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;3.1415926&#39;
237
- </span><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'>## =&gt; 3.1415926
238
- </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!
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 &quot;parse&quot; and &quot;register&quot; 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'>&#39;</span><span class='tstring_content'>SHORT_PI</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='comment'>## =&gt; &#39;3.1415926&#39;
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'>## =&gt; 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&#39;s proxy &quot;parse&quot; 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 &quot;parse&quot; 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
- <h4 id="label-Defining+your+own+types+for+use+with+EnvParser">Defining your own types for use with EnvParser</h4>
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 &quot;from_set&quot; 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'>## =&gt; raises EnvParser::ValueNotAllowed
213
+ </span>
214
+
242
215
 
243
- <pre class="code ruby"><code class="ruby"><span class='comment'>## If you use a particular validation many times, or are often manipulating values in the same way
244
- </span><span class='comment'>## after EnvParser has done its thing, you may want to register a new type altogether.
245
- </span><span class='comment'>##
246
- </span><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>
216
+
217
+ <span class='comment'>## The &quot;validated_by&quot; 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'>-&gt;</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'>&amp;</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><span class='comment'>##
254
- </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_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>
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='id identifier rubyid_raise'>raise</span><span class='lparen'>(</span><span class='const'>StandardError</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>this is not a &quot;special type&quot; number</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</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_value'>value</span><span class='rparen'>)</span>
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'>&#39;</span><span class='tstring_content'>cannot parse as a &quot;special type number&quot;</span><span class='tstring_end'>&#39;</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
- <span class='comment'>## Defining a new type makes your code both more maintainable (all the logic for your special type
265
- </span><span class='comment'>## is only defined once) and more readable (your &quot;parse&quot; calls aren&#39;t littered with type-checking
266
- </span><span class='comment'>## cruft).
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 &quot;parse&quot; calls aren&#39;t littered with
261
+ </span><span class='comment'>## type-checking cruft).
267
262
  </span></code></pre>
268
263
  <hr>
269
264
 
270
- <p><a href="http://nestor-custodio.github.io/env_parser">Consult the repo
271
- docs</a> for the full EnvParser documentation.</p>
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&#39;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 Sun Dec 24 19:33:34 2017 by
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>