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:

In addition to these main methods, there are these supporting “CRUD” methods:

Constants

NA

Dummy object for null arguments.

Public Class Methods

[](*hash) click to toggle source

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
auto(*args, &block) click to toggle source

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

<<(assoc) click to toggle source

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
[](key) click to toggle source

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
[]=(key,value) click to toggle source

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
default_proc(&block) click to toggle source

Allow ‘#default_proc` to take a block.

block - The ‘Proc` object to set the `default_proc`.

Returns ‘Proc`, the `default_proc`.

Calls superclass method
# File lib/hashery/crud_hash.rb, line 118
def default_proc(&block)
  self.default_proc = block if block
  super()
end
delete(key) click to toggle source

CRUD method for delete.

key - Hash key to remove.

Returns value of deleted Hash entry.

Calls superclass method
# File lib/hashery/crud_hash.rb, line 169
def delete(key)
  super cast_key(key)
end
each() { || ... } click to toggle source

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
Also aliased as: each_pair
each_pair()

Alias for each.

Alias for: each
fetch(key, *default) click to toggle source

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.

Calls superclass method
# File lib/hashery/crud_hash.rb, line 146
def fetch(key, *default)
   super(cast_key(key), *default)
end
has_key?(key)

Alias for ‘#key?`.

Alias for: key?
include?(key)

Alias for ‘#key?`.

Alias for: key?
key?(key) click to toggle source

CRUD method for checking if key exists.

key - Hash key to lookup.

Returns ‘true/false`.

Calls superclass method
# File lib/hashery/crud_hash.rb, line 130
def key?(key)
  super cast_key(key)
end
Also aliased as: has_key?, member?, include?
key_proc(&block) click to toggle source

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
key_proc=(proc) click to toggle source

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
member?(key)

Alias for ‘#key?`.

Alias for: key?
merge(other) click to toggle source

Merge the Hash with another hash, returning a new Hash.

other - Other hash or hash-like object to add to the hash.

Returns ‘Hash`.

# File lib/hashery/crud_hash.rb, line 276
def merge(other)
  #super(other.rekey{ |key| cast_key(key) })
  copy = dup
  other.each{ |k,v| copy.store(k, v) }
  copy
end
merge!(other)

Alias for ‘#update`.

Alias for: update
read(key) click to toggle source

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(other) click to toggle source

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.

Calls superclass method
# File lib/hashery/crud_hash.rb, line 325
 def replace(other)
   super cast(other)
end
retrieve(key) click to toggle source

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
store(key, value) click to toggle source

CRUD method for create and update.

key - The ‘Object` to act as indexing key. value - The `Object` to associate with key.

Returns value.

Calls superclass method
# File lib/hashery/crud_hash.rb, line 158
def store(key, value)
  super(cast_key(key), value)
end
to_h()

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`.

Alias for: to_hash
to_hash() click to toggle source

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
Also aliased as: to_h
update(other) click to toggle source

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
Also aliased as: merge!
values_at(*keys) click to toggle source

Get the values at.

keys - List of keys to lookup.

Returns ‘Array` of values.

Calls superclass method
# File lib/hashery/crud_hash.rb, line 336
def values_at(*keys)
  super *keys.map{ |key| cast_key(key) }
end

Private Instance Methods

cast(hash) click to toggle source

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
cast_key(key) click to toggle source

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