inquisitive 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2c18376379e842ce96e09a55327f32e626a25c04
+  data.tar.gz: 745ebacc0f952e67809dfc5a0fc9c2aa0a6b0ac3
+SHA512:
+  metadata.gz: 40d8af8890c71242210733158d282e228a855d75882861a7a6d35ff2ca048abc267f47459613be4343c74833be9d16d4f888c83e5b8cff541b667d00e73e986c
+  data.tar.gz: 1c0f9745d5dbe15d2f9a98caea7d487db33e5276d32725819c14cadc7f2114adbb1d7de353af49e71df6ba1704103067492d8453e9b3cb224128fa959f4f672f

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in inquisitive.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,24 @@
+Copyright (c) 2013 Chris Keele
+------------------------------
+
+MIT License
+===========
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,261 @@
+Inquisitive
+===========
+
+Predicate methods for those curious about their datastructures.
+
+Inquisitive allows you to interrogate objects about their contents with friendly, readable method chains. It's the logical conclusion of ActiveSupport's `StringInquirer`.
+
+This library is extracted from several projects where I found myself building on the `Rails.env.production?` pattern: wrapping information from the `ENV` variable into more descriptive and flexible methods accessible from my main namespace. `Inquisitive::Environment` contains helper methods to further this end.
+
+For all intents and purposes Inquisitive has no dependencies, doesn't pollute the global constant namespace with anything but `Inquisitive`, and doesn't touch any core classes. It uses ActiveSupport's `HashWithIndifferentAccess`, but will bootstrap itself with a minimal version extracted from ActiveSupport 4.0 if it cannot be found.
+
+It also leans on `method_missing`, `dup`, and wrapper objects, so if your application is too inquisitive you might find it grinding to a halt. It's recommended to only use it to switch on a few core runtime environment variables. Don't serialize ActiveRecord attributes into it, is what I'm saying here.
+
+Usage
+-----
+
+### String
+
+`Inquisitive::String` tests equality:
+
+```ruby
+environment = Inquisitive::String.new 'development'
+#=> "development"
+environment.development?
+#=> true
+environment.not.development?
+#=> false
+```
+
+### Array
+
+`Inquisitive::Array` tests inclusion:
+
+```ruby
+supported_databases = Inquisitive::Array.new %w[mysql postgres sqlite]
+#=> ["mysql", "postgres", "sqlite"]
+supported_databases.postgres?
+#=> true
+supported_databases.sql_server?
+#=> false
+supported_databases.exclude.sql_server?
+#=> true
+```
+
+### Hash
+
+`Inquisitive::Hash` provides struct-like access to its values, wrapped in other inquisitive objects:
+
+```ruby
+stubbed = Inquisitive::Hash.new(
+  authentication: true,
+  in: 'development',
+  services: %w[database api],
+  ignorable: { junk: [ "" ] }
+)
+#=> {"authentication"=>true,
+#=>  "in"=>"development",
+#=>  "services"=>["database", "api"],
+#=>  "ignorable"=>{"junk"=>[""]}}
+
+stubbed.authentication?
+#=> true
+stubbed.registration?
+#=> false
+stubbed.services?
+#=> true
+stubbed.ignorable?
+#=> false
+
+stubbed.in.development?
+#=> true
+stubbed.in.production?
+#=> false
+stubbed.services.database?
+#=> true
+stubbed.services.sidekiq?
+#=> false
+```
+
+`Inquisitive::Hash` also allows negation with the `no` method:
+
+```ruby
+config = Inquisitive::Hash.new(database: 'postgres')
+#=> {"database"=>"postgres"}
+
+config.database?
+#=> true
+config.no.database?
+#=> false
+config.api?
+#=> false
+config.no.api?
+#=> true
+```
+
+### Inquisitive Environment
+
+`Inquisitive::Environment` can be used in your modules and classes to more easily interrogate the `ENV` variable:
+
+#### Strings
+
+```ruby
+ENV['ENVIRONMENT'] = "development"
+class MyGame
+  extend Inquisitive::Environment
+  inquires_about 'ENVIRONMENT'
+end
+
+MyGame.environment
+#=> "development"
+MyGame.environment.development?
+#=> true
+MyGame.environment.production?
+#=> false
+```
+
+#### Arrays
+
+```ruby
+ENV['SUPPORTED_DATABASES'] = "mysql,postgres,sqlite"
+class MyGame
+  extend Inquisitive::Environment
+  inquires_about 'SUPPORTED_DATABASES'
+end
+
+MyGame.supported_databases
+#=> ["mysql", "postgres", "sqlite"]
+MyGame.supported_databases.sqlite?
+#=> true
+MyGame.supported_databases.sql_server?
+#=> false
+```
+
+#### Hashes
+
+```ruby
+ENV['STUB_AUTHENTICATION'] = 'true'
+ENV['STUB_IN'] = "development"
+ENV['STUB_SERVICES'] = "database,api"
+class MyGame
+  extend Inquisitive::Environment
+  inquires_about 'STUB'
+end
+
+MyGame.stub.authentication?
+#=> true
+MyGame.stub.registration?
+#=> false
+MyGame.stub.in.development?
+#=> true
+MyGame.stub.in.production?
+#=> false
+MyGame.stub.services.exclude.sidekiq?
+#=> true
+MyGame.stub.services.sidekiq?
+#=> false
+```
+
+#### Naming
+
+You can name your environment inquirers with `:with`:
+
+```ruby
+ENV['ENVIRONMENT'] = "development"
+class MyGame
+  extend Inquisitive::Environment
+  inquires_about 'ENVIRONMENT', with: :env
+end
+
+MyGame.env
+#=> "development"
+MyGame.env.development?
+#=> true
+MyGame.env.production?
+#=> false
+```
+
+#### Presence
+
+Environment inquirers can have explicit presence checks, circumventing a common pitfall when reasoning about environment variables. Borrowing from the example above:
+
+```ruby
+ENV['STUB_AUTHENTICATION'] = 'false'
+class MyGame
+  extend Inquisitive::Environment
+  inquires_about 'STUB'
+end
+
+MyGame.stub.authentication
+#=> "false"
+MyGame.stub.authentication?
+#=> true
+MyGame.stub.authentication.true?
+#=> false
+```
+
+It's common to use the presence of environment variables as runtime booleans. This is frequently done by setting the environment variable to the string `"true"` when you want it to be true, and not at all otherwise. As demonstrated, this pattern can lead to ambiguity when the string is other values.
+
+By default such variables will be parsed as an `Inquisitive::String`, so predicate methods will return true whatever their contents, as long as they exist. You can bind the predicate method tighter to an explicit value if you prefer:
+
+```ruby
+ENV['STUB_AUTHENTICATION'] = 'false'
+ENV['STUB_REGISTRATION'] = 'true'
+class MyGame
+  extend Inquisitive::Environment
+  inquires_about 'STUB_AUTHENTICATION', present_if: 'true'
+  inquires_about 'STUB_REGISTRATION', present_if: 'true'
+end
+
+MyGame.stub_authentication
+#=> "false"
+MyGame.stub_authentication?
+#=> false
+
+MyGame.stub_registration
+#=> "true"
+MyGame.stub_registration?
+#=> true
+```
+
+This only works on top-level inquirers, so there's no way to get our nested `MyGame.stubbed.authentication?` to behave as expected (currently).
+
+The `present_if` check uses `===` under the covers for maximum expressiveness, so you can also use it to match against regexs and other constructs.
+
+#### Inquiry mode
+
+Environment inquirers have three configurable modes, defaulting to `:dynamic`:
+
+```ruby
+class MyGame
+  extend Inquisitive::Environment
+  inquires_about 'STUB', mode: %i[dynamic cached static].sample
+end
+```
+
+- **Dynamic**
+
+    Environment inquiries parse `ENV` on every invocation.
+
+    Use if you're manipulating the environment in between invocations, so `Inquisitive` can pick up on new values, detect changes between string or array notation, and discover new keys for hash notation.
+
+- **Cached**
+
+    Environment inquiries check `ENV` on their first invocation, and re-use the response in future invocations.
+
+    Use if you're loading the module with environment inquiry methods before you've finished preparing your environment.
+
+- **Static**
+
+    Environment inquiries use the contents of `ENV` at the moment `inquires_about` was invoked.
+
+    Use if your application is well-behaved and doesn't go mucking around with the environment at runtime.
+
+Contributing
+------------
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = Dir['test/**/*_test.rb']
+end
+task default: :test

data/inquisitive.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "inquisitive"
+  spec.version       = "1.0.0"
+  spec.authors       = ["Chris Keele"]
+  spec.email         = ["dev@chriskeele.com"]
+  spec.description   = "Predicate methods for those curious about their datastructures."
+  spec.summary       = "Predicate methods for those curious about their datastructures."
+  spec.homepage      = "https://github.com/rawsugar/inquisitive"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{^(test)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler",   ">= 1.3"
+  spec.add_development_dependency "rake",      ">= 10.0"
+  spec.add_development_dependency "minitest",  ">= 5.0"
+  spec.add_development_dependency "simplecov", ">= 0.7"
+end

data/lib/inquisitive.rb

@@ -0,0 +1,48 @@
+module Inquisitive
+
+  class << self
+
+    def [](object)
+      Inquisitive.const_get(:"#{object.class}", false).new object
+    rescue NameError
+      object
+    end
+
+    def present?(object)
+      case object
+      when ::String
+        not object.empty?
+      when ::Array
+        object.any? do |value|
+          Inquisitive.present? value
+        end
+      when ::Hash
+        object.values.any? do |value|
+          Inquisitive.present? value
+        end
+      else
+        !!object
+      end
+    end
+
+  end
+
+private
+
+  def predicate_method?(string)
+    string[-1] == '?'
+  end
+
+  def predication(string)
+    string[0..-2]
+  end
+
+end
+
+require "inquisitive/string"
+require "inquisitive/array"
+unless Object.const_defined? :HashWithIndifferentAccess
+  require "inquisitive/hash_with_indifferent_access"
+end
+require "inquisitive/hash"
+require "inquisitive/environment"

data/lib/inquisitive/array.rb

@@ -0,0 +1,24 @@
+module Inquisitive
+  class Array < ::Array
+    include Inquisitive
+    attr_accessor :negated, :array
+
+    def exclude
+      self.dup.tap{ |a| a.negated = !a.negated }
+    end
+
+  private
+
+    def respond_to_missing?(method_name, include_private = false)
+      predicate_method?(method_name)
+    end
+    def method_missing(method_name, *arguments)
+      if predicate_method? method_name
+        (include? predication(method_name)) ^ negated
+      else
+        super
+      end
+    end
+
+  end
+end

data/lib/inquisitive/environment.rb

@@ -0,0 +1,89 @@
+module Inquisitive
+  module Environment
+    include Inquisitive
+
+    def inquires_about(env_var, opts={})
+
+      env_accessor = opts.fetch(:with, env_var.downcase)
+      @__env_accessors__ ||= HashWithIndifferentAccess.new
+      @__env_accessors__[env_accessor] = env_var
+
+      mode = Inquisitive[ opts.fetch(:mode, :dynamic).to_s ]
+
+      if mode.dynamic?
+
+        define_singleton_method :"#{env_accessor}" do
+          Inquisitive[Parser[@__env_accessors__[__method__]]]
+        end
+
+      else
+
+        @__cached_env__ ||= HashWithIndifferentAccess.new
+        @__cached_env__[env_accessor] = Inquisitive[Parser[env_var]] if mode.static?
+
+        define_singleton_method :"#{env_accessor}" do
+          if @__cached_env__.has_key? __method__
+            @__cached_env__[__method__]
+          else
+            @__cached_env__[__method__] = Inquisitive[Parser[@__env_accessors__[__method__]]]
+          end
+        end
+
+      end
+
+      present_if = opts.fetch(:present_if, nil)
+
+      @__env_presence__ ||= HashWithIndifferentAccess.new
+      @__env_presence__["#{env_accessor}?"] = present_if if present_if
+
+      define_singleton_method :"#{env_accessor}?" do
+        if @__env_presence__.has_key? __method__
+          @__env_presence__[__method__] === send(predication(__method__))
+        else
+          Inquisitive.present? send(predication(__method__))
+        end
+      end
+    end
+
+    module Parser
+      class << self
+
+        def [](var_name)
+          if ENV.has_key? var_name
+            env_var = ENV[var_name]
+
+            if env_var.include? ','
+              env_var.split(',').map(&:strip)
+            else
+              env_var
+            end
+
+          elsif Parser.env_key? var_name
+
+            Parser.env_keys_from(var_name).reduce({}) do |hash, key|
+              hash[Parser.key_for(key, var_name)] = Inquisitive[Parser[key]]
+              hash
+            end
+
+          end
+        end
+
+        def env_keys_from(var_name)
+          ENV.keys.select do |key|
+            key =~ /^#{var_name}_/
+          end
+        end
+
+        def env_key?(var_name)
+          !env_keys_from(var_name).empty?
+        end
+
+        def key_for(env_key, var_name)
+          env_key.gsub("#{var_name}_", '').downcase
+        end
+
+      end
+    end
+
+  end
+end