hash_dial 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a2e69ddcb5f84bef6fa164953fa3a127396568cd91ee1debbad926902e29df3
-  data.tar.gz: efa91b61097992c4b3a57545d9cb64af8cd4a9fa924277e2c5f1af60f967e1bb
+  metadata.gz: 9534eaddcb86bd7312266b1e8f9e4f3b820907156ad51b8dc217e7a6bd0aa4bb
+  data.tar.gz: b1655d5175679674f0c0771da15a23cca7ad57531557dff5992d109d8549f238
 SHA512:
-  metadata.gz: b776b72153e96ff264e3c859cb1a12b37a06d8baa3538735e34dcffb8331780597ed119cc032c11ccdb70379f45f888ec497b09c417aeab794cc5917c29660ae
-  data.tar.gz: 4c38e006c1140bb59afc72e2fadb347e40887c49e5b7274d59e2b9cef1c33e54fde80ff475944ed9bb541ddc296ccad9a0ff61a6d86b413993e1ef03dded41a9
+  metadata.gz: 85de5edb9b862b2b7f316cd503153008d35d112df936a95edd8c11bc67f462084d421b9c32e73968cb6db706ae49f69937465885e7d7f67ed0ae6959fef695d6
+  data.tar.gz: 8668b5f99eea13ae09b8a5a702698a662cc92eb56934bf8e4c586485683c775f5ad4cfe9c852314c6a2d9c34343dcb402d10f054f268e7d3d4261460453179b0

data/.gitignore

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

data/README.md

@@ -1,8 +1,8 @@
-# HashDial
+# HashDial (Ruby Gem)
 
-**Avoid all errors when accessing a deeply nested Hash key.** HashDial goes one step beyond Hash::dig() by returning nil (or your default) if the keys requested are invalid for any reason.
+**Avoid all errors when accessing a deeply nested Hash key.** HashDial goes one step beyond `Hash::dig()` by returning `nil` (or your default) if the keys requested are invalid for any reason.
 
-In particular, if you try to access a key on a value that isn't a hash, dig() will cause an error where HashDial will not.
+In particular, if you try to access a key on a value that isn't a hash, `dig()` will cause an error where HashDial will not.
 
 ```ruby
 hash = {a: {b: {c: true}, d: 5}}
@@ -14,7 +14,8 @@ 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 deep hash 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]           #=> TypeError: no implicit conversion of Symbol into Integer
+
 #hash →   [:a][:d][:c]
 #     ↓                ↓
  hash.dial[:a][:d][:c].call #=> nil
@@ -26,22 +27,6 @@ We use the concept of placing a phone-call: you can 'dial' any set of keys regar
 
 This works by intermediating your request with a HashDialler object. Trying to access keys on this object simply builds up a list of keys to use when you later place the 'call'.
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'hash_dial'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install hash_dial
-
 ## Usage
 
 ```ruby
@@ -53,14 +38,14 @@ require 'hash_dial'
 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
-hash.call(:a, :b, :c) #=> Returns the value at hash[:a][:b][:c] or nil
+hash.call(:a, :b, :c) # Returns the value at hash[:a][:b][:c] or nil
 ```
 
 ### Use it like a Hash -- allows default return value
 
 ```ruby
-hash.dial[:a][:b][:c].call #=> Returns the value at hash[:a][:b][:c] or nil
-hash.dial[:a][:b][:c].call('Ooops') #=> Returns the value at hash[:a][:b][:c] or 'Ooops'
+hash.dial[:a][:b][:c].call          # Returns the value at hash[:a][:b][:c] or nil
+hash.dial[:a][:b][:c].call('Ooops') # Returns the value at hash[:a][:b][:c] or 'Ooops'
 ```
 
 If you don't do this all in one line, you can access the HashDialler object should you want to manipulate it:
@@ -74,6 +59,6 @@ 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 hash[:b][:c][:d][:e] or nil
-dialler.hangup #=> Returns the original hash by reference
+dialler.call # Returns the value at hash[:b][:c][:d][:e] or nil
+dialler.hangup # Returns the original hash by reference
 ```

data/hash_dial.gemspec

@@ -4,25 +4,26 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "hash_dial/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "hash_dial"
-  spec.version       = HashDial::VERSION
-  spec.authors       = ["Convincible"]
-  spec.email         = ["development@convincible.media"]
+    spec.name          = "hash_dial"
+    spec.version       = HashDial::VERSION
+    spec.authors       = ["Convincible"]
+    spec.email         = ["development@convincible.media"]
 
-  spec.summary       = "Access (deeply nested) hash keys. Get the value, or nil on any error. (Even safer than Hash::dig)."
-  spec.description   = "Avoid all errors when accessing a (deeply nested) Hash key. HashDial goes one step beyond Hash::dig() by returning 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 hash key, just surround this with '.dial' and '.call'."
-  spec.homepage      = "https://github.com/ConvincibleMedia/hash_dial"
+    spec.summary       = "Access (deeply nested) hash keys. Get the value, or nil on any error. (Even safer than Hash::dig)."
+    spec.description   = "Avoid all errors when accessing (deeply nested) Hash 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 hash key (e.g. hash[:a][:b][:c]), just surround this with '.dial' and '.call'."
+    spec.homepage      = "https://github.com/ConvincibleMedia/ruby-gem-hash_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"]
+    # 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"
+    spec.add_development_dependency "bundler", "~> 1.17"
+    spec.add_development_dependency "rake", "~> 10.0"
+    spec.add_development_dependency "rspec", "~> 3.0"
 end

data/lib/hash_dial.rb

@@ -3,18 +3,27 @@ require "hash_dial/hash_dialler"
 
 module HashDial
 
+    # Called on a Hash, returns a HashDialler object for that Hash.
+    #
+    # @param lookup Parameters to this method form initial hash keys to dial. This is unnecessary but works anyway. For simplicity, dial hash keys by accessing them as if HashDialler were a Hash.
+    #
     def to_dial(*lookup)
         return HashDialler.new(self, *lookup)
     end
 
     alias_method :dial, :to_dial
 
+    # Called directly on a Hash, immediately dials and calls the hash keys specified as arguments. Returns the value found, or nil.
+    #
+    # @param lookup The hash keys to attempt to retrieve.
+    #
     def call(*lookup)
         return HashDialler.new(self, *lookup).call
     end
 
 end
 
+# Extend core class so that hash.dial can be called
 class Hash
     include HashDial
 end

data/lib/hash_dial/hash_dialler.rb

@@ -1,61 +1,76 @@
-module HashDial
-
-	class HashDialler
-
-		@hash
-		@lookup
-		@default = nil
-
-		def initialize(hash, *lookup)
-			if hash.is_a?(Hash)
-				@hash = hash
-			else
-				@hash = {}
-			end
-			@lookup = []
-			if lookup.length > 0
-				dial!(*lookup)
-			end
-		end
-
-		def dial!(*keys)
-			#unless key.is_a(Symbol) || key.is_a(String)
-			@lookup += keys
-			return self
-		end
-
-		def call(default = nil)
-			begin
-				value = @hash.dig(*@lookup)
-			rescue
-				value = default
-			end
-			return value
-		end
-
-		def hangup
-			return @hash
-		end
-
-		def undial!(*keys)
-			if keys.length > 0
-				@lookup -= keys
-			elsif @lookup.length > 0
-				@lookup.pop
-			end
-			return self
-		end
-
-		def [](key)
-			return dial!(key)
-		end
-		def +(key)
-			return dial!(key)
-		end
-		def -(key)
-			return undial!(key)
-		end
-
-	end
-
-end
+module HashDial
+
+	class HashDialler
+
+		@hash
+		@lookup
+		@default = nil
+
+		def initialize(hash, *lookup)
+			if hash.is_a?(Hash)
+				@hash = hash
+			else
+				@hash = {}
+			end
+			@lookup = []
+			if lookup.length > 0
+				dial!(*lookup)
+			end
+		end
+
+		# Adds a hash 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 hash 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 = @hash.dig(*@lookup)
+			rescue
+				value = default
+			end
+			return value
+		end
+
+		# Return the original hash object.
+		def hangup
+			return @hash
+		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 HashDialler as if it were a Hash, e.g. hash[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/hash_dial/version.rb

@@ -1,3 +1,3 @@
 module HashDial
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hash_dial
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Convincible
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-12-20 00:00:00.000000000 Z
+date: 2019-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,11 +52,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: 'Avoid all errors when accessing a (deeply nested) Hash key. HashDial
-  goes one step beyond Hash::dig() by returning 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 hash
-  key, just surround this with ''.dial'' and ''.call''.'
+description: 'Avoid all errors when accessing (deeply nested) Hash 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 hash key (e.g. hash[:a][:b][:c]),
+  just surround this with ''.dial'' and ''.call''.'
 email:
 - development@convincible.media
 executables: []
@@ -76,7 +76,7 @@ files:
 - lib/hash_dial.rb
 - lib/hash_dial/hash_dialler.rb
 - lib/hash_dial/version.rb
-homepage: https://github.com/ConvincibleMedia/hash_dial
+homepage: https://github.com/ConvincibleMedia/ruby-gem-hash_dial
 licenses: []
 metadata: {}
 post_install_message: 
@@ -85,9 +85,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="