https://github.com/ms-ati/docile

Docile keeps your Ruby DSLs tame and well-behaved
https://github.com/ms-ati/docile

Keywords

builder-pattern dsl immutability ruby

Keywords from Contributors

rubygems rspec rubocop test-coverage coverage-report coverage-library coverage code-quality debugger gem

Last synced: about 6 hours ago
JSON representation

Repository metadata

Docile keeps your Ruby DSLs tame and well-behaved

Host: GitHub
URL: https://github.com/ms-ati/docile
Owner: ms-ati
License: mit
Created: 2011-12-06T23:03:34.000Z (about 14 years ago)
Default Branch: main
Last Pushed: 2026-01-23T11:42:18.000Z (about 1 month ago)
Last Synced: 2026-02-12T18:50:46.302Z (18 days ago)
Topics: builder-pattern, dsl, immutability, ruby
Language: Ruby
Homepage: http://ms-ati.github.com/docile/
Size: 659 KB
Stars: 424
Watchers: 6
Forks: 34
Open Issues: 7
Releases: 0
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- License: LICENSE
- Security: SECURITY.md

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

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

Licensed under the MIT License,
see LICENSE for details.

Owner metadata

Name: Marc Siegel
Login: ms-ati
Email:
Kind: user
Description:
Website:
Location: Boston, MA
Twitter: ms_ati
Company: American Technology Innovations
Icon url: https://avatars.githubusercontent.com/u/592892?v=4
Repositories: 20
Last ynced at: 2023-04-09T05:56:24.644Z
Profile URL: https://github.com/ms-ati

GitHub Events

Total

Delete event: 5
Pull request event: 15
Fork event: 1
Watch event: 8
Issue comment event: 7
Push event: 6
Pull request review event: 1
Pull request review comment event: 1
Create event: 6

Last Year

Delete event: 4
Pull request event: 13
Fork event: 1
Watch event: 4
Issue comment event: 6
Push event: 6
Pull request review event: 1
Pull request review comment event: 1
Create event: 6

Committers metadata

Last synced: 2 days ago

Total Commits: 344
Total Committers: 24
Avg Commits per committer: 14.333
Development Distribution Score (DDS): 0.25

Commits in past year: 5
Committers in past year: 2
Avg Commits per committer in past year: 2.5
Development Distribution Score (DDS) in past year: 0.2

Name	Email	Commits
Marc Siegel	m**c@u**m	258
dependabot[bot]	4****]	17
Marc Siegel	m**l@t**m	16
Alexey Vasiliev	l**a@g**m	11
doop	d**d@g**m	9
Marc Siegel	m**l@u**m	7
Taichi Ishitani	t**0@g**m	7
Ken Dreyer	k**r@k**m	2
René Föhring	rf@b****e	2
Andrew Konchin	a**n@g**m	1
Andrew Meyer	a**i@g**m	1
Benoit Daloze	e**p@g**m	1
Bitdeli Chef	c**f@b**m	1
Christina Koller	c**2@g**m	1
Chun-wei Kuo	D**h@g**m	1
Hosam Aly	h**6@g**m	1
Igor Victor	g**a@y**u	1
Jochen Seeber	j**n@s**e	1
Mamoru TASAKA	m**a@f**g	1
Matt Schreiber	s**h@g**m	1
The Gitter Badger	b**r@g**m	1
Tobias Pfeiffer	p**b@g**m	1
Xavier Nayrac	x**c@g**m	1
Zsolt Kozaroczy	k**a@g**m	1

Committer domains:

Issue and Pull Request metadata

Last synced: about 1 month ago

Total issues: 25
Total pull requests: 113
Average time to close issues: 5 months
Average time to close pull requests: about 2 months
Total issue authors: 15
Total pull request authors: 22
Average comments per issue: 4.32
Average comments per pull request: 1.5
Merged pull request: 79
Bot issues: 0
Bot pull requests: 42

Past year issues: 0
Past year pull requests: 9
Past year average time to close issues: N/A
Past year average time to close pull requests: 19 days
Past year issue authors: 0
Past year pull request authors: 2
Past year average comments per issue: 0
Past year average comments per pull request: 0.67
Past year merged pull request: 0
Past year bot issues: 0
Past year bot pull requests: 8

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/ms-ati/docile

Top Issue Authors

ms-ati (7)
taichi-ishitani (5)
robkinyon (1)
lohqua (1)
OrelSokolov (1)
Ajedi32 (1)
jochenseeber (1)
michaeldiscala (1)
adrianthedev (1)
PragTob (1)
mtasaka (1)
coolo (1)
srghma (1)
manther (1)
Paul-Bob (1)

Top Pull Request Authors

dependabot[bot] (42)
ms-ati (35)
taichi-ishitani (10)
ktdreyer (2)
eregon (2)
rrrene (2)
mtasaka (2)
jochenseeber (2)
kiskoza (2)
ms-tg (2)
andrykonchin (1)
dslh (1)
bitdeli-chef (1)
Domon (1)
tomeon (1)

Top Issue Labels

CI (3)
Bug (2)
2.0 (2)

Top Pull Request Labels

dependencies (41)
github_actions (41)

Package metadata

Total packages: 14
Total downloads:
- rubygems: 903,603,919 total
Total docker downloads: 6,684,110,174
Total dependent packages: 71 (may contain duplicates)
Total dependent repositories: 70,869 (may contain duplicates)
Total versions: 83
Total maintainers: 1

gem.coop: docile

Docile treats the methods of a given ruby object as a DSL (domain specific language) within a given block. Killer feature: you can also reference methods, instance variables, and local variables from the original (non-DSL) context within the block. Docile releases follow Semantic Versioning as defined at semver.org.

Homepage: https://ms-ati.github.io/docile/
Documentation: http://www.rubydoc.info/gems/docile/
Licenses: MIT
Latest release: 1.4.1 (published over 1 year ago)
Last Synced: 2026-03-02T08:31:03.653Z (about 18 hours ago)
Versions: 24
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 451,732,422 Total
Docker Downloads: 3,342,055,087
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.02%
- Docker downloads count: 0.028%
- Downloads: 0.051%
Maintainers (1)
- ms_ati

rubygems.org: docile

Homepage: https://ms-ati.github.io/docile/
Documentation: http://www.rubydoc.info/gems/docile/
Licenses: MIT
Latest release: 1.4.1 (published over 1 year ago)
Last Synced: 2026-03-02T18:03:06.746Z (about 9 hours ago)
Versions: 24
Dependent Packages: 71
Dependent Repositories: 70,869
Downloads: 451,871,497 Total
Docker Downloads: 3,342,055,087
Rankings:
- Downloads: 0.055%
- Docker downloads count: 0.072%
- Dependent repos count: 0.137%
- Dependent packages count: 0.413%
- Average: 1.369%
- Stargazers count: 2.816%
- Forks count: 4.72%
Maintainers (1)
- ms_ati

proxy.golang.org: github.com/ms-ati/docile

Homepage:
Documentation: https://pkg.go.dev/github.com/ms-ati/docile#section-documentation
Licenses: mit
Latest release: v1.4.1 (published over 1 year ago)
Last Synced: 2026-02-28T20:00:51.820Z (2 days ago)
Versions: 24
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent packages count: 6.515%
- Average: 6.733%
- Dependent repos count: 6.952%

debian-10: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Documentation: https://packages.debian.org/buster/ruby-docile
Licenses:
Latest release: 1.1.5-2 (published 20 days ago)
Last Synced: 2026-02-13T04:20:44.385Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-20.04: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Licenses:
Latest release: 1.1.5-2 (published 18 days ago)
Last Synced: 2026-02-13T07:12:38.253Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-23.10: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Licenses:
Latest release: 1.1.5-2.1 (published 17 days ago)
Last Synced: 2026-02-13T18:18:13.738Z (17 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-23.04: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Licenses:
Latest release: 1.1.5-2.1 (published 20 days ago)
Last Synced: 2026-02-11T06:38:15.531Z (20 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-24.10: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Licenses:
Latest release: 1.1.5-2.1 (published 21 days ago)
Last Synced: 2026-02-09T16:26:55.541Z (21 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

debian-11: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Documentation: https://packages.debian.org/bullseye/ruby-docile
Licenses:
Latest release: 1.1.5-2 (published 20 days ago)
Last Synced: 2026-02-13T08:19:49.293Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

guix: ruby-docile

Ruby EDSL helper library

Homepage: https://ms-ati.github.io/docile/
Documentation: https://git.savannah.gnu.org/cgit/guix.git/tree/gnu/packages/ruby-check.scm#n458
Licenses: expat
Latest release: 1.1.5 (published about 8 hours ago)
Last Synced: 2026-03-02T19:00:28.741Z (about 8 hours ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

debian-13: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Documentation: https://packages.debian.org/trixie/ruby-docile
Licenses: mit
Latest release: 1.1.5-2.1 (published 19 days ago)
Last Synced: 2026-02-13T13:14:52.445Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-22.04: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Licenses:
Latest release: 1.1.5-2 (published 18 days ago)
Last Synced: 2026-02-13T13:15:50.546Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

debian-12: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Documentation: https://packages.debian.org/bookworm/ruby-docile
Licenses:
Latest release: 1.1.5-2.1 (published 18 days ago)
Last Synced: 2026-02-12T23:28:22.079Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-24.04: ruby-docile

Homepage: http://ms-ati.github.com/docile/
Licenses:
Latest release: 1.1.5-2.1 (published 24 days ago)
Last Synced: 2026-02-06T15:04:28.307Z (24 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

Dependencies

Gemfile rubygems

panolint >= 0 development
rspec ~> 3.10 development
simplecov >= 0 development
simplecov-cobertura >= 0 development
rake >= 0

.github/workflows/main.yml actions

actions/checkout v3.0.2 composite
codecov/codecov-action v3.1.0 composite
ruby/setup-ruby v1 composite

docile.gemspec rubygems

Score: 31.993968219211506