env_parser 0.7.0 → 0.8.0

data/docs/method_list.html

@@ -52,6 +52,22 @@
   </li>
   
 
+  <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="EnvParser.html#define_type-class_method" title="EnvParser.define_type (method)">define_type</a></span>
+      <small>EnvParser</small>
+    </div>
+  </li>
+  
+
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="top-level-namespace.html#filename-instance_method" title="#filename (method)">#filename</a></span>
+      <small>Top Level Namespace</small>
+    </div>
+  </li>
+  
+
   <li class="even ">
     <div class="item">
       <span class='object_link'><a href="EnvParser.html#parse-class_method" title="EnvParser.parse (method)">parse</a></span>

data/docs/top-level-namespace.html

@@ -95,12 +95,90 @@
 
 
 
+  
+    <h2>
+      Instance Method Summary
+      <small><a href="#" class="summary_toggle">collapse</a></small>
+    </h2>
+
+    <ul class="summary">
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="top-level-namespace.html#filename-instance_method" title="#filename (instance method)">#<strong>filename</strong>  &#x21d2; Object </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'>
+<p>Load all files listed in “/lib/env_parser/types”.</p>
+</div></span>
+  
+</li>
+
+      
+    </ul>
+  
+
+
 
+  <div id="instance_method_details" class="method_details_list">
+    <h2>Instance Method Details</h2>
+
+    
+      <div class="method_details first">
+  <h3 class="signature first" id="filename-instance_method">
+  
+    #<strong>filename</strong>  &#x21d2; <tt>Object</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+<p>Load all files listed in “/lib/env_parser/types”.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+315</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/env_parser.rb', line 315</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>
+    </td>
+  </tr>
+</table>
+</div>
+    
+  </div>
 
 </div>
 
       <div id="footer">
-  Generated on Mon Dec 11 23:37:25 2017 by
+  Generated on Sun Dec 24 19:33:35 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

@@ -4,12 +4,68 @@ 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 < StandardError
+  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.
+    ##
+    ## @param name [Symbol]
+    ##   The name to assign to the type.
+    ##
+    ## @option options aliases [Array<Symbol>]
+    ##   An array of additional names you'd like to see refer to this same type.
+    ##
+    ## @option options if_unset
+    ##   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.
+    ##
+    ## @yield
+    ##   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
+    ##   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.
+    ##
+    ## @return [nil]
+    ##   This generates no usable value.
+    ##
+    ## @raise [ArgumentError, EnvParser::TypeAlreadyDefined]
+    ##
+    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)
+
+        known_types[type] = {
+          parser: parser,
+          if_unset: options[:if_unset]
+        }
+      end
+
+      nil
+    end
+
     ## Interprets the given value as the specified type.
     ##
     ## @param value [String, Symbol]
@@ -18,19 +74,10 @@ class EnvParser
     ##
     ## @option options as [Symbol]
     ##   The expected return type. A best-effort attempt is made to convert the source String to the
-    ##   requested type. Valid "as" types are:
-    ##
-    ##   - `:string`
-    ##   - `:symbol`
-    ##   - `:boolean`
-    ##   - `:int` / `:integer`
-    ##   - `:float` / `:decimal` / `:number`
-    ##   - `:json`
-    ##   - `:array`
-    ##   - `:hash`
+    ##   requested type.
     ##
-    ##   If no "as" option is given (or the "as" value given is not on the above list), an
-    ##   ArgumentError exception is raised.
+    ##   If no "as" option is given (or the "as" value given has not been defined), an ArgumentError
+    ##   exception is raised.
     ##
     ## @option options if_unset
     ##   Specifies the default value to return if the given "value" is either unset (`nil`) or blank
@@ -73,20 +120,12 @@ class EnvParser
       value = ENV[value.to_s] if value.is_a? Symbol
       value = value.to_s
 
-      return options[:if_unset] if value.blank? && options.key?(:if_unset)
+      type = known_types[options[:as]]
+      raise(ArgumentError, "invalid `as` parameter: #{options[:as].inspect}") unless type
 
-      value = case options[:as]
-              when :string then parse_string(value)
-              when :symbol then parse_symbol(value)
-              when :boolean then parse_boolean(value)
-              when :int, :integer then parse_integer(value)
-              when :float, :decimal, :number then parse_float(value)
-              when :json then parse_json(value)
-              when :array then parse_array(value)
-              when :hash then parse_hash(value)
-              else raise ArgumentError, "invalid `as` parameter: #{options[:as].inspect}"
-              end
+      return (options.key?(:if_unset) ? options[:if_unset] : type[:if_unset]) if value.blank?
 
+      value = type[:parser].call(value)
       check_for_set_inclusion(value, set: options[:from_set]) if options.key?(:from_set)
       check_user_defined_validations(value, proc: options[:validated_by], block: validation_block)
 
@@ -203,54 +242,10 @@ class EnvParser
 
     private
 
-    def parse_string(value)
-      value
-    end
-
-    def parse_symbol(value)
-      value.to_sym
-    end
-
-    def parse_boolean(value)
-      case value
-      when '', '0', 'f', 'false' then false
-      else true
-      end
-    end
-
-    def parse_integer(value)
-      value.to_i
-    end
-
-    def parse_float(value)
-      value.to_f
-    end
-
-    def parse_json(value)
-      require 'json'
-
-      return nil if value.blank?
-
-      decoded_json = JSON.parse(value, quirks_mode: true)
-      { decoded_json: decoded_json }.with_indifferent_access[:decoded_json]
-    end
-
-    def parse_array(value)
-      return [] if value.blank?
-
-      decoded_json = parse_json(value)
-      raise(ArgumentError, 'non-array value') unless decoded_json.is_a? Array
-
-      decoded_json
-    end
-
-    def parse_hash(value)
-      return {} if value.blank?
-
-      decoded_json = parse_json(value)
-      raise(ArgumentError, 'non-hash value') unless decoded_json.is_a? Hash
-
-      decoded_json
+    ## Class instance variable for storing known type data.
+    ##
+    def known_types
+      @known_types ||= {}
     end
 
     ## Verifies that the given "value" is included in the "set".
@@ -314,3 +309,7 @@ class EnvParser
     end
   end
 end
+
+## Load all files listed in "/lib/env_parser/types".
+##
+Dir.glob(File.join(__dir__, %w[env_parser types *.rb])).each { |filename| require_relative filename }

data/lib/env_parser/types/base_types.rb

@@ -0,0 +1,39 @@
+require 'env_parser'
+
+EnvParser.define_type(:string, if_unset: '') do |value|
+  value
+end
+
+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(: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(: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
+
+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
+
+  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
+
+  decoded_json
+end

data/lib/env_parser/version.rb

@@ -1,3 +1,3 @@
 class EnvParser
-  VERSION = '0.7.0'.freeze
+  VERSION = '0.8.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: env_parser
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Nestor Custodio
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-12 00:00:00.000000000 Z
+date: 2017-12-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -102,6 +102,8 @@ files:
 - bin/console
 - bin/setup
 - docs/EnvParser.html
+- docs/EnvParser/Error.html
+- docs/EnvParser/TypeAlreadyDefined.html
 - docs/EnvParser/ValueNotAllowed.html
 - docs/_index.html
 - docs/class_list.html
@@ -119,6 +121,7 @@ files:
 - docs/top-level-namespace.html
 - env_parser.gemspec
 - lib/env_parser.rb
+- lib/env_parser/types/base_types.rb
 - lib/env_parser/version.rb
 homepage: https://github.com/nestor-custodio/env_parser
 licenses: