1
0
Fork 0
mirror of https://github.com/ms-ati/docile synced 2023-03-27 23:21:52 -04:00

Add documentation to README about #dsl_eval_immutable

This commit is contained in:
Marc Siegel 2013-07-29 00:37:03 -04:00
parent 67756fa69e
commit 28daa260c2

View file

@ -28,12 +28,12 @@ with_array([]) do
pop pop
push 3 push 3
end end
# => [1, 3] #=> [1, 3]
``` ```
No problem, just define the method `with_array` like this: No problem, just define the method `with_array` like this:
``` ruby ```ruby
def with_array(arr=[], &block) def with_array(arr=[], &block)
Docile.dsl_eval(arr, &block) Docile.dsl_eval(arr, &block)
end end
@ -55,7 +55,7 @@ pizza do
pepperoni pepperoni
sauce @sauce_level sauce @sauce_level
end end
# => #<Pizza:0x00001009dc398 @cheese=true, @pepperoni=true, @bacon=false, @sauce=:extra> #=> #<Pizza:0x00001009dc398 @cheese=true, @pepperoni=true, @bacon=false, @sauce=:extra>
``` ```
And let's say we have a PizzaBuilder, which builds a Pizza like this: And let's say we have a PizzaBuilder, which builds a Pizza like this:
@ -85,7 +85,7 @@ def pizza(&block)
end end
``` ```
It's just that easy! It's just that easy!
[2]: http://stackoverflow.com/questions/328496/when-would-you-use-the-builder-pattern "Builder Pattern" [2]: http://stackoverflow.com/questions/328496/when-would-you-use-the-builder-pattern "Builder Pattern"
@ -149,6 +149,40 @@ end
[3]: http://www.sinatrarb.com "Sinatra" [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 ## Features
1. Method lookup falls back from the DSL object to the block's context 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 3. Instance variables are from the block's context only
4. Nested DSL evaluation, correctly chaining method and variable handling 4. Nested DSL evaluation, correctly chaining method and variable handling
from the inner to the outer DSL scopes from the inner to the outer DSL scopes
5. Alternatives for both imperative and functional styles of DSL objects
## Installation ## Installation