Add documentation to README about #dsl_eval_immutable

README.md

@@ -149,6 +149,40 @@ end
 
 [3]: http://www.sinatrarb.com "Sinatra"
 
+## Functional-Style DSL Objects
+
+Sometimes, you want to use an object as a DSL, but it doesn't quite fit the
+[imperative](http://en.wikipedia.org/wiki/Imperative_programming) pattern shown
+above.
+
+Instead of methods like
+[Array#push](http://www.ruby-doc.org/core-2.0/Array.html#method-i-push), which
+modifies the object at hand, it has methods like
+[String#reverse](http://www.ruby-doc.org/core-2.0/String.html#method-i-reverse),
+which returns a new object without touching the original. Perhaps it's even
+[frozen](http://www.ruby-doc.org/core-2.0/Object.html#method-i-freeze) in
+order to enforce [immutability](http://en.wikipedia.org/wiki/Immutable_object).
+
+Wouldn't it be great if we could just treat these methods as a DSL as well?
+
+```ruby
+with_immutable_string("I'm immutable!".freeze) do
+  reverse
+  upcase
+end
+#=> "!ELBATUMMI M'I"
+```
+
+No problem, just define the method `with_immutable_string` like this:
+
+```ruby
+def with_immutable_string(str="", &block)
+  Docile.dsl_eval_immutable(str, &block)
+end
+```
+
+All set!
+
 ## Features
 
   1.  Method lookup falls back from the DSL object to the block's context
@@ -157,6 +191,7 @@ end
   3.  Instance variables are from the block's context only
   4.  Nested DSL evaluation, correctly chaining method and variable handling
         from the inner to the outer DSL scopes
+  5.  Alternatives for both imperative and functional styles of DSL objects
 
 ## Installation