From 61209169b454ce11455091f087a61de61c48e28d Mon Sep 17 00:00:00 2001 From: Jean-Francis Bastien Date: Mon, 17 Sep 2018 16:22:51 -0400 Subject: Updated README.md SymbolizeKeys and Keywords argument behavior. --- CHANGELOG.md | 1 + README.md | 14 ++++++++++---- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a2b2c37..e26ffec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,7 @@ scheme are considered to be bugs. * [#459](https://github.com/intridea/hashie/pull/459): Fixed a regression in `Mash.load` that disallowed aliases - [@arekt](https://github.com/arekt) and [@michaelherold](https://github.com/michaelherold). * [#465](https://github.com/intridea/hashie/pull/465): Fixed `deep_update` to call any readers when a key exists - [@laertispappas](https://github.com/laertispappas). * [#479](https://github.com/intridea/hashie/pull/479): Fixed an issue with `Hash#except` not returning a `Mash` in Rails 6 - [@bobbymcwho](https://github.com/bobbymcwho). +* [#489](https://github.com/intridea/hashie/pull/489): Updated the documentation to exlain the behavior of `Mash` and keyword arguments - [@Bhacaz](https://github.com/Bhacaz). * Your contribution here. ### Security diff --git a/README.md b/README.md index be94965..57b4616 100644 --- a/README.md +++ b/README.md @@ -190,7 +190,7 @@ end ### KeyConversion -The KeyConversion extension gives you the convenience methods of `symbolize_keys` and `stringify_keys` along with their bang counterparts. You can also include just stringify or just symbolize with `Hashie::Extensions::StringifyKeys` or `Hashie::Extensions::SymbolizeKeys`. +The KeyConversion extension gives you the convenience methods of `symbolize_keys` and `stringify_keys` along with their bang counterparts. You can also include just stringify or just symbolize with `Hashie::Extensions::StringifyKeys` or [`Hashie::Extensions::SymbolizeKeys`](#mash-extension-symbolizekeys). Hashie also has a utility method for converting keys on a Hash without a mixin: @@ -674,9 +674,9 @@ safe_mash.zip = 'Test' # => ArgumentError safe_mash[:zip] = 'test' # => still ArgumentError ``` -### Mash Extension:: SymbolizeKeys +### Mash Extension: SymbolizeKeys -This extension can be mixed into a Mash to change the default behavior of converting keys to strings. After mixing this extension into a Mash, the Mash will convert all keys to symbols. +This extension can be mixed into a Mash to change the default behavior of converting keys to strings. After mixing this extension into a Mash, the Mash will convert all keys to symbols. It can be useful to use with keywords argument, which required symbol keys. ```ruby class SymbolizedMash < ::Hashie::Mash @@ -687,6 +687,12 @@ symbol_mash = SymbolizedMash.new symbol_mash['test'] = 'value' symbol_mash.test #=> 'value' symbol_mash.to_h #=> {test: 'value'} + +def example(test:) + puts test +end + +example(symbol_mash) #=> value ``` There is a major benefit and coupled with a major trade-off to this decision (at least on older Rubies). As a benefit, by using symbols as keys, you will be able to use the implicit conversion of a Mash via the `#to_hash` method to destructure (or splat) the contents of a Mash out to a block. This can be handy for doing iterations through the Mash's keys and values, as follows: @@ -701,7 +707,7 @@ end However, on Rubies less than 2.0, this means that every key you send to the Mash will generate a symbol. Since symbols are not garbage-collected on older versions of Ruby, this can cause a slow memory leak when using a symbolized Mash with data generated from user input. -### Mash Extension:: DefineAccessors +### Mash Extension: DefineAccessors This extension can be mixed into a Mash so it makes it behave like `OpenStruct`. It reduces the overhead of `method_missing?` magic by lazily defining field accessors when they're requested. -- cgit v1.2.1