key_dial 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80905cbb9d3d2375534b67233544440b17c3a9aa2e092089c304db1d7f48161e
+  data.tar.gz: 6fca290e125cf5cc240e7d420b9bf504c0932bb31bf916ab30cb4fe2f73e4de0
+SHA512:
+  metadata.gz: e1c107522a250b151d0ff974d5acf41712adfeba5e1294464cd689c97265d488497c385f4eb181695e607c2bd353b7250a96dba5de80e0fa60f02b3f87ba9744
+  data.tar.gz: 523ccc88302b8ec64ae711b91b06556bf5a29d414accee9095ee1df0675ee37e7814628d7920cc13d9c0e7e871b5583954d7c6f5f6a930591ed49c403eeb9ec5

data/.gitignore

@@ -0,0 +1,17 @@
+.git
+.env
+*.lnk
+*.db
+*.ini
+
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.4.3
+before_install: gem install bundler -v 1.17.2

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in hash_dial.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    key_dial (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.3)
+    rake (10.5.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.17)
+  key_dial!
+  rake (~> 10.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   1.17.2

data/README.md

@@ -0,0 +1,82 @@
+# KeyDial (Ruby Gem)
+
+**Avoid all errors when accessing a deeply nested Hash key,** or Array or Struct key. KeyDial goes one step beyond Ruby 2.3's `dig()` method by quietly returning `nil` (or your default) if the keys requested are invalid for any reason, and never an error.
+
+In particular, if you try to access a key on a value that can't have keys, `dig()` will cause an error where KeyDial will not.
+
+```ruby
+hash = {a: {b: {c: true}, d: 5}}
+
+hash.dig( :a, :d, :c) #=> TypeError: Integer does not have #dig method
+hash.call(:a, :d, :c) #=> nil
+hash.call(:a, :b, :c) #=> true
+```
+
+**Bonus: you don't even need to fiddle with existing code.** If you have already written something to access a deeply nested key, just surround this with `dial` and `call` (rather than changing it to the form above as function parameters).
+
+```ruby
+ hash[:a][:d][:c]           #=> TypeError: no implicit conversion of Symbol into Integer
+
+#hash →   [:a][:d][:c]
+#     ↓                ↓
+ hash.dial[:a][:d][:c].call #=> nil
+```
+
+**KeyDial will work on mixed objects**, such as structs containing arrays containing hashes. It can be called from any hash, array or struct.
+
+## Explanation
+
+We use the concept of placing a phone-call: you can 'dial' any set of keys regardless of whether they exist (like entering a phone number), then finally place the 'call'. If the key is invalid for any reason you get nil/default (like a wrong number); otherwise you get the value (you're connected).
+
+This works by intermediating your request with a KeyDialler object. Trying to access keys on this object simply builds up a list of keys to use when you later place the 'call'. The call then `dig`s for the keys safely.
+
+## Usage
+
+```ruby
+require 'hash_dial'
+```
+
+### Use it like `dig()`
+
+If you want to follow this pattern, it works in the same way. You can't change the default return value when using this pattern.
+
+```ruby
+array = [0, {a: [true, false], b: 'foo'}, 2]
+
+array.call(1, :a, 0) #=> true (i.e. array[1][:a][0])
+array.call(1, :b, 0) #=> nil (i.e. array[1][:b][0] doesn't exist)
+```
+
+You can `call` on any Hash, Array or Struct after requiring this gem.
+
+Note that KeyDial does not treat strings as arrays. Trying to access a key on a string will return nil or your default. (This is also how `dig()` works.)
+
+### Use key access syntax (allows default return value)
+
+```ruby
+hash.dial[:a][4][:c].call          # Returns the value at hash[:a][4][:c] or nil
+hash.dial[:a][4][:c].call('Ooops') # Returns the value at hash[:a][4][:c] or 'Ooops'
+```
+
+You can `dial` on any Hash, Array or Struct after requiring this gem.
+
+### Use the KeyDialler object
+
+If you don't do this all in one line, you can access the KeyDialler object should you want to manipulate it:
+
+```ruby
+dialler = KeyDial::KeyDialler.new(struct) # Returns a KeyDialler object referencing struct
+dialler[:a] # Adds :a to the list of keys to dial (returns self)
+dialler.dial!(:b, :c) # Longhand way of adding more keys (returns self)
+dialler.undial! # Removes the last-added key (returns self)
+dialler[:c][:d] # Adds two more keys (returns self)
+dialler += :e # Adds yet one more (returns self)
+dialler -= :a # Removes all such keys from the list (returns self)
+# So far we have dialled [:b][:c][:d][:e]
+dialler.call # Returns the value at struct[:b][:c][:d][:e] or nil
+dialler.hangup # Returns the original keyed object by reference
+```
+
+## Note
+
+KeyDial is a generic version of the gem HashDial, replacing and deprecating it.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "key_dial"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/key_dial.gemspec

@@ -0,0 +1,29 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "key_dial/version"
+
+Gem::Specification.new do |spec|
+    spec.name          = "key_dial"
+    spec.version       = KeyDial::VERSION
+    spec.authors       = ["Convincible"]
+    spec.email         = ["development@convincible.media"]
+
+    spec.summary       = "Access (deeply nested) Hash, Array or Struct keys. Get the value, or nil/default instead of any error. (Even safer than Ruby 2.3's dig method)."
+    spec.description   = "Avoid all errors when accessing (deeply nested) Hash, Array or Struct keys. Safer than dig(), as will quietly return nil (or your default) if the keys requested are invalid for any reason at all. Bonus: you don't even need to fiddle with existing code. If you have already written something to access a deep key (e.g. hash[:a][:b][:c]), just surround this with '.dial' and '.call'."
+    spec.homepage      = "https://github.com/ConvincibleMedia/ruby-gem-key_dial"
+
+    # Specify which files should be added to the gem when it is released.
+    # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+    spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+        `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    end
+    spec.bindir        = "exe"
+    spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+    spec.require_paths = ["lib"]
+    spec.required_ruby_version = '>= 2.3'
+
+    spec.add_development_dependency "bundler", "~> 1.17"
+    spec.add_development_dependency "rake", "~> 10.0"
+    spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/key_dial.rb

@@ -0,0 +1,37 @@
+require "key_dial/version"
+require "key_dial/key_dialler"
+
+module KeyDial
+
+    # Called on a Hash, Array or Struct, returns a KeyDialler object.
+    #
+    # @param lookup Parameters to this method form initial keys to dial. This is unnecessary but works anyway. For simplicity, dial keys by accessing them as if KeyDialler were a keyed object itself.
+    #
+    def to_dial(*lookup)
+        return KeyDialler.new(self, *lookup)
+    end
+
+    alias_method :dial, :to_dial
+
+    # Called directly on a keyed object, immediately dials and calls the keys specified as arguments. Returns the value found, or nil.
+    #
+    # @param lookup The keys to attempt to retrieve.
+    #
+    def call(*lookup)
+        return KeyDialler.new(self, *lookup).call
+    end
+
+end
+
+# Extend core class so that .dial can be called seamlessly
+class Hash
+    include KeyDial
+end
+
+class Array
+    include KeyDial
+end
+
+class Struct
+    include KeyDial
+end

data/lib/key_dial/key_dialler.rb

@@ -0,0 +1,76 @@
+module KeyDial
+
+	class KeyDialler
+
+		@obj_with_keys
+		@lookup
+		@default = nil
+
+		def initialize(obj_with_keys, *lookup)
+			if obj_with_keys.respond_to?(:dig)
+				@obj_with_keys = obj_with_keys
+			else
+				raise ArgumentError.new('HashDialler must be initialized on a Hash, Array or Struct, or an object that responds to :dig.')
+			end
+			@lookup = []
+			if lookup.length > 0
+				dial!(*lookup)
+			end
+		end
+
+		# Adds a key to the list of nested keys to try, one level deeper.
+		#
+		# @param keys The key to add. Multiple arguments would add multiple keys.
+		#
+		def dial!(*keys)
+			#unless key.is_a(Symbol) || key.is_a(String)
+			@lookup += keys
+			return self
+		end
+
+		# Digs into the object to the list of keys specified by dialling. Returns nil or default if specified.
+		#
+		# @param default What to return if no key is found.
+		#
+		def call(default = nil)
+			begin
+				value = @obj_with_keys.dig(*@lookup)
+			rescue
+				value = default
+			end
+			return value
+		end
+
+		# Return the original keyed object.
+		def hangup
+			return @obj_with_keys
+		end
+
+		# Remove keys from the dialling list.
+		#
+		# @param keys If specified, these keys would be removed from wherever they appear in the dialling list. Otherwise, the last added key is removed.
+		#
+		def undial!(*keys)
+			if keys.length > 0
+				@lookup -= keys
+			elsif @lookup.length > 0
+				@lookup.pop
+			end
+			return self
+		end
+
+		# The preferred way to build up your dialling list. Access KeyDialler as if it were a keyed object, e.g. keydialler[a][b][c]. This does not actually return any value, rather it dials those keys (awaiting a call).
+		#
+		def [](key)
+			return dial!(key)
+		end
+		def +(key)
+			return dial!(key)
+		end
+		def -(key)
+			return undial!(key)
+		end
+
+	end
+
+end

data/lib/key_dial/version.rb

@@ -0,0 +1,3 @@
+module KeyDial
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: key_dial
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Convincible
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-01-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 'Avoid all errors when accessing (deeply nested) Hash, Array or Struct
+  keys. Safer than dig(), as will quietly return nil (or your default) if the keys
+  requested are invalid for any reason at all. Bonus: you don''t even need to fiddle
+  with existing code. If you have already written something to access a deep key (e.g.
+  hash[:a][:b][:c]), just surround this with ''.dial'' and ''.call''.'
+email:
+- development@convincible.media
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- key_dial.gemspec
+- lib/key_dial.rb
+- lib/key_dial/key_dialler.rb
+- lib/key_dial/version.rb
+homepage: https://github.com/ConvincibleMedia/ruby-gem-key_dial
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.0
+signing_key: 
+specification_version: 4
+summary: Access (deeply nested) Hash, Array or Struct keys. Get the value, or nil/default
+  instead of any error. (Even safer than Ruby 2.3's dig method).
+test_files: []