Allow options on Mash.load (#474)

`Mash.load` uses the Ruby standard library to load Yaml-serialized files
into a Mash. The original implementation used `YAML.load` for this
purpose. However, that method is inherently unsafe so we switched to
using `YAML.safe_load`.

Safely loading Yaml files has many different domain-specific
configuration flags that we did not, by default, expose. This change
introduces the ability to configure the safe loading of Yaml files so
that all types of Yaml can be loaded when necessary using the flags from
the standard library.

This implementation preserves the backwards-compatibility with the prior
implementation so that it should not require updates from users of the
current `Mash.load` behavior. For those who this change affects, we
included upgrading documentation to ease the transition.

1 files changed, 35 insertions, 0 deletions

diff --git a/UPGRADING.md b/UPGRADING.md
index 5a9f05a..6c8ac93 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -1,6 +1,41 @@
 Upgrading Hashie
 ================
 
+### Upgrading to 3.7.0
+
+#### Mash#load takes options
+
+The `Hashie::Mash#load` method now accepts options, changing the interface of `Parser#initialize`. If you have a custom parser, you must update its `initialize` method.
+
+For example, `Hashie::Extensions::Parsers::YamlErbParser` now accepts `whitelist_classes`, `whitelist_symbols` and `aliases` options.
+
+Before:
+
+```ruby
+class Hashie::Extensions::Parsers::YamlErbParser
+  def initialize(file_path)
+    @file_path = file_path
+  end
+end
+```
+
+After:
+
+```ruby
+class Hashie::Extensions::Parsers::YamlErbParser
+  def initialize(file_path, options = {})
+    @file_path = file_path
+    @options = options
+  end
+end
+```
+
+Options can now be passed into `Mash#load`.
+
+```ruby
+Mash.load(filename, whitelist_classes: [])
+```
+
 ### Upgrading to 3.5.2
 
 #### Disable logging in Mash subclasses