env_parser 0.8.0 → 1.0.0

data/docs/top-level-namespace.html

@@ -82,6 +82,8 @@
 <p class="children">
   
     
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="EnvParserTypes.html" title="EnvParserTypes (module)">EnvParserTypes</a></span>
+    
   
     
       <strong class="classes">Classes:</strong> <span class='object_link'><a href="EnvParser.html" title="EnvParser (class)">EnvParser</a></span>
@@ -162,12 +164,12 @@
       <pre class="lines">
 
 
-315</pre>
+3</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/env_parser.rb', line 315</span>
+      <pre class="code"><span class="info file"># File 'lib/env_parser/types.rb', line 3</span>
 
-<span class='const'>Dir</span><span class='period'>.</span><span class='id identifier rubyid_glob'>glob</span><span class='lparen'>(</span><span class='const'>File</span><span class='period'>.</span><span class='id identifier rubyid_join'>join</span><span class='lparen'>(</span><span class='id identifier rubyid___dir__'>__dir__</span><span class='comma'>,</span> <span class='qwords_beg'>%w[</span><span class='tstring_content'>env_parser</span><span class='words_sep'> </span><span class='tstring_content'>types</span><span class='words_sep'> </span><span class='tstring_content'>*.rb</span><span class='words_sep'>]</span><span class='rparen'>)</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_each'>each</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_filename'>filename</span><span class='op'>|</span> <span class='id identifier rubyid_require_relative'>require_relative</span> <span class='id identifier rubyid_filename'>filename</span> <span class='rbrace'>}</span></pre>
+<span class='const'>Dir</span><span class='period'>.</span><span class='id identifier rubyid_glob'>glob</span><span class='lparen'>(</span><span class='const'>File</span><span class='period'>.</span><span class='id identifier rubyid_join'>join</span><span class='lparen'>(</span><span class='id identifier rubyid___dir__'>__dir__</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>types</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>*.rb</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_each'>each</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_filename'>filename</span><span class='op'>|</span> <span class='id identifier rubyid_require_relative'>require_relative</span> <span class='id identifier rubyid_filename'>filename</span> <span class='rbrace'>}</span></pre>
     </td>
   </tr>
 </table>
@@ -178,7 +180,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sun Dec 24 19:33:35 2017 by
+  Generated on Mon Dec 25 19:13:02 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.11 (ruby-2.4.2).
 </div>

data/lib/env_parser.rb

@@ -1,61 +1,47 @@
+require 'env_parser/errors'
 require 'env_parser/version'
 require 'active_support/all'
 
 ## The EnvParser class simplifies parsing of environment variables as different data types.
 ##
 class EnvParser
-  ## Base exception class for EnvParser.
-  ##
-  class Error < ::StandardError
-  end
-
-  ## Exception class used to indicate parsed values not allowed per a "from_set" option.
-  ##
-  class ValueNotAllowed < Error
-  end
-
-  ## Exception class used to indicate a type has already been defined.
-  ##
-  class TypeAlreadyDefined < Error
-  end
-
   class << self
-    ## Defines a new type for use as the "as" option on a subsequent `.parse` or `.register` call.
+    ## Defines a new type for use as the "as" option on a subsequent {.parse} or {.register} call.
     ##
     ## @param name [Symbol]
     ##   The name to assign to the type.
     ##
-    ## @option options aliases [Array<Symbol>]
+    ## @option options [Array<Symbol>] aliases
     ##   An array of additional names you'd like to see refer to this same type.
     ##
-    ## @option options if_unset
+    ## @option options if_unset (nil)
     ##   Specifies a "sensible default" to return for this type if the value being parsed (via
-    ##   `.parse` or `.register`) is either unset (`nil`) or blank (`''`). Note this may be
-    ##   overridden by the user via the `.parse`/`.register` "if_unset" option.
+    ##   {.parse} or {.register}) is either unset (`nil`) or blank (`''`). Note this may be
+    ##   overridden by the user via the {.parse}/{.register} "if_unset" option.
     ##
-    ## @yield
+    ## @yield [value]
     ##   A block to act as the parser for the this type. If no block is given, an ArgumentError is
     ##   raised.
     ##
-    ##   When the type defined is used via a `.parse`/`.register` call, this block is invoked with
+    ##   When the type defined is used via a {.parse}/{.register} call, this block is invoked with
     ##   the value to be parsed. Said value is guaranteed to be a non-empty String (the "if_unset"
     ##   check will have already run), but no other assurances as to content are given. The block
     ##   should return the final output of parsing the given String value as the type being defined.
     ##
     ##   If the value given cannot be sensibly parsed into the type defined, the block should raise
-    ##   an EnvParser::ValueNotAllowed exception.
+    ##   an {EnvParser::ValueNotConvertibleError}.
     ##
     ## @return [nil]
     ##   This generates no usable value.
     ##
-    ## @raise [ArgumentError, EnvParser::TypeAlreadyDefined]
+    ## @raise [ArgumentError, EnvParser::TypeAlreadyDefinedError]
     ##
     def define_type(name, options = {}, &parser)
       raise(ArgumentError, 'no parsing block given') unless block_given?
 
       given_types = (Array(name) + Array(options[:aliases])).map(&:to_s).map(&:to_sym)
       given_types.each do |type|
-        raise(TypeAlreadyDefined, "cannot redefine #{type.inspect}") if known_types.key?(type)
+        raise(TypeAlreadyDefinedError, "cannot redefine #{type.inspect}") if known_types.key?(type)
 
         known_types[type] = {
           parser: parser,
@@ -72,12 +58,13 @@ class EnvParser
     ##   The value to parse/interpret. If a String is given, the value will be used as-is. If a
     ##   Symbol is given, the ENV value for the matching string key will be used.
     ##
-    ## @option options as [Symbol]
+    ## @option options [Symbol] as
     ##   The expected return type. A best-effort attempt is made to convert the source String to the
     ##   requested type.
     ##
-    ##   If no "as" option is given (or the "as" value given has not been defined), an ArgumentError
-    ##   exception is raised.
+    ##   If no "as" option is given, an ArgumentError is raised. If the "as" option given is unknown
+    ##   (the given type has not been previously defined via {.define_type}), an
+    ##   {EnvParser::UnknownTypeError} is raised.
     ##
     ## @option options if_unset
     ##   Specifies the default value to return if the given "value" is either unset (`nil`) or blank
@@ -85,43 +72,45 @@ class EnvParser
     ##   change having been made.  If unspecified, the "default" value for `nil`/`''` input will
     ##   depend on the "as" type.
     ##
-    ## @option options from_set [Array, Range]
+    ## @option options [Array, Range] from_set
     ##   Gives a limited set of allowed values (after type conversion). If, after parsing, the final
-    ##   value is not included in the "from_set" list/range, an EnvParser::ValueNotAllowed exception
-    ##   is raised.
+    ##   value is not included in the "from_set" list/range, an {EnvParser::ValueNotAllowedError} is
+    ##   raised.
     ##
     ##   Note that if the "if_unset" option is given and the value to parse is `nil`/`''`, the
     ##   "if_unset" value will be returned, even if it is not part of the "from_set" list/range.
     ##
     ##   Also note that, due to the nature of the lookup, the "from_set" option is only available
     ##   for scalar values (i.e. not arrays, hashes, or other enumerables). An attempt to use the
-    ##   "from_set" option with a non-scalar value will raise an ArgumentError exception.
+    ##   "from_set" option with a non-scalar value will raise an ArgumentError.
     ##
-    ## @option options validated_by [Proc]
-    ##   If given, the "validated_by" proc is called with the parsed value (after type conversion)
+    ## @option options [Proc] validated_by
+    ##   If given, the "validated_by" Proc is called with the parsed value (after type conversion)
     ##   as its sole argument. This allows for user-defined validation of the parsed value beyond
-    ##   what can be enforced by use of the "from_set" option alone. If the proc's return value is
-    ##   `#blank?`, an EnvParser::ValueNotAllowed exception is raised. To accomodate your syntax of
-    ##   choice, this validation proc may be given as a yield block instead.
+    ##   what can be enforced by use of the "from_set" option alone. If the Proc's return value is
+    ##   `#blank?`, an {EnvParser::ValueNotAllowedError} is raised. To accomodate your syntax of
+    ##   choice, this validation Proc may be given as a block instead.
     ##
     ##   Note that this option is intended to provide an inspection mechanism only -- no mutation
-    ##   of the parsed value should occur within the given proc. To that end, the argument passed is
+    ##   of the parsed value should occur within the given Proc. To that end, the argument passed is
     ##   a *frozen* duplicate of the parsed value.
     ##
     ## @yield [value]
-    ##   A block (if given) is treated exactly as the "validated_by" Proc would. Although there is
-    ##   no compelling reason to provide both a "validated_by" proc *and* a validation block, there
-    ##   is no technical limitation preventing this. **If both are given, both validation checks
-    ##   must pass.**
+    ##   A block (if given) is treated exactly as the "validated_by" Proc would.
     ##
-    ## @raise [ArgumentError, EnvParser::ValueNotAllowed]
+    ##   Although there is no compelling reason to provide both a "validated_by" Proc *and* a
+    ##   validation block, there is no technical limitation preventing this. **If both are given,
+    ##   both validation checks must pass.**
+    ##
+    ## @raise [ArgumentError, EnvParser::UnknownTypeError, EnvParser::ValueNotAllowedError]
     ##
     def parse(value, options = {}, &validation_block)
       value = ENV[value.to_s] if value.is_a? Symbol
       value = value.to_s
 
       type = known_types[options[:as]]
-      raise(ArgumentError, "invalid `as` parameter: #{options[:as].inspect}") unless type
+      raise(ArgumentError, 'missing `as` parameter') unless options.key?(:as)
+      raise(UnknownTypeError, "invalid `as` parameter: #{options[:as].inspect}") unless type
 
       return (options.key?(:if_unset) ? options[:if_unset] : type[:if_unset]) if value.blank?
 
@@ -134,9 +123,8 @@ class EnvParser
 
     ## Parses the referenced value and creates a matching constant in the requested context.
     ##
-    ## Multiple calls to "register" may be shortcutted by passing in a Hash with the same keys as
-    ## those in the "from" Hash and each value being the "register" options set for each variable's
-    ## "register" call.
+    ## Multiple calls to {.register} may be shortcutted by passing in a Hash whose keys are the
+    ## variable names and whose values are the options set for each variable's {.register} call.
     ##
     ## <pre>
     ##   ## Example shortcut usage:
@@ -153,40 +141,39 @@ class EnvParser
     ## </pre>
     ##
     ## @param name
-    ##   The name of the value to parse/interpret from the "from" Hash. If the "from" value is ENV,
-    ##   you may give a Symbol and the corresponding String key will be used instead.
+    ##   The name of the value to parse/interpret from the "from" Hash. If the "from" value is
+    ##   `ENV`, you may give a Symbol and the corresponding String key will be used instead.
     ##
-    ## @option options from [Hash]
-    ##   The source Hash from which to pull the value referenced by the "name" key. Defaults to ENV.
+    ## @option options [Hash] from (ENV)
+    ##   The source Hash from which to pull the value referenced by the "name" key.
     ##
-    ## @option options within [Module, Class]
-    ##   The module or class in which the constant should be created. Defaults to Kernel (making it
-    ##   a global constant).
+    ## @option options [Module, Class] within (Kernel)
+    ##   The module or class in which the constant should be created. Creates global constants by
+    ##   default.
     ##
-    ## @option options as [Symbol]
-    ##   See `.parse`.
+    ## @option options [Symbol] as
+    ##   See {.parse}.
     ##
     ## @option options if_unset
-    ##   See `.parse`.
+    ##   See {.parse}.
     ##
-    ## @option options from_set [Array, Range]
-    ##   See `.parse`.
+    ## @option options [Array, Range] from_set
+    ##   See {.parse}.
     ##
-    ## @option options validated_by [Proc]
-    ##   See `.parse`.
+    ## @option options [Proc] validated_by
+    ##   See {.parse}.
     ##
     ## @yield [value]
-    ##   A block (if given) is treated exactly as in `.parse`. Note, however, that a single yield
-    ##   block cannot be used to register multiple constants simultaneously -- each value needing
-    ##   validation must give its own "validated_by" proc.
+    ##   A block (if given) is treated exactly as in {.parse}. Note, however, that a single block
+    ##   cannot be used to register multiple constants simultaneously -- each value needing
+    ##   validation must give its own "validated_by" Proc.
     ##
     ## @raise [ArgumentError]
     ##
     def register(name, options = {}, &validation_block)
-      ## We want to allow for registering multiple variables simultaneously via a single `.register`
-      ## method call.
+      ## Allow for registering multiple variables simultaneously via a single call.
       if name.is_a? Hash
-        raise ArgumentError, 'cannot register multiple values with one yield block' if block_given?
+        raise(ArgumentError, 'cannot register multiple values with one block') if block_given?
         return register_all(name)
       end
 
@@ -217,14 +204,14 @@ class EnvParser
       value
     end
 
-    ## Creates ENV bindings for EnvParser.parse and EnvParser.register proxy methods.
+    ## Creates ENV bindings for {.parse} and {.register} proxy methods.
     ##
     ## The sole difference between these proxy methods and their EnvParser counterparts is that
     ## ENV.parse will interpret any value given as an ENV key (as a String), not the given value
     ## itself.  i.e. ENV.parse('XYZ', ...) is equivalent to EnvParser.parse(ENV['XYZ'], ...)
     ##
     ## @return [ENV]
-    ##   This generates no usable value, so we may as well return ENV for chaining?
+    ##   This generates no usable value.
     ##
     def add_env_bindings
       ENV.instance_eval do
@@ -256,7 +243,7 @@ class EnvParser
     ## @return [nil]
     ##   This generates no usable value.
     ##
-    ## @raise [ArgumentError, EnvParser::ValueNotAllowed]
+    ## @raise [ArgumentError, EnvParser::ValueNotAllowedError]
     ##
     def check_for_set_inclusion(value, set: nil)
       if value.respond_to?(:each)
@@ -267,7 +254,7 @@ class EnvParser
         raise ArgumentError, "invalid `from_set` parameter type: #{set.class}"
       end
 
-      raise ValueNotAllowed, 'parsed value not in allowed list/range' unless set.include?(value)
+      raise(ValueNotAllowedError, 'parsed value not in allowed set') unless set.include?(value)
 
       nil
     end
@@ -281,18 +268,18 @@ class EnvParser
     ## @return [nil]
     ##   This generates no usable value.
     ##
-    ## @raise [EnvParser::ValueNotAllowed]
+    ## @raise [EnvParser::ValueNotAllowedError]
     ##
     def check_user_defined_validations(value, proc: nil, block: nil)
       immutable_value = value.dup.freeze
-      error = 'parsed value failed user validation'
-      raise ValueNotAllowed, error unless [proc, block].compact.all? { |i| i.call(immutable_value) }
+      all_tests_passed = [proc, block].compact.all? { |i| i.call(immutable_value) }
+      raise(ValueNotAllowedError, 'parsed value failed user validation') unless all_tests_passed
 
       nil
     end
 
-    ## Receives a list of "register" calls to make, as a Hash keyed with variable names and the
-    ## values being each "register" call's option set.
+    ## Receives a list of {.register} calls to make, as a Hash keyed with variable names and the
+    ## values being each {.register} call's option set.
     ##
     ## @param list [Hash]
     ##
@@ -301,7 +288,7 @@ class EnvParser
     ## @raise [ArgumentError]
     ##
     def register_all(list)
-      raise ArgumentError, "invalid 'list' parameter type: #{list.class}" unless list.is_a?(Hash)
+      raise(ArgumentError, "invalid 'list' parameter type: #{list.class}") unless list.is_a?(Hash)
 
       list.to_a.each_with_object({}) do |tuple, output|
         output[tuple.first] = register(tuple.first, tuple.second)
@@ -310,6 +297,6 @@ class EnvParser
   end
 end
 
-## Load all files listed in "/lib/env_parser/types".
+## Load predefined types.
 ##
-Dir.glob(File.join(__dir__, %w[env_parser types *.rb])).each { |filename| require_relative filename }
+require 'env_parser/types'

data/lib/env_parser/errors.rb

@@ -0,0 +1,28 @@
+class EnvParser
+  ## Base error class for EnvParser.
+  ##
+  class Error < ::StandardError
+  end
+
+  ## Error class used to indicate a type has already been defined.
+  ##
+  class TypeAlreadyDefinedError < Error
+  end
+
+  ## Error class used to indicate the requested "as" type has not been defined.
+  ##
+  class UnknownTypeError < Error
+  end
+
+  ## Error class used to indicate value given is not convertible to the requested type.
+  ##
+  class ValueNotConvertibleError < Error
+  end
+
+  ## Error class used to indicate parsed values that do not pass user-validation, either by not
+  ## being part of the given "from_set" list, or by failing the "validated_by" Proc or yield-block
+  ## check.
+  ##
+  class ValueNotAllowedError < Error
+  end
+end

data/lib/env_parser/types.rb

@@ -0,0 +1,3 @@
+## Load all files listed in "/lib/env_parser/types".
+##
+Dir.glob(File.join(__dir__, 'types', '*.rb')).each { |filename| require_relative filename }

data/lib/env_parser/types/base_types.rb

@@ -1,39 +1,93 @@
 require 'env_parser'
 
-EnvParser.define_type(:string, if_unset: '') do |value|
-  value
-end
+## The parent module for all EnvParser type definition modules.
+## Exists only for documentation's sake.
+##
+module EnvParserTypes
+  ## Defines types for primitive classes, adding the following:
+  ##
+  ## <table>
+  ##   <tbody>
+  ##     <tr>
+  ##       <th><code>:as</code> value</th>
+  ##       <th>type returned</th>
+  ##     </tr>
+  ##   </tbody>
+  ##   <tbody>
+  ##     <tr>
+  ##       <td>:string</td>
+  ##       <td>String</td>
+  ##     </tr>
+  ##     <tr>
+  ##       <td>:symbol</td>
+  ##       <td>Symbol</td>
+  ##     </tr>
+  ##     <tr>
+  ##       <td>:boolean</td>
+  ##       <td>TrueValue / FalseValue</td>
+  ##     </tr>
+  ##     <tr>
+  ##       <td>:int / :integer</td>
+  ##       <td>Integer</td>
+  ##     </tr>
+  ##     <tr>
+  ##       <td>:float / :decimal / :number</td>
+  ##       <td>Float</td>
+  ##     </tr>
+  ##     <tr>
+  ##       <td>:json</td>
+  ##       <td>&lt; depends on JSON given &gt;</td>
+  ##     </tr>
+  ##     <tr>
+  ##       <td>:array</td>
+  ##       <td>Array</td>
+  ##     </tr>
+  ##     <tr>
+  ##       <td>:hash</td>
+  ##       <td>Hash</td>
+  ##     </tr>
+  ##   </tbody>
+  ## </table>
+  ##
+  ## Note JSON is parsed using *quirks-mode* (meaning 'true', '25', and 'null' are all considered valid, parseable JSON).
+  ##
+  module BaseTypes
+    EnvParser.define_type(:string, if_unset: '') do |value|
+      value
+    end
 
-EnvParser.define_type(:symbol, if_unset: :'', &:to_sym)
+    EnvParser.define_type(:symbol, if_unset: :'', &:to_sym)
 
-EnvParser.define_type(:boolean, if_unset: false) do |value|
-  case value
-  when '', '0', 'f', 'false' then false
-  else true
-  end
-end
+    EnvParser.define_type(:boolean, if_unset: false) do |value|
+      case value
+      when '', '0', 'f', 'false' then false
+      else true
+      end
+    end
 
-EnvParser.define_type(:integer, aliases: %i[int], if_unset: 0, &:to_i)
+    EnvParser.define_type(:integer, aliases: %i[int], if_unset: 0, &:to_i)
 
-EnvParser.define_type(:float, aliases: %i[decimal number], if_unset: 0.0, &:to_f)
+    EnvParser.define_type(:float, aliases: %i[decimal number], if_unset: 0.0, &:to_f)
 
-EnvParser.define_type(:json, if_unset: nil) do |value|
-  require 'json'
+    EnvParser.define_type(:json, if_unset: nil) do |value|
+      require 'json'
 
-  decoded_json = JSON.parse(value, quirks_mode: true)
-  { decoded_json: decoded_json }.with_indifferent_access[:decoded_json]
-end
+      decoded_json = JSON.parse(value, quirks_mode: true)
+      { decoded_json: decoded_json }.with_indifferent_access[:decoded_json]
+    end
 
-EnvParser.define_type(:array, if_unset: []) do |value|
-  decoded_json = EnvParser.parse(value, as: :json)
-  raise(ArgumentError, 'non-array value') unless decoded_json.is_a? Array
+    EnvParser.define_type(:array, if_unset: []) do |value|
+      decoded_json = EnvParser.parse(value, as: :json)
+      raise(EnvParser::ValueNotConvertibleError, 'non-array value') unless decoded_json.is_a? Array
 
-  decoded_json
-end
+      decoded_json
+    end
 
-EnvParser.define_type(:hash, if_unset: {}) do |value|
-  decoded_json = EnvParser.parse(value, as: :json)
-  raise(ArgumentError, 'non-hash value') unless decoded_json.is_a? Hash
+    EnvParser.define_type(:hash, if_unset: {}) do |value|
+      decoded_json = EnvParser.parse(value, as: :json)
+      raise(EnvParser::ValueNotConvertibleError, 'non-hash value') unless decoded_json.is_a? Hash
 
-  decoded_json
+      decoded_json
+    end
+  end
 end