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:
parent
67756fa69e
commit
28daa260c2
1 changed files with 39 additions and 4 deletions
43
README.md
43
README.md
|
@ -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
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue