inquisitive 3.1.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e22f450e21c1139aff9b5587f6da20f9964ed3f5
-  data.tar.gz: 26d9737845ee0028316664d7715ec0b2457619b1
+  metadata.gz: 78b5345c827669dee4928a4907d68799180a7b6a
+  data.tar.gz: 39899a19a8e7701645acc4134d1c1f8d4e7af5a0
 SHA512:
-  metadata.gz: 213264cbb822921b64d7393fcdeee3c135dbee7e4ae4ed93d9150b01354fe6f0803d4028cc2ad64147ccf47239de5c2ec49121a60338911beec8dc4d697dc561
-  data.tar.gz: eea7a7c74d2a3288e6902b1012bccefbaec395e7847007d1dd87fa1cfaa109bdea7d9bcf00ea41af33f36115c504e28059bf6be4ceac90f2b7750aaa0c877e65
+  metadata.gz: 0a8a2423a9dccc219ac6d3dd13fc9d953e827a83cf6aa089e6dec24deaf21e171c73f4e4b130e7472c3c4467ad4cd821bf75450c13f028096df95153f806580a
+  data.tar.gz: aae5568da7e1a36a75adbc0573fa7a2a3c26b2ef543deee13f1c44631870e752e2710d441603004fed126ca2b7bcf419ae82ca38f93d6249ff7542012bc45349

data/README.md

@@ -10,7 +10,7 @@ Synopsis
 
 Inquisitive provides String, Array, and Hash subclasses with dynamic predicate methods that allow you to interrogate the most common Ruby datastructures in a readable, friendly fashion. It's the inevitable evolution of ActiveSupport's `StringInquirer`.
 
-It also allows you to auto-instanciate and read inquisitive datastructures straight from your `ENV` hash through the `Inquisitive::Environment` module.
+It also allows you to elegantly interrogate your `ENV` hash through the `Inquisitive::Environment` module.
 
 Inquisitive will try to use ActiveSupport's `HashWithIndifferentAccess`, but if that cannot be found it will bootstrap itself with a minimal, well-tested version extracted from ActiveSupport 4.0.
 
@@ -70,6 +70,92 @@ Usage
 -----
 
 
+### Helpers
+
+You can coerce any object to a supported Inquisitive equivalent with the Inquisitive coercion helpers:
+
+```ruby
+Inquisitive.coerce('foo').class
+#=> Inquisitive::String
+Inquisitive.coerce(1).class
+#=> Integer
+
+Inquisitive['foo'].class
+#=> Inquisitive::String
+Inquisitive[1].class
+#=> Integer
+
+Inquisitive.coerce!('foo').class
+#=> Inquisitive::String
+Inquisitive.coerce!(1).class
+#=> NameError
+```
+
+You can check if any object appears to be present with the Inquisitive presence helper:
+
+```ruby
+Inquisitive.present? 'foo'
+#=> true
+Inquisitive.present? %i[foo]
+#=> true
+Inquisitive.present? {foo: :bar}
+#=> true
+Inquisitive.present? 0
+#=> true
+Inquisitive.present? true
+#=> true
+
+Inquisitive.present? ''
+#=> false
+Inquisitive.present? Array.new
+#=> false
+Inquisitive.present? Hash.new
+#=> false
+Inquisitive.present? false
+#=> false
+Inquisitive.present? nil
+#=> false
+Inquisitive.present? Inquisitive::NilClass.new
+#=> false
+```
+
+Finally, you can check if any object is explicitly an Inquisitive object with the Inquisitive object helper:
+
+```ruby
+nil_object = nil
+Inquisitive.object? nil_object
+#=> false
+Inquisitive.object? Inquisitive[nil_object]
+#=> true
+Inquisitive.object? Inquisitive::NilClass.new nil_object
+#=> true
+
+string = 'foo'
+Inquisitive.object? string
+#=> false
+Inquisitive.object? Inquisitive[string]
+#=> true
+Inquisitive.object? Inquisitive::String.new string
+#=> true
+
+array = %i[foo]
+Inquisitive.object? array
+#=> false
+Inquisitive.object? Inquisitive[array]
+#=> true
+Inquisitive.object? Inquisitive::Array.new array
+#=> true
+
+hash = {foo: :bar}
+Inquisitive.object? hash
+#=> false
+Inquisitive.object? Inquisitive[hash]
+#=> true
+Inquisitive.object? Inquisitive::Hash.new hash
+#=> true
+```
+
+
 ### String
 
 `Inquisitive::String` tests equality:
@@ -212,6 +298,35 @@ stubbed.api.domains.web?
 #=> false
 ```
 
+This custom `Inquisitive::NilClass` comes with a few caveats, read the section below to understand them.
+
+
+### NilClass
+
+`Inquisitive::NilClass` is a black-hole null object that respects the Inquisitive interface, allowing you to inquire on non-existant nested datastructures as if there was one there, negated methods included:
+
+```ruby
+nillish = Inquisitive::NilClass.new
+#=> nil
+
+nillish.nil?
+#=> true
+nillish.present?
+#=> false
+
+
+nillish.access
+#=> nil
+nillish.not.access
+#=> true
+nillish.exclude.access
+#=> true
+nillish.no.access
+#=> true
+```
+
+**Be warned**: since Ruby doesn't allow subclassing `NilClass` and provides no boolean-coercion mechanism, `Inquisitive::NilClass` **will** appear truthy. I recommend using built-in predicates (`stubbed.authentication? && ...`), presence predicates with ActiveSupport (`stubbed.authentication.present? && ...`), Inquisitive's presence utility (`Inquisitive.present?(stubbed.authentication) && ...`) or nil predicates (`stubbed.authentication.nil? || ...`) in boolean chains. Also note that for `Inquisitive::Hash` access, `stubbed.fetch(:authentication, ...)` behaves as expected.
+
 
 ### Inquisitive Environment
 

data/inquisitive.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "inquisitive"
-  spec.version       = "3.1.0"
+  spec.version       = "3.1.1"
   spec.authors       = ["Chris Keele"]
   spec.email         = ["dev@chriskeele.com"]
   spec.summary       = "Predicate methods for those curious about their datastructures."

data/lib/inquisitive.rb

@@ -2,11 +2,20 @@ module Inquisitive
 
   class << self
 
-    def [](object)
-      Inquisitive.const_get(:"#{object.class}", false).new object
+    def coerce(object)
+      coerce! object
     rescue NameError
       object
     end
+    alias_method :[], :coerce
+
+    def coerce!(object)
+      if Inquisitive.object? object
+        object
+      else
+        Inquisitive.const_get(:"#{object.class}", false).new object
+      end
+    end
 
     def present?(object)
       case object
@@ -23,20 +32,34 @@ module Inquisitive
       when ::NilClass, NilClass
         false
       else
-        !!object
+        if object.respond_to?(:present?)
+          object.present?
+        else
+          !!object
+        end
       end
     end
 
+    def object?(object)
+      object.class.name.start_with? 'Inquisitive::'
+    end
+
   end
 
 private
 
-  def predicate_method?(string)
-    string[-1] == '?'
-  end
+  module Utils
+
+  private
+
+    def predicate_method?(string)
+      string[-1] == '?'
+    end
+
+    def predication(string)
+      string[0..-2]
+    end
 
-  def predication(string)
-    string[0..-2]
   end
 
 end

data/lib/inquisitive/array.rb

@@ -1,6 +1,6 @@
 module Inquisitive
   class Array < ::Array
-    include Inquisitive
+    include Inquisitive::Utils
 
     attr_accessor :negated
     def exclude

data/lib/inquisitive/environment.rb

@@ -1,6 +1,6 @@
 module Inquisitive
   module Environment
-    include Inquisitive
+    include Inquisitive::Utils
 
     def truthy
       /true|yes|1/i
@@ -80,7 +80,7 @@ module Inquisitive
 
         def can_find_env_keys_from(var_name)
           found = env_keys_from(var_name)
-          found.empty? ? nil : found
+          Inquisitive.present?(found) ? found : nil
         end
 
         def env_keys_from(var_name)
@@ -91,24 +91,26 @@ module Inquisitive
 
         def set_hash_value_of(hash, var)
           keypath = var.split('__').map(&:downcase)
-          keypath.shift
+          keypath.shift # discard variable namespace
           hash.tap do |hash|
             keypath.reduce(hash) do |namespace, key|
+
               namespace[key] = if key == keypath.last
                 replace_empty Inquisitive[Parser[var]]
               else
-                if namespace[key].respond_to? :store
+                if namespace[key].kind_of? ::Hash
                   namespace[key]
                 else
                   Hash.new
                 end
               end
+
             end
           end
         end
 
         def replace_empty(value)
-          value == "" or value.nil? ? NilClass.new(nil) : value
+          Inquisitive.present?(value) ? value : NilClass.new(nil)
         end
 
       end

data/lib/inquisitive/hash.rb

@@ -1,20 +1,44 @@
 module Inquisitive
   class Hash < HashWithIndifferentAccess
-    include Inquisitive
+    include Inquisitive::Utils
 
     attr_accessor :negated
     def no
       dup.tap{ |s| s.negated = !s.negated }
     end
 
-    def convert_value(value, options={})
-      super(Inquisitive[value], options)
-    end
-
     def === other
       other.class == Class and other == ::Hash or super
     end
 
+    alias_method :regular_reader, :[] unless method_defined?(:regular_reader)
+    def [](key)
+      Inquisitive[regular_reader key]
+    end
+
+    def fetch(key, default=nil)
+      key = convert_key(key)
+      value = self[key]
+      if Inquisitive.present? value
+        value
+      else
+        if block_given?
+          yield(key)
+        else
+          default
+        end
+      end
+    end
+
+  protected
+
+    def convert_value(value, options={})
+      if options[:for] == :assignment
+        return if value.kind_of? NilClass
+      end
+      super(Inquisitive[value], options)
+    end
+
   private
 
     def dup

data/lib/inquisitive/nil_class.rb

@@ -1,6 +1,6 @@
 module Inquisitive
   class NilClass
-    include Inquisitive
+    include Inquisitive::Utils
 
     def initialize(object=nil); end
 
@@ -13,6 +13,10 @@ module Inquisitive
 
     undef_method :nil?, :inspect, :to_s
 
+    def present?
+      presence
+    end
+
   # Since we can't subclass NilClass
   #  (it has no allocate method)
   #  we fake its identity.
@@ -38,11 +42,15 @@ module Inquisitive
       if nil.respond_to? method_name
         nil.send method_name, *arguments
       elsif predicate_method? method_name
-        false ^ negated
+        presence
       else
         self
       end
     end
 
+    def presence
+      false ^ negated
+    end
+
   end
 end

data/lib/inquisitive/string.rb

@@ -1,6 +1,6 @@
 module Inquisitive
   class String < ::String
-    include Inquisitive
+    include Inquisitive::Utils
 
     attr_accessor :negated
     def not

data/test/inquisitive/combinatorial_environment_test.rb

@@ -23,6 +23,7 @@ class InquisitiveCombinatorialEnvironmentTest < EnvironmentTest
     ENV.delete 'HASH__IN'
     ENV.delete 'HASH__DATABASES'
     ENV.delete 'HASH__NESTED__KEY'
+    ENV.delete 'HASH__NESTED__ARRAY'
     ENV.delete 'HASH__SOMETHING_NEW'
   end
 

data/test/inquisitive_test.rb

@@ -1,7 +1,7 @@
 require 'test_helper'
 
 class InquisitiveTest < Test
-  Helpers = Module.new.extend Inquisitive
+  Utils = Module.new.extend Inquisitive::Utils
   HashWithIndifferentAccess ||= Inquisitive::HashWithIndifferentAccess
 
   def setup
@@ -147,25 +147,25 @@ class InquisitiveTest < Test
   end
 
 ####
-# HELPERS
+# UTILS
 ##
   def test_found_symbol_predicate_method_helper
-    assert Helpers.send :predicate_method?, :foo?
+    assert Utils.send :predicate_method?, :foo?
   end
   def test_found_string_predicate_method_helper
-    assert Helpers.send :predicate_method?, "foo?"
+    assert Utils.send :predicate_method?, "foo?"
   end
   def test_missing_symbol_predicate_method_helper
-    refute Helpers.send :predicate_method?, :foo
+    refute Utils.send :predicate_method?, :foo
   end
   def test_missing_string_predicate_method_helper
-    refute Helpers.send :predicate_method?, "foo"
+    refute Utils.send :predicate_method?, "foo"
   end
 
   def test_symbol_predication_helper
-    assert_equal Helpers.send(:predication, :foo?),  'foo'
+    assert_equal Utils.send(:predication, :foo?),  'foo'
   end
   def test_string_predication_helper
-    assert_equal Helpers.send(:predication, "foo?"), 'foo'
+    assert_equal Utils.send(:predication, "foo?"), 'foo'
   end
 end

data/test/shared/hash_tests.rb

@@ -10,22 +10,48 @@ module HashTests
     refute hash.registration?
   end
 
-  def test_hash_access_implicit_nil
+  def test_hash_method_access_implicit_nil
     assert_instance_of Inquisitive::NilClass, hash.missing_key
   end
-  def test_hash_access_explicit_nil
+  def test_hash_method_access_explicit_nil
     assert_instance_of Inquisitive::NilClass, hash.nothing
   end
-  def test_hash_access_string
+  def test_hash_method_access_string
     assert_instance_of Inquisitive::String, hash.in
   end
-  def test_hash_access_array
+  def test_hash_method_access_array
     assert_instance_of Inquisitive::Array, hash.databases
   end
-  def test_hash_access_hash
+  def test_hash_method_access_hash
     assert_instance_of Inquisitive::Hash, hash.nested
   end
 
+  def test_hash_access_implicit_nil
+    assert_instance_of Inquisitive::NilClass, hash[:missing_key]
+  end
+  def test_hash_access_explicit_nil
+    assert_instance_of Inquisitive::NilClass, hash[:nothing]
+  end
+  def test_hash_access_string
+    assert_instance_of Inquisitive::String, hash[:in]
+  end
+  def test_hash_access_array
+    assert_instance_of Inquisitive::Array, hash[:databases]
+  end
+  def test_hash_access_hash
+    assert_instance_of Inquisitive::Hash, hash[:nested]
+  end
+
+  def test_hash_fetch_implicit_nil
+    assert_equal hash.fetch(:missing_key, @default_value), @default_value
+  end
+  def test_hash_fetch_explicit_nil
+    assert_equal hash.fetch(:nothing, @default_value), @default_value
+  end
+  def test_hash_present_value
+    assert_equal hash.fetch(:in), @raw_string
+  end
+
   def test_hash_negative_match
     assert hash.no.registration?
   end

data/test/test_helper.rb

@@ -56,6 +56,7 @@ class Test < MiniTest::Test
       databases: @raw_array,
       nested: {key: 'value', array: %w[foo bar]}
     }
+    @default_value = 'foo'
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquisitive
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Chris Keele