Skip to content

Latest commit

 

History

History
109 lines (70 loc) · 3.86 KB

UPGRADING.md

File metadata and controls

109 lines (70 loc) · 3.86 KB
Raw

Upgrading Hashie

Upgrading to 3.2.1

Possible coercion changes

The improvements made to coercions in version 3.2.1 issue #200 do not break the documented API, but are significant enough that changes may effect undocumented side-effects. Applications that depended on those side-effects will need to be updated.

Change: Type coercion no longer creates new objects if the input matches the target type. Previously coerced properties always resulted in the creation of a new object, even when it wasn't necessary. This had the effect of a dup or clone on coerced properties but not uncoerced ones.

If necessary, dup or clone your own objects. Do not assume Hashie will do it for you.

Change: Failed coercion attempts now raise Hashie::CoercionError.

Hashie now raises a Hashie::CoercionError that details on the property that could not be coerced, the source and target type of the coercion, and the internal error. Previously only the internal error was raised.

Applications that were attempting to rescuing the internal errors should be updated to rescue Hashie::CoercionError instead.

Upgrading to 3.0

Compatibility with Rails 4 Strong Parameters

Version 2.1 introduced support to prevent default Rails 4 mass-assignment protection behavior. This was issue #89, resolved in #104. In version 2.2 this behavior has been removed in #147 in favor of a mixin and finally extracted into a separate gem in Hashie 3.0.

To enable 2.1 compatible behavior with Rails 4, use the hashie_rails gem.

gem 'hashie_rails'

See #154 and Mash and Rails 4 Strong Parameters for more details.

Key Conversions in Hashie::Dash and Hashie::Trash

Version 2.1 and older of Hashie::Dash and Hashie::Trash converted keys to strings by default. This is no longer the case in 2.2.

Consider the following code.

class Person < Hashie::Dash
  property :name
end

p = Person.new(name: 'dB.')

Version 2.1 behaves as follows.

p.name # => 'dB.'
p[:name] # => 'dB.'
p['name'] # => 'dB.'

# not what I put in
p.inspect # => { 'name' => 'dB.' }
p.to_hash # => { 'name' => 'dB.' }

It was not possible to achieve the behavior of preserving keys, as described in issue #151.

Version 2.2 does not perform this conversion by default.

p.name # => 'dB.'
p[:name] # => 'dB.'
# p['name'] # => NoMethodError

p.inspect # => { :name => 'dB.' }
p.to_hash # => { :name => 'dB.' }

To enable behavior compatible with older versions, use Hashie::Extensions::Dash::IndifferentAccess.

class Person < Hashie::Dash
  include Hashie::Extensions::Dash::IndifferentAccess
  property :name
end

Key Conversions in Hashie::Hash#to_hash

Version 2.1 or older of Hash#to_hash converted keys to strings automatically.

instance = Hashie::Hash[first: 'First', 'last' => 'Last']
instance.to_hash # => { "first" => 'First', "last" => 'Last' }

It was possible to symbolize keys by passing :symbolize_keys, however it was not possible to retrieve the hash with initial key values.

instance.to_hash(symbolize_keys: true) # => { :first => 'First', :last => 'Last' }
instance.to_hash(stringify_keys: true) # => { "first" => 'First', "last" => 'Last' }

Version 2.2 no longer converts keys by default.

instance = Hashie::Hash[first: 'First', 'last' => 'Last']
instance.to_hash # => { :first => 'First', "last" => 'Last' }

The behavior with symbolize_keys and stringify_keys is unchanged.

See #152 for more information.