env_parser 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f97bc0fe59df6a385baed458ea66fba04b2e79ac
-  data.tar.gz: 76f851cd5748a48f37e6de45c5cbcd30c6830838
+  metadata.gz: c332d39f13b5bc1bb69de8ea62bf563201cf9424
+  data.tar.gz: 3f1318fa50244fedf66831472c70482acbfbe8a9
 SHA512:
-  metadata.gz: 5730a3a7cc72e96ac94117b554262e59532c3c1f4486e3c1f526f5088ffe1ce5fb32289377ba54541669e428c9739cd64aafb33f1960e1d44de408832ed06e09
-  data.tar.gz: 8bae60dfa56d806266331d755a96d8f98c095990671d84312564ac1af5e73935d5a5bda83257255061549ca24e9c840a9ab395281d641367bff8c1d4c617947b
+  metadata.gz: ded5ae799d4457095e940a2737e95fcc58177fbc574deadc02ddaaee5c52b32a8edfbaf3be2984aef994507f73a4abf4721ef32930e4178ef0fe0c9427ee9598
+  data.tar.gz: 8e2330caa387e8425e74453b73a0b7f45251ac60de85adba8f7fa39f58f2080fab9af51c900f30656b35dc937d77e5b68d8ca6f2086a42ba75a977b28f04aa16

data/.rubocop.yml

@@ -1,78 +1,69 @@
 AllCops:
   TargetRubyVersion: 2.4
   Include:
+  - "**/*.rb"
   - "**/*.rake"
   - "**/Gemfile"
-  - "**/Rakefile"
-  - "**/Capfile"
-  - "**/Berksfile"
-  - "**/Cheffile"
   Exclude:
-  - "vendor/**/*"
-  - "db/**/*"
+  - ".git/**/*"
   - "tmp/**/*"
   - "true/**/*"
-Metrics/ClassLength:
-  Description: Avoid classes longer than 100 lines of code.
+  - "vendor/**/*"
+
+
+Layout/EmptyLineAfterGuardClause:
+  # Add empty line after guard clause.
   Enabled: false
-  CountComments: false
-  Max: 100
-Metrics/LineLength:
-  Description: Limit lines to 100 characters.
+
+
+Metrics/AbcSize:
+  # A calculated magnitude based on number of assignments, branches, and conditions.
   Enabled: false
-  Max: 100
+
 Metrics/BlockLength:
+  # Avoid long blocks with many lines.
   Exclude:
     - 'spec/**/*.rb'
-Metrics/MethodLength:
-  Description: Avoid methods longer than 10 lines of code.
-  StyleGuide: https://github.com/bbatsov/ruby-style-guide#short-methods
-  Enabled: false
-  CountComments: false
-  Max: 10
-Metrics/AbcSize:
-  Description: A calculated magnitude based on number of assignments, branches, and conditions.
-  Enabled: false
-  Max: 15
+
 Metrics/CyclomaticComplexity:
-  Description: A complexity metric that is strongly correlated to the number of test cases needed to validate a method.
-  Enabled: false
-  Max: 6
-Lint/Debugger:
-  Description: Warn in debugger entries
-  Enabled: false
-Lint/RescueWithoutErrorClass:
-  Description: Avoid rescuing without specifying an error class.
-  Enabled: false
-Style/SymbolArray:
-  Description: Use %i or %I for arrays of symbols.
-  Enabled: false
-Style/RegexpLiteral:
-  Description: Enforces using / or %r around regular expressions.
-  EnforcedStyle: percent_r
+  # A complexity metric that is strongly correlated to the number of test cases needed to validate a method.
+  Max: 10
+
+Metrics/LineLength:
+  # Limit lines to 100 characters.
+  Max: 100
+  Exclude:
+    - 'spec/**/*.rb'
+
+Metrics/MethodLength:
+  # Avoid methods longer than 25 lines of code.
+  Max: 25
+
+
 Style/AsciiComments:
-  # Disabling this so we can use non-breaking spaces (' ') in documentation comments, preventing browsers from collapsing multiple spaces in code blocks.
-  Description: This cop checks for non-ascii (non-English) characters in comments.
-  Enabled: false
-Style/NumericLiterals:
-  Description: This cop checks for big numeric literals without _ between groups of digits in them.
-  Enabled: false
-Style/Documentation:
-  Description: Document classes and non-namespace modules.
+  # This cop checks for non-ascii (non-English) characters in comments.
+  #
+  # NLC: Disabling this so we can use non-breaking spaces (' ') in documentation comments, preventing browsers from collapsing
+  #      multiple spaces in code blocks.
   Enabled: false
+
+Style/BlockDelimiters:
+  # Check for uses of braces or do/end around single line or multi-line blocks.
+  Exclude:
+    - 'spec/**/*.rb'
+
 Style/ClassAndModuleChildren:
-  Description: Use nested modules/class definitions instead of compact style.
+  # Use nested modules/class definitions instead of compact style.
   Enabled: false
+
 Style/FrozenStringLiteralComment:
+  # Add the frozen_string_literal comment to the top of files to help transition to frozen string literals by default.
   Enabled: false
-Style/EmptyMethod:
+
+Style/NumericLiterals:
+  # his cop checks for big numeric literals without _ between groups of digits in them.
   Enabled: false
-Style/StderrPuts:
-  Enabled: true
-  Exclude:
-    - 'bin/**/*'
-Style/BlockDelimiters:
-  Description: Check for uses of braces or do/end around single line or multi-line blocks.
-  Enabled: true
-  Exclude:
-    - 'spec/**/*.rb'
+
+Style/RegexpLiteral:
+  # Enforces using / or %r around regular expressions.
+  EnforcedStyle: percent_r

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    env_parser (1.2.0)
+    env_parser (1.3.0)
       activesupport (>= 5.0.0)
       chronic
       chronic_duration
@@ -14,6 +14,7 @@ GEM
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
+    ast (2.4.0)
     chronic (0.10.2)
     chronic_duration (0.10.6)
       numerizer (~> 0.1.1)
@@ -21,8 +22,13 @@ GEM
     diff-lcs (1.3)
     i18n (1.7.0)
       concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.3)
     minitest (5.12.2)
     numerizer (0.1.1)
+    parallel (1.18.0)
+    parser (2.6.5.0)
+      ast (~> 2.4.0)
+    rainbow (3.0.0)
     rake (10.5.0)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
@@ -39,9 +45,19 @@ GEM
     rspec-support (3.7.0)
     rspec_junit_formatter (0.3.0)
       rspec-core (>= 2, < 4, != 2.12.0)
+    rubocop (0.75.1)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.6)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    ruby-progressbar (1.10.1)
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
+    unicode-display_width (1.6.0)
+    yard (0.9.20)
 
 PLATFORMS
   ruby
@@ -52,6 +68,8 @@ DEPENDENCIES
   rake (~> 10.0)
   rspec (~> 3.0)
   rspec_junit_formatter
+  rubocop
+  yard
 
 BUNDLED WITH
    1.16.0

data/README.md

@@ -1,227 +1,316 @@
-# EnvParser  [![Gem Version](https://badge.fury.io/rb/env_parser.svg)](https://badge.fury.io/rb/env_parser)
+[![Gem Version](https://img.shields.io/github/v/release/nestor-custodio/env_parser?color=green&label=gem%20version)](https://rubygems.org/gems/env_parser)
+[![MIT License](https://img.shields.io/github/license/nestor-custodio/env_parser)](https://github.com/nestor-custodio/env_parser/blob/master/LICENSE.txt)
+
+
+# EnvParser
 
 If your code uses environment variables, you know that `ENV` will always surface these as strings. Interpreting these strings as the value you *actually* want to see/use takes some work, however: for numbers you need to cast with `to_i` or `to_f` ... for booleans you need to check for a specific value (`ENV['SOME_VAR'] == 'true'`) ... maybe you want to set non-trivial defaults (something other than `0` or `''`)? ... maybe you only want to allow values from a limited set? ...
 
-Things can get out of control pretty fast, especially as the number of environment variables in play grows. Tools like [dotenv](https://github.com/bkeepers/dotenv) help to make sure you're loading the correct **set** of variables, but [EnvParser](https://github.com/nestor-custodio/env_parser) makes ***the values themselves*** usable with a minimum of effort.
+Things can get out of control pretty fast, especially as the number of environment variables in play grows. Tools like [dotenv](https://github.com/bkeepers/dotenv) help to make sure you're loading the correct **set** of variables, but [EnvParser](https://github.com/nestor-custodio/env_parser) makes **the values themselves** usable with a minimum of effort.
+
+[Full documentation is available here](http://nestor-custodio.github.io/env_parser/EnvParser.html), but do read below for a crash course on availble featues!
 
 
 ## Installation
 
-Add this line to your application's Gemfile:
+- If your project uses [Bundler](https://github.com/bundler/bundler):
+  - Add one of the following to your application's Gemfile:
+    ```ruby
+    ## For on-demand usage ...
+    ##
+    gem 'env_parser'
 
-```ruby
-gem 'env_parser'
-```
+    ## To automatically register ENV
+    ## constants per ".env_parser.yml" ...
+    ##
+    gem 'env_parser', require: 'env_parser/autoregister'
+    ```
+  - And then run a:
+    ```shell
+    $ bundle install
+    ```
 
-And then execute:
+- Or, you can keep things simple with a manual install:
+  ```shell
+  $ gem install env_parser
+  ```
 
-    $ bundle
 
-Or install it yourself as:
+## Syntax Cheat Sheet
 
-    $ gem install env_parser
+```ruby
+## Returns an ENV value parsed "as" a specific type:
+##
+EnvParser.parse env_key_as_a_symbol
+                as: …                          ## ➜ required
+                if_unset: …                    ## ➜ optional; default value
+                from_set: …                    ## ➜ optional; an Array or Range
+                validated_by: ->(value) { … }  ## ➜ optional; may also be given as a block
+
+## Parse an ENV value and register it as a constant:
+##
+EnvParser.register env_key_as_a_symbol
+                   as: …                          ## ➜ required
+                   within: …                      ## ➜ optional; Class or Module
+                   if_unset: …                    ## ➜ optional; default value
+                   from_set: …                    ## ➜ optional; an Array or Range
+                   validated_by: ->(value) { … }  ## ➜ optional; may also be given as a block
+
+## Registers all ENV variables as spec'ed in ".env_parser.yml":
+##
+EnvParser.autoregister  ## Note this is automatically called if your
+                        ## Gemfile included the "env_parser" gem with
+                        ## the "require: 'env_parser/autoregister'" option.
+
+## Lets you call "parse" and "register" on ENV itself:
+##
+EnvParser.add_env_bindings  ## ENV.parse will now be a proxy for EnvParser.parse
+                            ## and ENV.register will now be a proxy for EnvParser.register
+```
 
 
-## Using EnvParser
+## Extended How-To-Use
 
-### Basic Usage
+#### Basic Usage
 
-#### Parsing ENV Values
+- **Parsing `ENV` Values**
 
-```ruby
-## Returns ENV['TIMEOUT_MS'] as an Integer,
-## or 0 if ENV['TIMEOUT_MS'] is unset or nil.
+  At its core, EnvParser is a straight-forward parser for string values (since that's all `ENV` ever gives you), allowing you to read a given string **_as_** a variety of types.
 
-timeout_ms = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
+  ```ruby
+  ## Returns ENV['TIMEOUT_MS'] as an Integer,
+  ## or a sensible default (0) if ENV['TIMEOUT_MS'] is unset.
+  ##
+  timeout_ms = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
+  ```
 
+  You can check the full documentation for [a list of all **_as_** types available right out of the box](http://nestor-custodio.github.io/env_parser/EnvParser/Types.html).
 
-## LESS TYPING, PLZ!  :(
-## If you pass in a Symbol instead of a String, EnvParser
-## will use the value behind the matching String key in ENV.
-## (i.e. passing in ENV['X'] is equivalent to passing in :X)
+- **How About Less Typing?**
 
-timeout_ms = EnvParser.parse :TIMEOUT_MS, as: :integer
-```
+  EnvParser is all about ~~simplification~~ ~~less typing~~ *laziness*. If you pass in a symbol instead of a string, EnvParser will look to `ENV` and use the value from the corresponding (string) key.
 
-For a full list of all "as" types available out-of-the-box, [see the documentation for modules listed under EnvParserTypes](http://nestor-custodio.github.io/env_parser/EnvParserTypes.html).
+  ```ruby
+  ## YAY, LESS TYPING!  😃
+  ## These two are the same:
+  ##
+  more_typing = EnvParser.parse ENV['TIMEOUT_MS'], as: :integer
+  less_typing = EnvParser.parse :TIMEOUT_MS, as: :integer
+  ```
 
----
+- **Registering Constants From `ENV` Values**
 
-#### Setting Non-Trivial Defaults
+  The `EnvParser.register` method lets you "promote" `ENV` variables into their own constants, already parsed into the correct type.
 
-```ruby
-## If the ENV variable you want is unset (nil) or blank (''),
-## the return value is a sensible default for the given "as" type
-## (0 or 0.0 for numbers, an empty tring, an empty Array or Hash, etc).
-## Sometimes you want a non-trivial default, however.
+  ```ruby
+  ENV['API_KEY']  ## => 'unbreakable p4$$w0rd'
 
-EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer  ## => 0
-EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer, if_unset: 250  ## => 250
+  EnvParser.register :API_KEY, as: :string
+  API_KEY  ## => 'unbreakable p4$$w0rd'
+  ```
 
+  By default, `EnvParser.register` will create the requested constant within the Kernel module (making it available everywhere), but you can specify any class or module you like.
 
-## Note that "if_unset" values are used as-is, with no type conversion.
+  ```ruby
+  ENV['BEST_VIDEO']  ## => 'https://youtu.be/L_jWHffIx5E'
 
-EnvParser.parse :MISSING_ENV_VARIABLE, as: :integer, if_unset: 'Careful!'  ## => 'Careful!'
-```
+  EnvParser.register :BEST_VIDEO, as: :string, within: URI
+  URI::BEST_VIDEO  ## => 'https://youtu.be/L_jWHffIx5E'
+  BEST_VIDEO  ## => raises NameError
+  ```
 
----
+  You can also register multiple constants with a single call, which is a bit cleaner.
 
-#### Setting Constants From ENV Values
+  ```ruby
+  EnvParser.register :USERNAME, as: :string
+  EnvParser.register :PASSWORD, as: :string
+  EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }
 
-```ruby
-## Global constants...
+  ## ... is equivalent to ... ##
 
-ENV['API_KEY']  ## => 'unbreakable p4$$w0rd'
+  EnvParser.register USERNAME: { as: :string                           },
+                     PASSWORD: { as: :string                           },
+                     MOCK_API: { as: :boolean, within: MyClassOrModule }
+  ```
 
-EnvParser.register :API_KEY, as: :string
-API_KEY  ## => 'unbreakable p4$$w0rd' (registered within the Kernel module, so it's available everywhere)
+- **Okay, But... How About Even Less Typing?**
 
+  Calling `EnvParser.add_env_bindings` binds proxy `parse` and `register` methods onto `ENV`. With these bindings in place, you can call `parse` or `register` on `ENV` itself, which is more legible and feels more straight-forward.
 
-## ... and class/module-level constants!
+  ```ruby
+  ENV['SHORT_PI']  ## => '3.1415926'
+  ENV['BETTER_PI']  ## => '["flaky crust", "strawberry filling"]'
 
-ENV['ULTIMATE_LINK']  ## => 'https://youtu.be/L_jWHffIx5E'
+  ## Bind the proxy methods.
+  ##
+  EnvParser.add_env_bindings
 
-EnvParser.register :ULTIMATE_LINK, as: :string, within: URI
-URI::ULTIMATE_LINK  ## => 'https://youtu.be/L_jWHffIx5E'
+  ENV.parse :SHORT_PI, as: :float  ## => 3.1415926
+  ENV.register :BETTER_PI, as: :array  ## Your constant is set!
+  ```
 
-ULTIMATE_LINK  ## => raises NameError (the un-namespaced constant is only in scope within the URI module)
+  Note that the proxy `ENV.parse` method will (naturally) *always* interpret the value given as an `ENV` key (converting it to a string, if necessary), which is slightly different from the original `EnvParser.parse` method.
 
+  ```ruby
+  ENV['SHORT_PI']  ## => '3.1415926'
 
+  EnvParser.parse 'SHORT_PI', as: :float  ## => 'SHORT_PI' as a float: 0.0
+  EnvParser.parse :SHORT_PI , as: :float  ## => ENV['SHORT_PI'] as a float: 3.1415926
 
+  ## Bind the proxy methods.
+  ##
+  EnvParser.add_env_bindings
 
-## You can also set multiple constants in one call, which is considerably cleaner to read:
+  ENV.parse 'SHORT_PI', as: :float  ## => ENV['SHORT_PI'] as a float: 3.1415926
+  ENV.parse :SHORT_PI , as: :float  ## => ENV['SHORT_PI'] as a float: 3.1415926
+  ```
 
-EnvParser.register :A, as: :string
-EnvParser.register :B, as: :integer, if_unset: 25
-EnvParser.register :C, as: :boolean, if_unset: true
+  Note also that the `ENV.parse` and `ENV.register` binding is done safely and without polluting the method space for other objects.
 
+  **All additional examples below will assume that `ENV` bindings are already in place, for brevity's sake.**
 
-## ... is equivalent to ...
 
-EnvParser.register(
-  A: { as: :string },
-  B: { as: :integer, if_unset: 25 },
-  C: { as: :boolean, if_unset: true }
-)
-```
+#### Ensuring Usable Values
 
----
+- **Sensible Defaults**
 
-#### Binding EnvParser Proxies Onto ENV
+  If the `ENV` variable you want is unset (`nil`) or blank (`''`), the return value is a sensible default for the given **_as_** type: 0 or 0.0 for numbers, an empty string/array/hash, etc. Sometimes you want a non-trivial default, however. The **_if_unset_** option lets you specify a default that better meets your needs.
 
-```ruby
-## You can bind proxy "parse" and "register" methods onto ENV.
-## This is done without polluting the method space for other objects.
+  ```ruby
+  ENV.parse :MISSING_VAR, as: :integer  ## => 0
+  ENV.parse :MISSING_VAR, as: :integer, if_unset: 250  ## => 250
+  ```
 
-EnvParser.add_env_bindings  ## Sets up the proxy methods.
+  Note these default values are used as-is with no type conversion, so exercise caution.
 
+  ```ruby
+  ENV.parse :MISSING_VAR, as: :integer, if_unset: 'Careful!'  ## => 'Careful!' (NOT AN INTEGER)
+  ```
 
-## Now you can call "parse" and "register" on ENV itself,
-## which is more legible and feels more straight-forward.
+- **Selecting From A Set**
 
-ENV['SHORT_PI']  ## => '3.1415926'
+  Sometimes setting the **_as_** type is a bit too open-ended. The **_from_set_** option lets you restrict the domain of allowed values.
 
-ENV.parse :SHORT_PI, as: :float  ## => 3.1415926
-ENV.register :SHORT_PI, as: :float  ## Your constant is set, my man!
+  ```ruby
+  ENV.parse :API_TO_USE, as: :symbol, from_set: %i[internal external]
+  ENV.parse :NETWORK_PORT, as: :integer, from_set: (1..65535), if_unset: 80
 
+  ## And if the value is not in the allowed set ...
+  ##
+  ENV.parse :TWELVE, as: :integer, from_set: (1..5)  ## => raises EnvParser::ValueNotAllowedError
+  ```
 
-## Note that ENV's proxy "parse" method will *always* interpret the
-## value given as an ENV key (converting to a String, if necessary).
-## This is different from the non-proxy "parse" method, which will use
-## String values as-is and only looks up ENV values when given a Symbol.
-```
+- **Custom Validation Of Parsed Values**
 
+  You can write your own, more complex validations by passing in a **_validated_by_** lambda or an equivalent block. The lambda/block should take one value and return true if the given value passes the custom validation.
 
-### Advanced Usage
+  ```ruby
+  ## Via a "validated_by" lambda ...
+  ##
+  ENV.parse :MUST_BE_LOWERCASE, as: :string, validated_by: ->(value) { value == value.downcase }
 
-#### Custom Validation Of Parsed Values
+  ## ... or with a block!
+  ##
+  ENV.parse(:MUST_BE_LOWERCASE, as: :string) { |value| value == value.downcase }
+  ENV.parse(:CONNECTION_RETRIES, as: :integer, &:positive?)
+  ```
 
-```ruby
-## Sometimes setting the type alone is a bit too open-ended.
-## The "from_set" option lets you restrict the set of allowed values.
+- **Defining Your Own EnvParser "*as*" Types**
 
-EnvParser.parse :API_TO_USE, as: :symbol, from_set: %i[internal external]
-EnvParser.parse :SOME_CUSTOM_NETWORK_PORT, as: :integer, from_set: (1..65535), if_unset: 80
+  If you use a particular validation many times or are often manipulating values in the same way after EnvParser has done its thing, you may want to register a new type altogether. Defining a new type makes your code both more maintainable (all the logic for your special type is only defined once) and more readable (your `parse` calls aren't littered with type-checking cruft).
 
+  Something as repetitive as:
 
-## And if the value is not allowed...
+  ```ruby
+  a = ENV.parse :A, as: :int, if_unset: 6
+  raise unless passes_all_my_checks?(a)
 
-EnvParser.parse :NEGATIVE_NUMBER, as: :integer, from_set: (1..5)  ## => raises EnvParser::ValueNotAllowedError
+  b = ENV.parse :B, as: :int, if_unset: 6
+  raise unless passes_all_my_checks?(b)
+  ```
 
+  ... is perhaps best handled by defining a new type:
 
+  ```ruby
+  EnvParser.define_type(:my_special_type_of_number, if_unset: 6) do |value|
+    value = value.to_i
+    unless passes_all_my_checks?(value)
+      raise(EnvParser::ValueNotConvertibleError, 'cannot parse as a "special type number"')
+    end
 
+    value
+  end
 
-## The "validated_by" option allows for more complex validation.
+  a = ENV.parse :A, as: :my_special_type_of_number
+  b = ENV.parse :B, as: :my_special_type_of_number
+  ```
 
-EnvParser.parse :MUST_BE_LOWERCASE, as: :string, validated_by: ->(value) { value == value.downcase }
 
+#### Auto-Registering Constants
 
-## ... but a block will also do the trick!
+- **The `autoregister` Call**
 
-EnvParser.parse(:MUST_BE_LOWERCASE, as: :string) { |value| value == value.downcase }
-EnvParser.parse(:CONNECTION_RETRIES, as: :integer, &:positive?)
-```
+  Consolidating all of your `EnvParser.register` calls into a single place only makes sense. A single `EnvParser.autoregister` call take a filename to read and process as a series of constant registration requests. If no filename is given, the default `".env_parser.yml"` is assumed.
 
----
+  You'll normally want to call `EnvParser.autoregister` as early in your application as possible. For Rails applications (and other frameworks that call `require 'bundler/setup'`), requiring the EnvParser gem via ...
 
-#### Defining Your Own EnvParser "as" Types
+  ```ruby
+  gem 'env_parser', require: 'env_parser/autoregister'
+  ```
 
-```ruby
-## If you use a particular validation many times,
-## or are often manipulating values in the same way
-## after EnvParser has done its thing, you may want
-## to register a new type altogether.
+  ... will automatically make the autoregistration call for you as soon as the gem is loaded (which should be early enough for most uses). If this is *still* not early enough for your needs, you can always `require 'env_parser/autoregister'` yourself even before `bundler/setup` is invoked.
 
-a = EnvParser.parse :A, as: :int, if_unset: nil
-raise unless passes_all_my_checks?(a)
+- **The ".env_parser.yml" File**
 
-b = EnvParser.parse :B, as: :int, if_unset: nil
-raise unless passes_all_my_checks?(b)
+  If you recall, multiple constants can be registered via a single `EnvParser.register` call:
 
+  ```ruby
+  EnvParser.register :USERNAME, as: :string
+  EnvParser.register :PASSWORD, as: :string
+  EnvParser.register :MOCK_API, as: :boolean, within: MyClassOrModule }
 
-## ... is perhaps best handled by defining a new type:
+  ## ... is equivalent to ... ##
 
-EnvParser.define_type(:my_special_type_of_number, if_unset: nil) do |value|
-  value = value.to_i
-  unless passes_all_my_checks?(value)
-    raise(EnvParser::ValueNotConvertibleError, 'cannot parse as a "special type number"')
-  end
+  EnvParser.register USERNAME: { as: :string                           },
+                     PASSWORD: { as: :string                           },
+                     MOCK_API: { as: :boolean, within: MyClassOrModule }
+  ```
 
-  value
-end
+  The autoregistraton file is intended to read as a YAML version of what you'd pass to the single-call version of `EnvParser.register`: a single hash with keys for each of the constants you'd like to register, with each value being the set of options to parse that constant.
 
-a = EnvParser.parse :A, as: :my_special_type_of_number
-b = EnvParser.parse :B, as: :my_special_type_of_number
+  The equivalent autoregistration file for the above would be:
 
+  ```yaml
+  USERNAME:
+    as: :string
 
-## Defining a new type makes your code both more maintainable
-## (all the logic for your special type is only defined once)
-## and more readable (your "parse" calls aren't littered with
-## type-checking cruft).
-```
+  PASSWORD:
+    as: :string
 
----
+  MOCK_API:
+    as: :boolean
+    within: MyClassOrModule
+  ```
 
-[Consult the repo docs for the full EnvParser documentation.](http://nestor-custodio.github.io/env_parser/EnvParser.html)
+  Because no Ruby *statements* can be safely represented via YAML, the set of `EnvParser.register` options available via autoregistration is limited to **_as_**, **_within_**, **_if_unset_**, and **_from_set_**. As an additional restriction, **_from_set_** (if given) must be an array, as ranges cannot be represented in YAML.
 
 
 ## Feature Roadmap / Future Development
 
-Additional features/options coming in the future:
+Additional features coming in the future:
 
-- Allow for a ".env_parser" file where you can easily type-check and/or register (as constants) any ENV variables you like.
-- Continue to round out the "as" type selection as ideas come to mind, suggestions are made, and pull requests are submitted.
+- Continue to round out the **_as_** type selection as ideas come to mind, suggestions are made, and pull requests are submitted.
 
 
 ## Contribution / Development
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/nestor-custodio/env_parser.
+Bug reports and pull requests are welcome at: [https://github.com/nestor-custodio/env_parser](https://github.com/nestor-custodio/env_parser)
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-Linting is courtesy of [Rubocop](https://github.com/bbatsov/rubocop) and documentation is built using [Yard](https://yardoc.org/). Neither is included in the Gemspec; you'll need to install these locally to take advantage.
+Linting is courtesy of [Rubocop](https://docs.rubocop.org/) (`bundle exec rubocop`) and documentation is built using [Yard](https://yardoc.org/) (`bundle exec yard`). Please ensure you have a clean bill of health from Rubocop and that any new features and/or changes to behaviour are reflected in the documentation before submitting a pull request.
 
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+EnvParser is available as open source under the terms of the [MIT License](https://tldrlegal.com/license/mit-license).