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

Docile keeps your Ruby DSLs tame and well-behaved

Find a file

Marc Siegel 88bb18a596 reformat api documentation comment Signed-off-by: Marc Siegel <marc@usainnov.com>		2012-10-29 15:24:37 -04:00
lib	reformat api documentation comment	2012-10-29 15:24:37 -04:00
spec	fix names of two tests	2011-12-06 19:06:55 -05:00
.gitignore	yard rake task	2011-12-06 14:31:22 -05:00
.travis.yml	allow travis failures for 1.8.x and jruby until fixed	2012-10-28 08:34:25 -04:00
.yardopts	minor change to .yardopts	2011-12-07 21:15:02 -05:00
docile.gemspec	add rake as a gem dependency for travis	2012-10-28 08:25:52 -04:00
Gemfile	initial commit	2011-12-06 13:51:56 -05:00
LICENSE	first stab at documentation	2011-12-06 18:03:18 -05:00
Rakefile	add default rake task for travis	2012-10-28 08:25:28 -04:00
README.md	update README with 1.0 plans	2012-10-28 13:23:46 -04:00

README.md

Docile

Definition: Ready to accept control or instruction; submissive [1]

Tired of overly complex DSL libraries and hairy meta-programming?

Let's make our Ruby DSLs more docile...

Usage

Let's treat an Array's methods as its own DSL:

Docile.dsl_eval([]) do
  push 1
  push 2
  pop
  push 3
end
#=> [1, 3]

Mutating (changing) the array is fine, but what you probably really want as your DSL is actually a Builder Pattern.

For example, if you have a PizzaBuilder class that can already build a Pizza:

@sauce_level = :extra
pizza = PizzaBuilder.new.cheese.pepperoni.sauce(@sauce_level).build
#=> #<Pizza:0x00001009dc398 @cheese=true, @pepperoni=true, @bacon=false, @sauce=:extra>

Then you can use this same PizzaBuilder class as a DSL:

@sauce_level = :extra
pizza = Docile.dsl_eval(PizzaBuilder.new) do
  cheese
  pepperoni
  sauce @sauce_level
end.build
#=> #<Pizza:0x00001009dc398 @cheese=true, @pepperoni=true, @bacon=false, @sauce=:extra>

It's just that easy!

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

Installation

$ gem install docile

Documentation

Documentation hosted on rubydoc.info: Docile Documentation

Or, read the code hosted on github.com: Docile Code

Status

A 1.0 release is coming soon! Just as soon as everything is working on ruby 1.8.7 (and jruby + rubinius in 1.8 mode)...

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.