key_dial 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80905cbb9d3d2375534b67233544440b17c3a9aa2e092089c304db1d7f48161e
-  data.tar.gz: 6fca290e125cf5cc240e7d420b9bf504c0932bb31bf916ab30cb4fe2f73e4de0
+  metadata.gz: adcb8d79a70615b55ef7096cb21d1df639a35fa8e83e42eff35e59dbfa2b466a
+  data.tar.gz: 5eed7fe134f7bf05227012c4a0242a5c89cc76d8c62afacc978ff17a1e09e76a
 SHA512:
-  metadata.gz: e1c107522a250b151d0ff974d5acf41712adfeba5e1294464cd689c97265d488497c385f4eb181695e607c2bd353b7250a96dba5de80e0fa60f02b3f87ba9744
-  data.tar.gz: 523ccc88302b8ec64ae711b91b06556bf5a29d414accee9095ee1df0675ee37e7814628d7920cc13d9c0e7e871b5583954d7c6f5f6a930591ed49c403eeb9ec5
+  metadata.gz: 28a754fba139b866e22a2184782ceba09aaed757384b92aa3607d4f9bff0b551162818dfac4ea01919509d9625e030a2b27c33184ca8c9aa938076995e2f0613
+  data.tar.gz: cac3c202ca11e2c398d35cf89079e1ead4dc2e95e83f6aed0ea281b672f5b2916bbadd63d1241418c0f46cf757f3d6268f753f695770443873b725481a9f547f

data/lib/key_dial/coercion.rb

@@ -0,0 +1,189 @@
+module KeyDial
+
+	module Coercion
+
+		module Hashes
+
+			# Convert a Hash to a Struct. {a: 1, b: 2, c: 3} will become <Struct :a=1, :b=2, :c=3>
+			#
+			def to_struct(type_class = nil)
+				return Coercion::Structs.create(self, type_class)
+			end
+
+			def self.included(base)
+			   	base.extend ClassMethods
+			end
+
+			module ClassMethods
+
+				# Allows you to do Hash.from(obj) to create a Hash from any object intelligently.
+				#
+				def from(obj)
+					return obj if obj.is_a?(Hash)
+					return obj.to_hash if obj.is_a?(Array)
+					return obj.to_h if obj.is_a?(Struct)
+					return {0 => obj}
+				end
+
+			end
+
+		end
+
+		module Arrays
+
+			# Convert an Array to a Hash, providing an alternative to the native to_h() method. to_hash() is more forgiving and avoids errors. ['a', 'b', 'c'] will become {0 => 'a', 1 => 'b', 2 => 'c'}
+			#
+			def to_hash
+				self.each_with_index.map { |k, i|
+					if k.is_a?(Array)
+						if k.empty?
+							[i, nil]
+						elsif k.size == 2
+							k # k in this case is a keyval pair, e.g. [k, v]
+						else
+							[i, k]
+						end
+					else
+						[i, k]
+					end
+				}.to_h
+			end
+
+			# Convert an Array to a Struct. ['a', 'b', 'c'] will become <Struct :'0'='a', :'1'='b', :'2'='c'>
+			#
+			# @param type_class If a sub-class of Struct is provided, this sub-class will be instantiated
+			#
+			def to_struct(type_class = nil)
+				return Coercion::Structs.create(self, type_class)
+			end
+
+			def self.included(base)
+			   	base.extend ClassMethods
+			end
+
+			module ClassMethods
+
+				# Allows you to do Array.from(obj) to create an Array from any object intelligently.
+				#
+				def from(obj)
+					return obj if obj.is_a?(Array)
+					return obj.to_a if obj.is_a?(Hash)
+					return obj.to_h.to_a if obj.is_a?(Struct)
+					return [obj]
+				end
+
+			end
+
+		end
+
+		module Structs
+
+			EMPTY = Struct.new(:'0').new.freeze
+
+			# Convert a Struct to another Struct.
+			#
+			# @param type_class If a sub-class of Struct is provided, the Struct will be converted to this sub-class
+			#
+			def to_struct(type_class = nil)
+				if type_class.is_a?(Class) && type_class < Struct
+					return Struct.from(self, type_class)
+				else
+					return self
+				end
+			end
+
+			def self.included(base)
+			   	base.extend ClassMethods
+			end
+
+			module ClassMethods
+
+				# Allows you to do Struct.from(obj) to instantiate a Struct using keys/values from any object intelligently.
+				#
+				# @param type_class If a sub-class of Struct is provided, this sub-class will be instantiated
+				#
+				def from(obj, type_class = nil)
+					if !obj.is_a?(Struct) && !obj.is_a?(Hash) && !obj.is_a?(Array) && type_class == nil
+						s = EMPTY.dup
+						s[0] = obj
+						return s
+					else
+						return Coercion::Structs.create(obj, type_class)
+					end
+				end
+
+			end
+
+			# Struct creation function not really meant to be used directly. Prefer Struct.from(obj).
+			#
+			# @param from_obj Keys/values from this object will be used to fill out the new Struct.
+			# @param type_class If a sub-class of Struct is provided, this sub-class will be instantiated
+			#
+			def self.create(from_obj, type_class = nil)
+				if from_obj.is_a?(Hash) || from_obj.is_a?(Array) || from_obj.is_a?(Struct)
+				 	return EMPTY.dup if from_obj.empty? && type_class == nil
+					from = from_obj
+				else
+					from = [from_obj]
+				end
+
+				# Has a specific type of Struct been specified?
+				if type_class.is_a?(Class) && type_class < Struct
+					if from.is_a?(type_class)
+						# Has an instantiation of that type of Struct been passed in? If so, just return it
+						return from
+					else
+						values = []
+						if from.is_a?(Array)
+							# Get as many elements of array as this Struct can handle - discard the rest
+							values = from.first(type_class.members.size)
+						else 
+							# Not an Array, so must be another Struct or Hash
+							type_class.members.each { |key|
+								if from.key?(key)
+									# If the object has this expected key, use it
+									values << from[key]
+								else
+									# Otherwise, fill this key with nil
+									values << nil
+									# Keys in the from object which don't match expected keys are discarded
+								end
+							}
+						end
+						# values now contains a value or nil for each of this class's expected keys
+						return type_class.new(*values)
+					end
+				else
+					# Anonymous Struct
+					new_values = from.is_a?(Array) ? from : from.values
+					# Iterate over the keys of the from object
+					# (Array.keys is monkeypatched in)
+					new_keys = from.keys.each_with_index.map { |k, i|
+						if k.respond_to?(:to_sym) && k != ''
+							k.to_sym
+						elsif k.respond_to?(:to_s) && !k.nil?
+							k.to_s.to_sym
+						else
+							# If we can't construct a valid Struct key for this key, we discard the corresponding value
+							new_values.delete_at(i)
+							nil
+						end
+					}.reject(&:nil?)
+					if new_keys.size > 0
+						# Create anonymous Struct with the specified keys and values
+						return Struct.new(*new_keys).new(*new_values)
+					else
+						# Return the Empty Struct
+						return EMPTY.dup
+					end
+				end
+
+			rescue
+				return EMPTY.dup
+			end
+
+		end
+
+	end
+
+end

data/lib/key_dial/key_dialler.rb

@@ -1,76 +1,462 @@
-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
+module KeyDial
+
+	class KeyDialler
+
+		DEFAULT_OBJECT = {}.freeze
+
+		@obj_with_keys
+		@lookup
+		@default
+
+		def initialize(obj_with_keys = DEFAULT_OBJECT, *lookup)
+			self.object = obj_with_keys
+			@lookup = []
+			@default = nil
+			if lookup.length > 0
+				dial!(*lookup)
+			end
+		end
+
+		attr_accessor :default
+
+		# Adds a key to the list of nested keys to try, one level deeper.
+		#
+		# @param keys_array The key(s) to add. Multiple arguments would add multiple keys.
+		#
+		def dial!(*keys_array)
+			keys_array = use_keys(keys_array)
+			@lookup += keys_array
+			return self
+		end
+
+		# Remove keys from the dialling list.
+		#
+		# @param keys_array 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_array)
+			keys_array = use_keys(keys_array)
+			if keys_array.length > 0
+				@lookup -= keys_array
+			elsif @lookup.length > 0
+				@lookup.pop
+			end
+			return self
+		end
+
+		# Digs into the object to the list of keys specified by dialling. Returns nil, or default if specified, if the key can't be found.
+		#
+		# @param default What to return if no key is found.
+		#
+		def set?
+			begin
+
+				value = @lookup.inject(@obj_with_keys) { |deep_obj, this_key|
+					# Has to be an object that can have keys
+					return false unless deep_obj.respond_to?(:[])
+
+					if deep_obj.respond_to?(:fetch)
+						# Hash, Array and Struct all respond to fetch
+						# We've monkeypatched fetch to Struct
+						if deep_obj.is_a?(Array)
+							# Check array separately as must fetch numeric key
+							return false unless Keys.index?(this_key)
+						end
+						next_obj = deep_obj.fetch(this_key, Keys::MISSING)
+					else
+						return false
+					end
+
+					# No need to go any further
+					return false if Keys::MISSING == next_obj
+
+					# Reinject value to next loop
+					next_obj
+				}
+
+			rescue
+				# If fetch throws a wobbly at any point, fail gracefully
+				return false
+			end
+			# No errors - yield the value if desired
+			if block_given?
+				yield(value)
+			end
+			# Return true
+			return true
+		end
+
+		def fetch(default = (default_skipped = true; @default))
+			value = nil
+			if set? { |exists| value = exists }
+				return value
+			else
+				if block_given?
+					warn 'warning: block supersedes default value argument' if !default_skipped
+					return yield
+				else
+					return default
+				end
+			end
+		end
+
+		def call(default = (default_skipped = true; @default))
+			value = nil
+			if set? { |exists| value = exists }
+				# Key exists at key list, and we've captured it to value
+				if block_given?
+					# If block given, yield value to the block
+					return yield(value)
+				else
+					# Otherwise, just return the value
+					return value
+				end
+			else
+				# Key does not exist
+				if default.is_a?(Proc)
+					# If default provided is a Proc, don't just return this as a value - run it
+					return default.call
+				else
+					# Return the default
+					return default
+				end
+			end
+		end
+
+		# Return the array of keys dialled so far.
+		def keys
+			return @lookup
+		end
+
+		# Set the key list directly.
+		def keys=(keys_array)
+			if keys_array.is_a?(Array)
+				@lookup = []
+				dial!(*keys_array)
+			else
+				raise ArgumentError, 'Key list must be set to an array.'
+			end
+		end
+
+		# Return the original keyed object.
+		def object
+			return @obj_with_keys
+		end
+		alias hangup object
+
+		# Set/change the keyed object.
+		#
+		# @param obj_with_keys The object that should be dialled, e.g. a Hash, Array or Struct.
+		#
+		def object=(obj_with_keys)
+			obj_with_keys = DEFAULT_OBJECT if obj_with_keys.nil?
+			if obj_with_keys.respond_to?(:fetch)
+				@obj_with_keys = obj_with_keys
+			else
+				raise ArgumentError, 'KeyDialler must be used on a Hash, Array or Struct, or object that responds to the fetch method.'
+			end
+		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).
+		#
+		# @param key The key to dial, determined via [key] syntax
+		#
+		def [](key)
+			return dial!(key)
+		end
+
+		# The preferred way to set a value at the end of a set of keys. Will create or coerce intermediate keys if required.
+		#
+		# @param key_obj The last key to dial, determined via [key] syntax
+		# @param value_obj What to set it to.
+		#
+		def []=(key_obj, value_obj)
+			# Dial the key to be set - @lookup can never be empty
+			dial!(key_obj)
+			# Set the value
+			return set!(value_obj)
+		end
+
+		# The preferred way to add to an array at the end of a set of keys. Will create or coerce the array if required.
+		#
+		# @param value_obj The value to add to the array at the dialled location.
+		#
+		def <<(value_obj)
+			array = call(Keys::MISSING)
+			# Dial the next array key index - @lookup can never be empty before set!()
+			if array.is_a?(Array) || array.is_a?(Hash) || array.is_a?(Struct)
+				dial!(array.size)
+			elsif array == Keys::MISSING
+				dial!(0)
+			else
+				dial!(1)
+			end
+			return set!(value_obj)
+		end
+
+		# Set any deep key. If keys along the way don't exist, empty Hashes or Arrays will be created. Warning: this method will try to coerce your main object to match the structure implied by your keys.
+		#
+		# @param key_obj The key to alter, determined via [key_obj] syntax
+		# @param value_obj What to set this key to, determined via [key_obj] = value_obj syntax
+		#
+		def set!(value_obj)
+			insist!()
+			@lookup[0...-1].inject(@obj_with_keys) { |deep_obj, this_key|
+				deep_obj[this_key]
+			}[@lookup[-1]] = value_obj
+		end
+
+		# Forces the current list of dialled keys to be instantiated on the object.
+		#
+		# @param type_class The object class that must be instantiated at the end of the key list. Either Hash, Array or Struct (or Struct::Type). Will create a new object if the key does not exist, or coerce existing values if it does.
+		#
+		def insist!(type_class = (type_class_skipped = true; nil))
+
+			return @obj_with_keys if @lookup.empty?
+			# Hashes can be accessed at [Object] of any kind
+			# Structs can be accessed at [String] and [Symbol], and [Integer] for the nth member (or [Float] which rounds down)
+			# Arrays can be accessed at [Integer] or [Float] which rounds down
+
+			index = 0
+			# Will run at least twice, as:
+			# Always runs once for @obj_with_keys itself
+			# Then at least one more time because @lookup is not empty
+			return @lookup.inject(@obj_with_keys) { |deep_obj, this_key|
+				last_index = index >= @lookup.size - 1
+
+				# this = object to be accessed
+				# key = key to access on this
+				# access = what kind of key is key
+
+				key = {
+					this: {
+						type: nil,
+						value: this_key
+					},
+					next: {
+						type: nil,
+						value: last_index ? Keys::MISSING : @lookup[index + 1]
+					},
+					last: {
+						type: nil,
+						value: index == 0 ? Keys::MISSING : @lookup[index - 1]
+					}
+				}
+
+				key.each { |pos, _|
+					if Keys.index?(key[pos][:value])
+						key[pos][:type] = :index
+						key[pos][:max] = key[pos][:value].magnitude.floor + (key[pos][:value] <= -1 ? 0 : 1)
+					else
+						key[pos][:type] = :object
+						key[pos][:type] = :string if key[pos][:value].is_a?(String)
+						key[pos][:type] = :symbol if key[pos][:value].is_a?(Symbol)
+					end
+				}
+
+				reconstruct = false
+
+				# Ensure this object is a supported type - always true for index == 0 i.e. @obj_with_keys itself
+				if !(deep_obj.respond_to?(:fetch) && deep_obj.respond_to?(:[]))
+					# Not a supported type! e.g. a string
+					if key[:this][:type] == :index
+						# If we'll access an array here, re-embed the unsupported object in an array as [0 => original]
+						deep_obj = Array.new(key[:this][:max] - 1).unshift(deep_obj)
+					else
+						# Otherwise, embed the unsupported object in a hash with the key 0
+						deep_obj = {0 => deep_obj}
+					end
+					# Will never run on @obj_with_keys itself
+					reconstruct = true
+				else
+					# Supported type, but what if this doesn't accept that kind of key? Then...
+
+					# "You asked for it!"(TM)
+					# In a Struct, if accessing a member that doesn't exist, we'll replace the struct with a redefined anonymous one containing the members you wanted. This is dangerous but it's your fault.
+					if deep_obj.is_a?(Struct)
+						if key[:this][:type] == :string || key[:this][:type] == :symbol
+							if !deep_obj.members.include?(key[:this][:value].to_sym)
+								# You asked for it!
+								# Add the member you requested
+								new_members = deep_obj.members.push(key[:this][:value].to_sym)
+								deep_obj = Struct.new(*new_members).new(*deep_obj.values)
+								reconstruct = true
+							end
+						elsif key[:this][:type] == :index
+							if key[:this][:max] > deep_obj.size
+								# You asked for it!
+								# Create new numeric members up to key requested
+								if key[:this][:value] <= -1
+									range = 0..((key[:this][:max] - deep_obj.size) - 1)
+								else
+									range = deep_obj.size..(key[:this][:max] - 1)
+								end
+								new_keys = (range).to_a.map { |num| num.to_s.to_sym }
+								# Shove them in
+								if key[:this][:value] <= -1
+									# Prepend
+									new_members = new_keys.concat(deep_obj.members)
+									new_values = Array.new(new_keys.size - deep_obj.values.size, nil).concat(deep_obj.values)
+								else
+									# Append
+									new_members = deep_obj.members.concat(new_keys)
+									new_values = deep_obj.values
+								end
+								deep_obj = Struct.new(*new_members).new(*new_values)
+								reconstruct = true
+							end
+						end
+					end
+
+					# "You asked for it!"(TM)
+					# If accessing an array with a key that doesn't exist, we'll add elements to the array or change the array to a hash. This is dangerous but it's your fault.
+					if deep_obj.is_a?(Array)
+						if key[:this][:type] == :index
+							if key[:this][:value] <= -1 && key[:this][:max] > deep_obj.size
+								# You asked for it!
+								# The only time an Array will break is if you try to set a negative key larger than the size of the array. In this case we'll prepend your array with nils.
+								deep_obj = Array.new(key[:this][:max] - deep_obj.size, nil).concat(deep_obj)
+								reconstruct = true
+							end
+						else
+							# You asked for it!
+							# Trying to access non-numeric key on an array, so will convert the array into a hash with integer keys.
+							deep_obj = deep_obj.each_with_index.map { |v, index| [index, v] }.to_h
+							reconstruct = true
+						end
+					end
+
+				end
+
+				if reconstruct
+					# Go back and reinject this altered value into the array
+					@lookup[0...(index-1)].inject(@obj_with_keys) { |deep_obj2, this_key2|
+						deep_obj2[this_key2]
+					}[key[:last][:value]] = deep_obj
+				end
+
+				# Does this object already have this key?
+				if !deep_obj.dial[key[:this][:value]].set?
+					# If not, create empty array/hash dependant on upcoming key
+					if type_class_skipped
+						if key[:next][:type] == :index
+							if key[:next][:value] <= -1
+								# Ensure new array big enough to address a negative key
+								deep_obj[key[:this][:value]] = Array.new(key[:next][:max])
+							else
+								# Otherwise, can just create an empty array
+								deep_obj[key[:this][:value]] = []
+							end
+						else
+							# Create an empty hash awaiting keys/values
+							deep_obj[key[:this][:value]] = {}
+						end
+					else
+						if type_class == Array
+							deep_obj[key[:this][:value]] = []
+						elsif type_class == Hash
+							deep_obj[key[:this][:value]] = {}
+						elsif type_class == Struct
+							# Why would you do this?
+							deep_obj[key[:this][:value]] = Coercion::Structs::EMPTY.dup
+						elsif type_class.is_a?(Class) && type_class < Struct
+							deep_obj[key[:this][:value]] = type_class.new
+						elsif type_class.respond_to?(:new)
+							begin
+								deep_obj[key[:this][:value]] = type_class.new
+							rescue
+								deep_obj[key[:this][:value]] = nil
+							end
+						else
+							deep_obj[key[:this][:value]] = nil
+						end
+					end
+				elsif !type_class_skipped && last_index && !deep_obj[key[:this][:value]].is_a?(type_class)
+					#Key already exists, but we must ensure it's of the right type
+					if type_class == Array
+						deep_obj[key[:this][:value]] = Array.from(deep_obj[key[:this][:value]])
+					elsif type_class == Hash
+						deep_obj[key[:this][:value]] = Hash.from(deep_obj[key[:this][:value]])
+					elsif type_class == Struct
+						# Why would you do this?
+						deep_obj[key[:this][:value]] = Struct.from(deep_obj[key[:this][:value]])
+					elsif type_class.is_a?(Class) && type_class < Struct
+						deep_obj[key[:this][:value]] = Struct.from(deep_obj[key[:this][:value]], type_class)
+					elsif type_class == String && deep_obj[key[:this][:value]].respond_to?(:to_s)
+						deep_obj[key[:this][:value]] = deep_obj[key[:this][:value]].to_s
+					elsif type_class == Symbol
+						if deep_obj[key[:this][:value]].respond_to?(:to_sym)
+							deep_obj[key[:this][:value]] = deep_obj[key[:this][:value]].to_s
+						elsif deep_obj[key[:this][:value]].respond_to?(:to_s)
+							deep_obj[key[:this][:value]] = deep_obj[key[:this][:value]].to_s.to_sym
+						else
+							warn "Could not coerce value to #{type_class}"
+						end
+					elsif type_class.respond_to?(:new)
+						begin
+							deep_obj[key[:this][:value]] = type_class.new
+						rescue
+							warn "Could not coerce value to #{type_class}"
+						end
+					else
+						warn "Could not coerce value to #{type_class}"
+					end
+				end
+
+				# Quit if this is the penultimate or last iteration
+				#next deep_obj if last_index
+
+				# Increment index manually
+				index += 1
+
+				# Before here, we must make sure we can access key on deep_obj
+				# Return the value at this key for the next part of inject loop
+				deep_obj[key[:this][:value]]
+
+			}
+
+			# Final access (and set) of last key in the @lookup - by this point should be guaranteed to work!
+			#if value_obj_skipped
+			#	return obj_to_set[@lookup[-1]]
+			#else
+			#	return obj_to_set[@lookup[-1]] = value_obj
+			#end
+
+		end
+
+		# Add a key to the dialling chain. If an array is passed, each item in the array will be added in order.
+		def +(key)
+			return dial!(*key)
+		end
+
+		# Remove keys that have been dialled.
+		#
+		# @param key If an integer n, the last n keys will be removed. Otherwise, all keys matching this argument will be removed from any point in the dialing chain. If an array is passed, each item in the array will be removed.
+		#
+		def -(key)
+			if key.is_a?(Integer) && key > 0
+				return key.times { undial! }
+			else
+				return undial!(*key)
+			end
+		end
+
+		# Private class method to reduce KeyDialler objects to their contained key arrays if a KeyDialler object itself is passed as a potential key to dial
+		private def use_keys(keys_array)
+			keys_array = [keys_array] if !keys_array.is_a?(Array)
+			keys_array.flatten
+			keys_return = []
+			keys_array.each { |key|
+				if key.is_a?(KeyDialler)
+					# Add returned keys inline (flattened into array)
+					keys_return += key.keys
+				else
+					# Add any other key as a whole object
+					keys_return.push(key)
+				end
+			}
+			return keys_return
+		end
+
+	end
+
+end

data/lib/key_dial/version.rb

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

data/lib/key_dial.rb

@@ -1,37 +1,145 @@
-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
+require "key_dial/version"
+require "key_dial/key_dialler"
+require "key_dial/coercion"
+
+module KeyDial
+
+	# Called on a Hash, Array or Struct, returns a KeyDialler object, ready to dial keys against that Hash, Array or Struct.
+	#
+	# @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. A default cannot be specified.
+	#
+	# @param lookup The keys to attempt to retrieve.
+	#
+	def call(*lookup)
+		return KeyDialler.new(self, *lookup).call
+	end
+
+end
+
+# Extend core classes so that .dial can be called seamlessly
+class Hash
+	include KeyDial
+	include KeyDial::Coercion::Hashes
+
+	alias to_array to_a
+	alias to_hash to_h
+end
+
+# Bring Array and Struct into parity with Hash for key? and fetch
+# Will not redefine these methods if they already exist, either from some future Ruby version or another gem
+
+class Array
+	include KeyDial
+	include KeyDial::Coercion::Arrays
+
+	# Returns true if this Array has the specified index.
+	def key?(key_obj)
+		if key_obj.is_a?(Numeric) && key_obj.respond_to?(:to_i)
+			key = key_obj.to_i
+			return key.magnitude + (key <= -1 ? 0 : 1) <= self.size
+		else
+			return false
+		end
+	end if !method_defined?(:key?)
+
+	# Returns an Array of all the valid indices for this Array
+	def keys
+		if self.size > 0
+			return Array(0..(self.size - 1))
+		else
+			return []
+		end
+	end
+
+	alias values to_ary
+	alias to_array to_a
+
+end
+
+class Struct
+	include KeyDial
+	include KeyDial::Coercion::Structs
+
+	# Extend Struct to give it a key? method
+	def key?(key_obj)
+		# These would be valid keys in struct[key] syntax
+		if key_obj.is_a?(Symbol)
+			key = key_obj
+		elsif key_obj.is_a?(String)
+			key = key_obj.to_sym
+		elsif key_obj.is_a?(Numeric) && key_obj.respond_to?(:to_i)
+			key = key_obj.to_i
+		else
+			return false #raise TypeError, "no implicit conversion of #{key_obj.class} into Symbol"
+		end
+
+		if key.is_a?(Symbol)
+			# Does the struct have the identified key?
+			return self.members.include?(key)
+		elsif key.is_a?(Integer)
+			# Does the struct have this numbered key?
+			return key.magnitude + (key <= -1 ? 0 : 1) <= self.size
+		end
+	end if !method_defined?(:key?)
+
+	# Extend Struct to give it a fetch method
+	def fetch(key_obj, default = (default_skipped = true; nil))
+		if key?(key_obj)
+			# Use key? method to check this struct has the requested key
+			# key? method ensures that key_obj is valid inside struct[key] syntax
+			return self[key_obj]
+		else
+			# Struct doesn't contain this key - proceed to defaults
+			if block_given?
+				# Warn if both block and default supplied
+				warn 'warning: block supersedes default value argument' if !default_skipped
+				# Return result of block as default
+				return yield(key_obj)
+			elsif !default_skipped
+				return default
+			else
+				raise KeyError, "key not found: #{key_obj.to_s}"
+			end
+		end
+	end if !method_defined?(:fetch)
+
+	alias keys members
+	alias to_array to_a
+	alias to_hash to_h
+
+	# Structs are not empty by definition
+	def empty?; false; end
+
+end
+
+# Ability to create anonymous key lists (on no particular object) with Keys[a][b][c]
+module Keys
+
+	class Missing; end
+	MISSING = Missing.new.freeze
+	MISSING.freeze
+
+	# Create a new key list (KeyDialler) object using the syntax Keys[...][...]
+	def self.[](first_key)
+		return KeyDial::KeyDialler.new(nil, first_key)
+	end
+
+	# Checks if a key is a valid numeric index, i.e. can be used in the syntax object[index]
+	#
+	# @param key The key to check.
+	#
+	# @return True if the key is a valid numeric index, otherwise false.
+	#
+	def self.index?(key)
+		return key.is_a?(Numeric) && key.respond_to?(:to_i)
+	end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: key_dial
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Convincible
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2019-01-09 00:00:00.000000000 Z
+date: 2019-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +52,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-nav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '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
@@ -63,17 +105,8 @@ 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/coercion.rb
 - lib/key_dial/key_dialler.rb
 - lib/key_dial/version.rb
 homepage: https://github.com/ConvincibleMedia/ruby-gem-key_dial
@@ -87,14 +120,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: 1.8.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.0
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: Access (deeply nested) Hash, Array or Struct keys. Get the value, or nil/default

data/.gitignore

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

data/.rspec

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

data/.travis.yml

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

data/Gemfile

@@ -1,6 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,82 +0,0 @@
-# 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

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

data/bin/console

@@ -1,14 +0,0 @@
-#!/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

@@ -1,8 +0,0 @@
-#!/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

@@ -1,29 +0,0 @@
-
-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