11 KiB
Docile
Ruby makes it possible to create very expressive Domain Specific Languages, or DSL's for short. However, it requires some deep knowledge and somewhat hairy meta-programming to get the interface just right.
"Docile" means Ready to accept control or instruction; submissive [1]
Instead of each Ruby project reinventing this wheel, let's make our Ruby DSL coding a bit more docile...
Usage
Basic: Ruby Array as DSL
Let's say that we want to make a DSL for modifying Array objects. Wouldn't it be great if we could just treat the methods of Array as a DSL?
with_array([]) do
push 1
push 2
pop
push 3
end
#=> [1, 3]
No problem, just define the method with_array like this:
def with_array(arr=[], &block)
Docile.dsl_eval(arr, &block)
end
Easy!
Next step: Allow helper methods to call DSL methods
What if, in our use of the methods of Array as a DSL, we want to extract helper methods which in turn call DSL methods?
def pop_sum_and_push(n)
sum = 0
n.times { sum += pop }
push sum
end
Docile.dsl_eval([]) do
push 5
push 6
pop_sum_and_push(2)
end
#=> [11]
Without Docile, you may find this sort of code extraction to be more challenging.
Wait! Can't I do that with just instance_eval or instance_exec?
Good question!
In short: No.
Not if you want the code in the block to be able to refer to anything the block would normally have access to from the surrounding context.
Let's be very specific. Docile internally uses instance_exec (see execution.rb#26), adding a small layer to support referencing local variables, instance variables, and methods from the block's context or the target object's context, interchangeably. This is "the hard part", where most folks making a DSL in Ruby throw up their hands.
For example:
class ContextOfBlock
def example_of_contexts
@block_instance_var = 1
block_local_var = 2
with_array do
push @block_instance_var
push block_local_var
pop
push block_sees_this_method
end
end
def block_sees_this_method
3
end
def with_array(&block)
{
docile: Docile.dsl_eval([], &block),
instance_eval: ([].instance_eval(&block) rescue $!),
instance_exec: ([].instance_exec(&block) rescue $!)
}
end
end
ContextOfBlock.new.example_of_contexts
#=> {
:docile=>[1, 3],
:instance_eval=>#<NameError: undefined local variable or method `block_sees_this_method' for [nil]:Array>,
:instance_exec=>#<NameError: undefined local variable or method `block_sees_this_method' for [nil]:Array>
}
As you can see, it won't be possible to call methods or access instance variables defined in the block's context using just the raw instance_eval or instance_exec methods. And in fact, Docile goes further, making it easy to maintain this support even in multi-layered DSLs.
Build a Pizza
Mutating (changing) an Array instance is fine, but what usually makes a good DSL is a Builder Pattern.
For example, let's say you want a DSL to specify how you want to build a Pizza:
@sauce_level = :extra
pizza do
cheese
pepperoni
sauce @sauce_level
end
#=> #<Pizza:0x00001009dc398 @cheese=true, @pepperoni=true, @bacon=false, @sauce=:extra>
And let's say we have a PizzaBuilder, which builds a Pizza like this:
Pizza = Struct.new(:cheese, :pepperoni, :bacon, :sauce)
class PizzaBuilder
def cheese(v=true); @cheese = v; self; end
def pepperoni(v=true); @pepperoni = v; self; end
def bacon(v=true); @bacon = v; self; end
def sauce(v=nil); @sauce = v; self; end
def build
Pizza.new(!!@cheese, !!@pepperoni, !!@bacon, @sauce)
end
end
PizzaBuilder.new.cheese.pepperoni.sauce(:extra).build
#=> #<Pizza:0x00001009dc398 @cheese=true, @pepperoni=true, @bacon=false, @sauce=:extra>
Then implement your DSL like this:
def pizza(&block)
Docile.dsl_eval(PizzaBuilder.new, &block).build
end
It's just that easy!
Multi-level and Recursive DSLs
Docile is a very easy way to write a multi-level DSL in Ruby, even for a recursive data structure such as a tree:
Person = Struct.new(:name, :mother, :father)
person {
name 'John Smith'
mother {
name 'Mary Smith'
}
father {
name 'Tom Smith'
mother {
name 'Jane Smith'
}
}
}
#=> #<struct Person name="John Smith",
# mother=#<struct Person name="Mary Smith", mother=nil, father=nil>,
# father=#<struct Person name="Tom Smith",
# mother=#<struct Person name="Jane Smith", mother=nil, father=nil>,
# father=nil>>
See the full person tree example for details.
Block parameters
Parameters can be passed to the DSL block.
Supposing you want to make some sort of cheap Sinatra knockoff:
@last_request = nil
respond '/path' do |request|
puts "Request received: #{request}"
@last_request = request
end
def ride bike
# Play with your new bike
end
respond '/new_bike' do |bike|
ride(bike)
end
You'd put together a dispatcher something like this:
require 'singleton'
class DispatchScope
def a_method_you_can_call_from_inside_the_block
:useful_huh?
end
end
class MessageDispatch
include Singleton
def initialize
@responders = {}
end
def add_responder path, &block
@responders[path] = block
end
def dispatch path, request
Docile.dsl_eval(DispatchScope.new, request, &@responders[path])
end
end
def respond path, &handler
MessageDispatch.instance.add_responder path, handler
end
def send_request path, request
MessageDispatch.instance.dispatch path, request
end
Functional-Style Immutable DSL Objects
Sometimes, you want to use an object as a DSL, but it doesn't quite fit the imperative pattern shown above.
Instead of methods like Array#push, which modifies the object at hand, it has methods like String#reverse, which returns a new object without touching the original. Perhaps it's even frozen in order to enforce immutability.
Wouldn't it be great if we could just treat these methods as a DSL as well?
s = "I'm immutable!".freeze
with_immutable_string(s) do
reverse
upcase
end
#=> "!ELBATUMMI M'I"
s
#=> "I'm immutable!"
No problem, just define the method with_immutable_string like this:
def with_immutable_string(str="", &block)
Docile.dsl_eval_immutable(str, &block)
end
All set!
Accessing the block's return value
Sometimes you might want to access the return value of your provided block,
as opposed to the DSL object itself. In these cases, use
dsl_eval_with_block_return. It behaves exactly like dsl_eval, but returns
the output from executing the block, rather than the DSL object.
arr = []
with_array(arr) do
push "a"
push "b"
push "c"
length
end
#=> 3
arr
#=> ["a", "b", "c"]
def with_array(arr=[], &block)
Docile.dsl_eval_with_block_return(arr, &block)
end
Features
- Method lookup falls back from the DSL object to the block's context
- Local variable lookup falls back from the DSL object to the block's context
- Instance variables are from the block's context only
- Nested DSL evaluation, correctly chaining method and variable handling from the inner to the outer DSL scopes
- Alternatives for both imperative and functional styles of DSL objects
Installation
$ gem install docile
Links
Status
Works on all currently supported ruby versions, or so Github Actions tells us.
Used by some pretty cool gems to implement their DSLs, notably including SimpleCov. Keep an eye out for new gems using Docile at the Ruby Toolbox.
Release Policy
Docile releases follow Semantic Versioning 2.0.0.
Note on Patches/Pull Requests
- Fork the project.
- Setup your development environment with:
gem install bundler; bundle install - Make your feature addition or bug fix.
- Add tests for it. This is important so I don't break it in a future version unintentionally.
- Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
- Send me a pull request. Bonus points for topic branches.
Releasing
To make a new release of Docile to
RubyGems, first install the release
dependencies (e.g. rake) as follows:
bundle config set --local with 'release'
bundle install
Then carry out these steps:
-
Update
HISTORY.md:- Add an entry for the upcoming version x.y.z
- Move content from Unreleased to the upcoming version x.y.z
- Commit with title
Update HISTORY.md for x.y.z
-
Update
lib/docile/version.rb- Replace with upcoming version x.y.z
- Commit with title
Bump version to x.y.z
-
bundle exec rake release
Copyright & License
Copyright (c) 2012-2021 Marc Siegel.
Licensed under the MIT License, see LICENSE for details.