README.md in messages_dictionary-2.0.0 vs README.md in messages_dictionary-2.1.0

@@ -33,14 +33,12 @@
 * [Messages are stored in a single file](https://github.com/bodrovis/lessons_indexer/blob/master/lib/lessons_indexer/messages/messages.yml)
 * [Messenger class equipped with messages_dictionary magic is defined](https://github.com/bodrovis/lessons_indexer/blob/master/lib/lessons_indexer.rb#L7)
 * [Other classes simply inherit from it](https://github.com/bodrovis/lessons_indexer/blob/master/lib/lessons_indexer/indexer.rb#L2)
 * [Messages are fetched easily](https://github.com/bodrovis/lessons_indexer/blob/master/lib/lessons_indexer/indexer.rb#L45)
 
-## Usage
+## Basic usage
 
-### Basic Example
-
 Suppose you have the following program:
 
 ```ruby
 class MyClass
   def calculate(a)
@@ -84,11 +82,11 @@
   end
 
   def greet
     pretty_output(:welcome)
     # Or simply
-    pou(:welcome)
+    pou :welcome
   end
 end
 ```
 
 The only thing you have to do is create two *.yml* files named after your classes:
@@ -154,13 +152,13 @@
     pou('show_result', result: result)
   end
 end
 ```
 
-### Further Customization
+## Further Customization
 
-#### Specifying File Name and Directory
+### Specifying File Name and Directory
 
 By default `messages_dictionary` will search for a *.yml* file named after your class (converted to snake case,
 so for the `MyClass` the file should be named *my_class.yml*)
 inside the same directory. However, this behavior can be easily changed with the following options:
 
@@ -168,18 +166,34 @@
 * `:dir` (`string`) - specifies the directory to load file from.
 
 ```ruby
 class MyClass
   include MessagesDictionary
-  has_messages_dictionary file: 'some_file.yml', dir: 'C:\my_docs'
+  has_messages_dictionary file: 'some_file.yml', dir: 'my_docs'
 end
 ```
 
 Both of these options are not mandatory.
 
-#### Specifying Messages Hash
+### Providing a custom file loader
 
+By default the gem a messages file in YAML format. However, you might want to use a different format: for example, JSON. In this case you'll have to provide a custom loader:
+
+```ruby
+class MyClass
+  include MessagesDictionary
+  has_messages_dictionary file: 'test_file.json', dir: 'my_dir',
+                          file_loader: ->(file_path) { JSON.parse(File.read(file_path)) }
+end
+```
+
+The `:file_loader` option accepts a proc or a lambda that receives a path to your messages file as an argument. This lambda must return a hash object with keys and the corresponding values.
+
+The default value for the `:file_loader` is `->(f) { YAML.load_file(f) }`.
+
+### Specifying Messages Hash
+
 Instead of loading messages from a file, you can pass hash to the `has_messages_dictionary` using `:messages` option:
 
 ```ruby
 class MyClass
   include MessagesDictionary
@@ -187,11 +201,11 @@
 end
 ```
 
 Nesting and all other features are supported as well.
 
-#### Specifying Output and Display Method
+### Specifying Output and Display Method
 
 By default all messages will be outputted to `STDOUT` using `puts` method, however this can be changed:
 
 * `:output` (`object`) - specify your own output. The object you provide has to implement `puts` method
 or any other method you provide for the `:method` option.
@@ -202,12 +216,37 @@
   include MessagesDictionary
   has_messages_dictionary output: STDOUT, method: :warn
 end
 ```
 
-#### Providing Custom Transformation Logic
+### "Lazy" mode
 
+By default this gem will load all messages from the given file. However, you can enable a "lazy" mode so that messages are not loaded until `pou` or `pretty_output` methods have been called. The "lazy" mode can only be enabled when the `:file` option is provided (in other words, `:lazy` has no effect with the `:messages` setting):
+
+```ruby
+class MyClass
+  include MessagesDictionary
+  has_messages_dictionary lazy: true, file: 'my_file.yml'
+
+  def greet
+    pou :hi
+  end
+end
+
+# At this point no messages are loaded from the given file
+
+obj = MyClass.new
+
+# ... doing some other stuff ...
+
+# Messages are still not loaded at this point!
+
+obj.greet # Now all messages will be loaded from the YAML file
+```
+
+### Providing Custom Transformation Logic
+
 Suppose you want to transform your message somehow or even simply return it instead of printing on the screen.
 `pretty_output` method accepts an optional block for this purpose:
 
 ```ruby
 class MyClass
@@ -259,9 +298,48 @@
   pou(:welcome) do |msg|
     puts msg.upcase # => Prints "WELCOME"
   end
 end
 ```
+
+### Handling missing keys
+
+By default when a non-existent key is requested, an error will be raised:
+
+```ruby
+class MyClass
+  include MessagesDictionary
+  has_messages_dictionary messages: {key: 'value'}
+
+  def greet
+    pou :unknown_key # trying to use some unknown key...
+  end
+end
+
+obj = MyClass.new
+
+obj.greet # KeyError is raised here!
+```
+
+However, you can adjust the `:on_key_missing` option and provide a custom proc or lambda to handle all missing keys:
+
+```ruby
+class MyClass
+  include MessagesDictionary
+  has_messages_dictionary messages: {key: 'value'},
+                          on_key_missing: ->(key) { key } # We simply return the requested key itself
+
+  def greet
+    pou :unknown_key
+  end
+end
+
+obj = MyClass.new
+
+obj.greet # Prints "unknown_key" to the screen, no errors will be raised
+```
+
+So, in the example above we simply return the key itself if it was not found in the messages hash.
 
 ## License
 
 Licensed under the [MIT License](https://github.com/bodrovis-learning/messages_dictionary/blob/master/LICENSE).