Class: Hashie::Mash
- 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.
== Basic Example
mash = Mash.new mash.name? # => false mash.name = "Bob" mash.name # => "Bob" mash.name? # => true
== Hash Conversion Example
hash = => {:b => 23, :d => {:e => "abc"}, :f => [=> 44, :h => 29, 12]} mash = Mash.new(hash) mash.a.b # => 23 mash.a.d.e # => "abc" mash.f.first.g # => 44 mash.f.last # => 12
== Bang Example
mash = Mash.new
mash.author # => nil
mash.author! # =>
mash = Mash.new
mash.author!.name = "Michael Bleigh"
mash.author # =>
== Under Bang Example
mash = Mash.new
mash.author # => nil
mash.author_ # =>
mash = Mash.new
mash.author_.name = "Michael Bleigh" (assigned to temp object)
mash.author # =>
Constant Summary collapse
- ALLOWED_SUFFIXES =
%w(? ! = _)
Class Method Summary collapse
Instance Method Summary collapse
-
#assign_property(name, value) ⇒ Object
Assigns a value to a key.
-
#custom_reader(key) {|value| ... } ⇒ Object
(also: #[])
Retrieves an attribute set in the Mash.
-
#custom_writer(key, value, convert = true) ⇒ Object
(also: #[]=)
Sets an attribute in the Mash.
-
#deep_merge(other_hash, &blk) ⇒ Object
(also: #merge)
Performs a deep_update on a duplicate of the current mash.
-
#deep_update(other_hash, &blk) ⇒ Object
(also: #deep_merge!, #update)
Recursively merges this mash with the passed in hash, merging each hash in the hierarchy.
- #delete(key) ⇒ Object
-
#dup ⇒ Object
Duplicates the current mash as a new mash.
- #fetch(key, *args) ⇒ Object
-
#id ⇒ Object
:nodoc:.
-
#initialize(source_hash = nil, default = nil, &blk) ⇒ Mash
constructor
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.
-
#initializing_reader(key) ⇒ Object
This is the bang method reader, it will return a new Mash if there isn't a value already assigned to the key requested.
- #key?(key) ⇒ Boolean (also: #has_key?, #include?, #member?)
- #method_missing(method_name, *args, &blk) ⇒ Object
- #prefix_method?(method_name) ⇒ Boolean
- #regular_dup ⇒ Object
- #replace(other_hash) ⇒ Object
- #respond_to_missing?(method_name, *args) ⇒ Boolean
-
#shallow_merge(other_hash) ⇒ Object
Performs a shallow_update on a duplicate of the current mash.
-
#shallow_update(other_hash) ⇒ Object
Merges (non-recursively) the hash from the argument, changing the receiving hash.
- #to_module(mash_method_name = :settings) ⇒ Object
-
#type ⇒ Object
:nodoc:.
-
#underbang_reader(key) ⇒ Object
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.
- #values_at(*keys) ⇒ Object
Methods included from Extensions::PrettyInspect
Methods inherited from Hash
Methods included from Extensions::StringifyKeys
#stringify_keys, #stringify_keys!
Constructor Details
#initialize(source_hash = nil, default = nil, &blk) ⇒ Mash
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.
87 88 89 90 |
# File 'lib/hashie/mash.rb', line 87 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
#method_missing(method_name, *args, &blk) ⇒ Object
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 |
# File 'lib/hashie/mash.rb', line 234 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
.load(path, options = {}) ⇒ Object
62 63 64 65 66 67 68 69 70 |
# File 'lib/hashie/mash.rb', line 62 def self.load(path, = {}) @_mashes ||= new do |h, file_path| fail ArgumentError, "The following file doesn't exist: #{file_path}" unless File.file?(file_path) parser = .fetch(:parser) { Hashie::Extensions::Parsers::YamlErbParser } h[file_path] = new(parser.perform(file_path)).freeze end @_mashes[path] end |
Instance Method Details
#assign_property(name, value) ⇒ Object
Assigns a value to a key
194 195 196 |
# File 'lib/hashie/mash.rb', line 194 def assign_property(name, value) self[name] = value end |
#custom_reader(key) {|value| ... } ⇒ Object Also known as: []
Retrieves an attribute set in the Mash. Will convert any key passed in to a string before retrieving.
107 108 109 110 111 |
# File 'lib/hashie/mash.rb', line 107 def custom_reader(key) value = regular_reader(convert_key(key)) yield value if block_given? value end |
#custom_writer(key, value, convert = true) ⇒ Object 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.
116 117 118 |
# File 'lib/hashie/mash.rb', line 116 def custom_writer(key, value, convert = true) #:nodoc: regular_writer(convert_key(key), convert ? convert_value(value) : value) end |
#deep_merge(other_hash, &blk) ⇒ Object Also known as: merge
Performs a deep_update on a duplicate of the current mash.
169 170 171 |
# File 'lib/hashie/mash.rb', line 169 def deep_merge(other_hash, &blk) dup.deep_update(other_hash, &blk) end |
#deep_update(other_hash, &blk) ⇒ Object Also known as: deep_merge!, update
Recursively merges this mash with the passed in hash, merging each hash in the hierarchy.
176 177 178 179 180 181 182 183 184 185 186 187 188 |
# File 'lib/hashie/mash.rb', line 176 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 custom_writer(key, value, false) end end self end |
#delete(key) ⇒ Object
146 147 148 |
# File 'lib/hashie/mash.rb', line 146 def delete(key) super(convert_key(key)) end |
#dup ⇒ Object
Duplicates the current mash as a new mash.
156 157 158 |
# File 'lib/hashie/mash.rb', line 156 def dup self.class.new(self, default) end |
#fetch(key, *args) ⇒ Object
142 143 144 |
# File 'lib/hashie/mash.rb', line 142 def fetch(key, *args) super(convert_key(key), *args) end |
#id ⇒ Object
:nodoc:
94 95 96 |
# File 'lib/hashie/mash.rb', line 94 def id #:nodoc: self['id'] end |
#initializing_reader(key) ⇒ Object
This is the bang method reader, it will return a new Mash if there isn't a value already assigned to the key requested.
125 126 127 128 129 |
# File 'lib/hashie/mash.rb', line 125 def initializing_reader(key) ck = convert_key(key) regular_writer(ck, self.class.new) unless key?(ck) regular_reader(ck) end |
#key?(key) ⇒ Boolean Also known as: has_key?, include?, member?
160 161 162 |
# File 'lib/hashie/mash.rb', line 160 def key?(key) super(convert_key(key)) end |
#prefix_method?(method_name) ⇒ Boolean
229 230 231 232 |
# File 'lib/hashie/mash.rb', line 229 def prefix_method?(method_name) method_name = method_name.to_s method_name.end_with?(*ALLOWED_SUFFIXES) && key?(method_name.chop) end |
#regular_dup ⇒ Object
154 |
# File 'lib/hashie/mash.rb', line 154 alias_method :regular_dup, :dup |
#replace(other_hash) ⇒ Object
212 213 214 215 216 |
# File 'lib/hashie/mash.rb', line 212 def replace(other_hash) (keys - other_hash.keys).each { |key| delete(key) } other_hash.each { |key, value| self[key] = value } self end |
#respond_to_missing?(method_name, *args) ⇒ Boolean
218 219 220 221 222 223 224 225 226 227 |
# File 'lib/hashie/mash.rb', line 218 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 |
#shallow_merge(other_hash) ⇒ Object
Performs a shallow_update on a duplicate of the current mash
199 200 201 |
# File 'lib/hashie/mash.rb', line 199 def shallow_merge(other_hash) dup.shallow_update(other_hash) end |
#shallow_update(other_hash) ⇒ Object
Merges (non-recursively) the hash from the argument, changing the receiving hash
205 206 207 208 209 210 |
# File 'lib/hashie/mash.rb', line 205 def shallow_update(other_hash) other_hash.each_pair do |k, v| regular_writer(convert_key(k), convert_value(v, true)) end self end |
#to_module(mash_method_name = :settings) ⇒ Object
72 73 74 75 76 77 78 79 |
# File 'lib/hashie/mash.rb', line 72 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 |
#type ⇒ Object
:nodoc:
98 99 100 |
# File 'lib/hashie/mash.rb', line 98 def type #:nodoc: self['type'] end |
#underbang_reader(key) ⇒ Object
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.
133 134 135 136 137 138 139 140 |
# File 'lib/hashie/mash.rb', line 133 def underbang_reader(key) ck = convert_key(key) if key?(ck) regular_reader(ck) else self.class.new end end |
#values_at(*keys) ⇒ Object
150 151 152 |
# File 'lib/hashie/mash.rb', line 150 def values_at(*keys) super(*keys.map { |key| convert_key(key) }) end |