class Hashery::CRUDHash
The CRUDHash
is essentailly the same as the Hash
class, but it reduces the the set of necessary methods to the fundametal CRUD requirements. All other methods route through these CRUD methods. This is a better general design, although it is, of course, a little bit slower. The utility of this class becomes appearent when subclassing or delegating, as only a handful of methods need to be changed for all other methods to work accordingly.
In addition to the CRUD features, CRUDHash
supports a `#key_proc`, akin to `#default_proc`, that can be used to normalize keys.
The CRUD methods are:
-
key?
-
fetch
-
store
-
delete
In addition to these main methods, there are these supporting “CRUD” methods:
-
default
Constants
- NA
Dummy object for null arguments.
Public Class Methods
This method is overridden to ensure that new entries pass through the `#store` method.
hash - [#each] Single Hash
, associative array or just a list of pairs.
# File lib/hashery/crud_hash.rb, line 43 def self.[](*hash) h = new if hash.size == 1 hash.first.each do |k,v| h.store(k, v) end else hash.each do |(k,v)| h.store(k, v) end end h end
Alternate to new which auto-creates sub-dictionaries as needed. By default the `default_proc` procuced a empty Hash
and is self-referential so every such Hash
also has the same `default_proc`.
args - Pass-thru arguments to `#new`. block - Alternate internal procedure for default proc.
Examples
d = CRUDHash.auto d["a"]["b"]["c"] = "abc" #=> { "a"=>{"b"=>{"c"=>"abc"}}}
Returns `Hash`.
# File lib/hashery/crud_hash.rb, line 72 def self.auto(*args, &block) if block leet = lambda { |hsh, key| hsh[key] = block.call(hsh, key) } else leet = lambda { |hsh, key| hsh[key] = new(&leet) } end new(*args, &leet) end
Public Instance Methods
Update Hash
with assoc
.
assoc - Two-element `Array` or a `Hash`.
Returns assoc
.
# File lib/hashery/crud_hash.rb, line 214 def <<(assoc) case assoc when Hash update(assoc) when Array assoc.each_slice(2) do |(k,v)| store(k,v) end else raise ArgumentError # or TypeError ? end end
Operator for `#retrieve`.
key - Index key to lookup.
Returns `Object` value of key.
# File lib/hashery/crud_hash.rb, line 234 def [](key) retrieve(key) end
Operator for `#store`.
key - The `Object` to act as indexing key. value - The `Object` to associate with key.
Returns value
.
# File lib/hashery/crud_hash.rb, line 246 def []=(key,value) store(key,value) end
Allow `#default_proc` to take a block.
block - The `Proc` object to set the `default_proc`.
Returns `Proc`, the `default_proc`.
# File lib/hashery/crud_hash.rb, line 118 def default_proc(&block) self.default_proc = block if block super() end
Iterate over each hash pair.
# File lib/hashery/crud_hash.rb, line 286 def each #:yield: if block_given? keys.each do |k| yield(k, retrieve(k)) end else to_enum(:each) end end
CRUD method for read. This method gets the value for a given key. An error is raised if the key is not present, but an optional argument can be provided to be returned instead.
key - Hash
key to lookup. default - Value to return if key is not present.
Raises KeyError when key is not found and default has not been given.
Returns the `Object` that is the Hash
entry's value.
# File lib/hashery/crud_hash.rb, line 146 def fetch(key, *default) super(cast_key(key), *default) end
CRUD method for checking if key exists.
key - Hash
key to lookup.
Returns `true/false`.
# File lib/hashery/crud_hash.rb, line 130 def key?(key) super cast_key(key) end
Get/set `key_proc`.
Examples
ch = CRUDHash.new ch.key_proc
Returns `Proc`.
# File lib/hashery/crud_hash.rb, line 106 def key_proc(&block) @key_proc = block if block @key_proc end
Set `key_proc`.
Examples
ch = CRUDHash.new ch.key_proc = Proc.new{ |key| key.to_sym }
Returns `Proc`.
# File lib/hashery/crud_hash.rb, line 91 def key_proc=(proc) raise ArgumentError unless Proc === proc or NilClass === proc @key_proc = proc end
Method for reading value. Returns `nil` if key is not present.
Note that this method used to be the CRUD method instead of retrieve
. Complaints about read
being indicative of an IO object (though in my opinion that is a bad asumption) have led to this method's deprecation.
key - Hash
key to lookup.
Returns value of Hash
entry.
# File lib/hashery/crud_hash.rb, line 202 def read(key) warn "The #read method as been deprecated. Use #retrieve instead." retrieve(key) end
Replace current entries with those from another Hash
, or Hash-like object. Each entry is run through the casting procedure as it is added.
other - Hash-like object.
Returns self
.
# File lib/hashery/crud_hash.rb, line 325 def replace(other) super cast(other) end
Like fetch
but returns the results of calling `default_proc`, if defined, otherwise `default`.
key - Hash
key to lookup.
Returns value of Hash
entry or `nil`.
# File lib/hashery/crud_hash.rb, line 183 def retrieve(key) if key?(key) fetch(key) else default_proc ? default_proc.call(self, key) : default end end
CRUD method for create and update.
key - The `Object` to act as indexing key. value - The `Object` to associate with key.
Returns value
.
# File lib/hashery/crud_hash.rb, line 158 def store(key, value) super(cast_key(key), value) end
Convert CRUDHash
to regular Hash
.
TODO: Since a CRUDHash
is a subclass of Hash
should to_h
just `#dup`
insted of converting to traditional Hash?
Returns `Hash`.
Convert CRUDHash
to regular Hash
.
TODO: Since a CRUDHash
is a subclass of Hash
should to_hash
just `#dup`
insted of converting to traditional Hash?
# File lib/hashery/crud_hash.rb, line 345 def to_hash h = {}; each{ |k,v| h[k] = v }; h end
Update the Hash
with another hash.
other - Other hash or hash-like object to add to the hash.
Returns self
.
# File lib/hashery/crud_hash.rb, line 257 def update(other) other.each do |k,v| store(k, v) end self end
Get the values at.
keys - List of keys to lookup.
Returns `Array` of values.
# File lib/hashery/crud_hash.rb, line 336 def values_at(*keys) super *keys.map{ |key| cast_key(key) } end
Private Instance Methods
Cast a given `hash` in accordance to the `#key_proc`.
hash - Any object the responds to `#each` like a Hash
.
Returns `Hash`.
# File lib/hashery/crud_hash.rb, line 368 def cast(hash) h = {} hash.each do |k,v| h[cast_key(k)] = v end h end
Callback for normalizing hash keys.
key - Index key.
Returns key after passing through the `key_proc`.
# File lib/hashery/crud_hash.rb, line 383 def cast_key(key) @key_proc ? @key_proc.call(key) : key end