Class: Hashie::Mash

Inherits:
Hash
  • Object
show all
Includes:
Extensions::PrettyInspect
Defined in:
lib/hashie/mash.rb

Overview

Mash allows you to create pseudo-objects that have method-like accessors for hash keys. This is useful for such implementations as an API-accessing library that wants to fake robust objects without the overhead of actually doing so. Think of it as OpenStruct with some additional goodies.

A Mash will look at the methods you pass it and perform operations based on the following rules:

  • No punctuation: Returns the value of the hash for that key, or nil if none exists.
  • Assignment (=): Sets the attribute of the given method name.
  • Existence (?): Returns true or false depending on whether that key has been set.
  • Bang (!): Forces the existence of this key, used for deep Mashes. Think of it as “touch” for mashes.
  • Under Bang (_): Like Bang, but returns a new Mash rather than creating a key. Used to test existance in deep Mashes.

mash = Mash.new mash.name? # => false mash.name = “Bob” mash.name # => “Bob” mash.name? # => true

hash = }, :f => , 12} mash = Mash.new(hash) mash.a.b # => 23 mash.a.d.e # => “abc” mash.f.first.g # => 44 mash.f.last # => 12

mash = Mash.new mash.author # => nil mash.author! # =>

REXML could not parse this XML/HTML: 
<Mash>

mash = Mash.new mash.author!.name = “Michael Bleigh” mash.author # =>

REXML could not parse this XML/HTML: 
<Mash name="Michael Bleigh">

mash = Mash.new mash.author # => nil mash.author_ # =>

REXML could not parse this XML/HTML: 
<Mash>
  mash.author_.name # => nil

mash = Mash.new mash.author_.name = “Michael Bleigh” (assigned to temp object) mash.author # =>

REXML could not parse this XML/HTML: 
<Mash>

Constant Summary

ALLOWED_SUFFIXES =
%w(? ! = _)
SUFFIXES_PARSER =
/(.*?)([#{ALLOWED_SUFFIXES.join}]?)$/

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Extensions::PrettyInspect

#hashie_inspect, included

Methods inherited from Hash

#to_hash, #to_json, #to_mash

Methods included from Extensions::StringifyKeys

#stringify_keys, #stringify_keys!

Constructor Details

- (Mash) initialize(source_hash = nil, default = nil, &blk)

If you pass in an existing hash, it will convert it to a Mash including recursively descending into arrays and hashes, converting them as well.



88
89
90
91
# File 'lib/hashie/mash.rb', line 88

def initialize(source_hash = nil, default = nil, &blk)
  deep_update(source_hash) if source_hash
  default ? super(default) : super(&blk)
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

- (Object) method_missing(method_name, *args, &blk)



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
# File 'lib/hashie/mash.rb', line 235

def method_missing(method_name, *args, &blk)
  return self.[](method_name, &blk) if key?(method_name)
  name, suffix = method_suffix(method_name)
  case suffix
  when '='
    assign_property(name, args.first)
  when '?'
    !!self[name]
  when '!'
    initializing_reader(name)
  when '_'
    underbang_reader(name)
  else
    default(method_name)
  end
end

Class Method Details

+ (Object) load(path, options = {})



63
64
65
66
67
68
69
70
71
# File 'lib/hashie/mash.rb', line 63

def self.load(path, options = {})
  @_mashes ||= new do |h, file_path|
    fail ArgumentError, "The following file doesn't exist: #{file_path}" unless File.file?(file_path)

    parser = options.fetch(:parser) {  Hashie::Extensions::Parsers::YamlErbParser }
    h[file_path] = new(parser.perform(file_path)).freeze
  end
  @_mashes[path]
end

Instance Method Details

- (Object) assign_property(name, value)

Assigns a value to a key



195
196
197
# File 'lib/hashie/mash.rb', line 195

def assign_property(name, value)
  self[name] = value
end

- (Object) custom_reader(key) {|value| ... } Also known as: []

Retrieves an attribute set in the Mash. Will convert any key passed in to a string before retrieving.

Yields:

  • (value)


108
109
110
111
112
# File 'lib/hashie/mash.rb', line 108

def custom_reader(key)
  value = regular_reader(convert_key(key))
  yield value if block_given?
  value
end

- (Object) custom_writer(key, value, convert = true) Also known as: []=

Sets an attribute in the Mash. Key will be converted to a string before it is set, and Hashes will be converted into Mashes for nesting purposes.



117
118
119
# File 'lib/hashie/mash.rb', line 117

def custom_writer(key, value, convert = true) #:nodoc:
  regular_writer(convert_key(key), convert ? convert_value(value) : value)
end

- (Object) deep_merge(other_hash, &blk) Also known as: merge

Performs a deep_update on a duplicate of the current mash.



170
171
172
# File 'lib/hashie/mash.rb', line 170

def deep_merge(other_hash, &blk)
  dup.deep_update(other_hash, &blk)
end

- (Object) deep_update(other_hash, &blk) Also known as: deep_merge!, update

Recursively merges this mash with the passed in hash, merging each hash in the hierarchy.



177
178
179
180
181
182
183
184
185
186
187
188
189
# File 'lib/hashie/mash.rb', line 177

def deep_update(other_hash, &blk)
  other_hash.each_pair do |k, v|
    key = convert_key(k)
    if regular_reader(key).is_a?(Mash) && v.is_a?(::Hash)
      custom_reader(key).deep_update(v, &blk)
    else
      value = convert_value(v, true)
      value = convert_value(blk.call(key, self[k], value), true) if blk && self.key?(k)
      custom_writer(key, value, false)
    end
  end
  self
end

- (Object) delete(key)



147
148
149
# File 'lib/hashie/mash.rb', line 147

def delete(key)
  super(convert_key(key))
end

- (Object) dup

Duplicates the current mash as a new mash.



157
158
159
# File 'lib/hashie/mash.rb', line 157

def dup
  self.class.new(self, default)
end

- (Object) fetch(key, *args)



143
144
145
# File 'lib/hashie/mash.rb', line 143

def fetch(key, *args)
  super(convert_key(key), *args)
end

- (Object) id



95
96
97
# File 'lib/hashie/mash.rb', line 95

def id #:nodoc:
  self['id']
end

- (Object) initializing_reader(key)

This is the bang method reader, it will return a new Mash if there isn’t a value already assigned to the key requested.



126
127
128
129
130
# File 'lib/hashie/mash.rb', line 126

def initializing_reader(key)
  ck = convert_key(key)
  regular_writer(ck, self.class.new) unless key?(ck)
  regular_reader(ck)
end

- (Boolean) key?(key) Also known as: has_key?, include?, member?



161
162
163
# File 'lib/hashie/mash.rb', line 161

def key?(key)
  super(convert_key(key))
end

- (Boolean) prefix_method?(method_name)



230
231
232
233
# File 'lib/hashie/mash.rb', line 230

def prefix_method?(method_name)
  method_name = method_name.to_s
  method_name.end_with?(*ALLOWED_SUFFIXES) && key?(method_name.chop)
end

- (Object) regular_dup



155
# File 'lib/hashie/mash.rb', line 155

alias_method :regular_dup, :dup

- (Object) replace(other_hash)



213
214
215
216
217
# File 'lib/hashie/mash.rb', line 213

def replace(other_hash)
  (keys - other_hash.keys).each { |key| delete(key) }
  other_hash.each { |key, value| self[key] = value }
  self
end

- (Boolean) respond_to_missing?(method_name, *args)



219
220
221
222
223
224
225
226
227
228
# File 'lib/hashie/mash.rb', line 219

def respond_to_missing?(method_name, *args)
  return true if key?(method_name)
  _, suffix = method_suffix(method_name)
  case suffix
  when '=', '?', '!', '_'
    return true
  else
    super
  end
end

- (Object) shallow_merge(other_hash)

Performs a shallow_update on a duplicate of the current mash



200
201
202
# File 'lib/hashie/mash.rb', line 200

def shallow_merge(other_hash)
  dup.shallow_update(other_hash)
end

- (Object) shallow_update(other_hash)

Merges (non-recursively) the hash from the argument, changing the receiving hash



206
207
208
209
210
211
# File 'lib/hashie/mash.rb', line 206

def shallow_update(other_hash)
  other_hash.each_pair do |k, v|
    regular_writer(convert_key(k), convert_value(v, true))
  end
  self
end

- (Object) to_module(mash_method_name = :settings)



73
74
75
76
77
78
79
80
# File 'lib/hashie/mash.rb', line 73

def to_module(mash_method_name = :settings)
  mash = self
  Module.new do |m|
    m.send :define_method, mash_method_name.to_sym do
      mash
    end
  end
end

- (Object) type



99
100
101
# File 'lib/hashie/mash.rb', line 99

def type #:nodoc:
  self['type']
end

- (Object) underbang_reader(key)

This is the under bang method reader, it will return a temporary new Mash if there isn’t a value already assigned to the key requested.



134
135
136
137
138
139
140
141
# File 'lib/hashie/mash.rb', line 134

def underbang_reader(key)
  ck = convert_key(key)
  if key?(ck)
    regular_reader(ck)
  else
    self.class.new
  end
end

- (Object) values_at(*keys)



151
152
153
# File 'lib/hashie/mash.rb', line 151

def values_at(*keys)
  super(*keys.map { |key| convert_key(key) })
end