1
0
Fork 0
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 242dfda9c1 Travis: remove restriction on rubygems version
It appears that travis-ci/travis-ci#1793 was fixed by rubygems release v2.2.1.
2014-01-20 19:08:20 -05:00
lib Bump for release v1.1.2 2014-01-10 10:54:27 -05:00
spec (cosmetic: replace eligible double quoted strings with single quotes) 2013-11-26 15:53:45 -05:00
.coveralls.yml Fix coveralls config to be travis-ci 2013-07-06 16:03:00 -04:00
.gitignore Add setup for coveralls.io code coverage tool 2013-07-05 10:46:19 -04:00
.rspec Configure rspec to format as documentation, in color 2013-07-28 18:21:17 -04:00
.ruby-gemset Switched from .rvmrc to .ruby-version and .ruby-gemset 2013-06-29 18:41:23 -04:00
.ruby-version Add ruby-2.1.0 to Travis testing and .ruby-version 2013-12-30 10:18:54 -05:00
.travis.yml Travis: remove restriction on rubygems version 2014-01-20 19:08:20 -05:00
.yardopts minor change to .yardopts 2011-12-07 21:15:02 -05:00
docile.gemspec (cosmetic: replace eligible double quoted strings with single quotes) 2013-11-26 15:53:45 -05:00
Gemfile (cosmetic: replace eligible double quoted strings with single quotes) 2013-11-26 15:53:45 -05:00
HISTORY.md Update HISTORY.md for v1.1.2 2014-01-10 10:53:49 -05:00
LICENSE Update LICENSE to extend copyright to 2014 2014-01-10 10:57:42 -05:00
Rakefile (cosmetic: replace eligible double quoted strings with single quotes) 2013-11-26 15:53:45 -05:00
README.md Update README.md to extend copyright to 2014 2014-01-10 10:58:09 -05:00

Docile

Gem Version Build Status Dependency Status Code Climate Coverage Status Bitdeli Badge

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

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!

Advanced

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!

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 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!

Features

  1. Method lookup falls back from the DSL object to the block's context
  2. Local variable lookup falls back from the DSL object to the block's context
  3. Instance variables are from the block's context only
  4. Nested DSL evaluation, correctly chaining method and variable handling from the inner to the outer DSL scopes
  5. Alternatives for both imperative and functional styles of DSL objects

Installation

$ gem install docile

Status

Works on all ruby versions since 1.8.7.

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.

Copyright (c) 2012-2014 Marc Siegel. See LICENSE for details.