docile 0.9.0

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg
+.idea
+doc
+.yardoc

data/.yardopts

@@ -0,0 +1,7 @@
+--title 'Docile Documentation'
+
+--no-private
+--hide-void-return
+
+--markup-provider=redcarpet
+--markup=markdown

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in docile.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 Marc Siegel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,75 @@
+# 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*...
+
+[1]: http://www.google.com/search?q=docile+definition   "Google"
+
+## Usage
+
+Let's treat an Array's methods as its own DSL:
+
+``` ruby
+Docile.dsl_eval [] do
+  push 1
+  push 2
+end
+#=> [1, 3]
+```
+
+Mutating (changing) the array is fine, but what you probably really want as your DSL is actually a [Builder Pattern][2].
+
+For example, if you have a PizzaBuilder class that can build a pizza:
+
+``` ruby
+@sauce_level = :extra
+pizza = PizzaBuilder.new.cheese.pepperoni.bacon.sauce(@sauce_level).build
+```
+
+Then you can use this PizzaBuilder class as a DSL:
+
+``` ruby
+@sauce_level = :extra
+pizza = Docile.dsl_eval PizzaBuilder.new do
+  cheese
+  pepperoni
+  bacon
+  sauce @sauce_level
+end.build
+```
+
+[2]: http://stackoverflow.com/questions/328496/when-would-you-use-the-builder-pattern  "Builder Pattern"
+
+## 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
+
+## Installation
+
+``` bash
+$ gem install docile
+```
+
+## Documentation
+
+Documentation hosted on *rubydoc.info*: [Docile Documentation](http://rubydoc.info/gems/docile)
+Or, read the code hosted on *github.com*: [Docile Code](https://github.com/ms-ati/docile)
+
+## 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
+
+Copyright (c) 2011 Marc Siegel. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "github/markup"
+require "redcarpet"
+require "yard"
+require "yard/rake/yardoc_task"
+
+YARD::Rake::YardocTask.new do |t|
+  OTHER_PATHS = %w()
+  t.files   = ['lib/**/*.rb', OTHER_PATHS]
+  t.options = %w(--markup-provider=redcarpet --markup=markdown)
+end

data/docile.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "docile/version"
+
+Gem::Specification.new do |s|
+  s.name        = "docile"
+  s.version     = Docile::VERSION
+  s.authors     = ["Marc Siegel"]
+  s.email       = ["msiegel@usainnov.com"]
+  s.homepage    = "http://docile.github.com"
+  s.summary     = "Docile keeps your Ruby DSL's tame and well-behaved"
+  s.description = "Docile turns any Ruby object into a DSL. Especially useful with the Builder pattern."
+
+  s.rubyforge_project = "docile"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec", "~> 2.7.0"
+
+  # Github flavored markdown in YARD documentation
+  # http://blog.nikosd.com/2011/11/github-flavored-markdown-in-yard.html
+  s.add_development_dependency "yard"
+  s.add_development_dependency "redcarpet"
+  s.add_development_dependency "github-markup"
+end

data/lib/docile.rb

@@ -0,0 +1,31 @@
+require "docile/version"
+require "docile/fallback_context_proxy"
+
+module Docile
+  # Executes a block in the context of an object whose interface represents a DSL.
+  #
+  # Example of using an Array as a DSL:
+  #   Docile.dsl_eval [] do
+  #     push 1
+  #     push 2
+  #     pop
+  #     push 3
+  #   end
+  #   #=> [1, 3]
+  #
+  # @param dsl [Object]  an object whose methods represent a DSL
+  # @param block [Proc]  a block to execute in the DSL context
+  # @return    [Object]  the dsl object, after execution of the block
+  def dsl_eval(dsl, &block)
+    block_context = eval("self", block.binding)
+    proxy_context = FallbackContextProxy.new(dsl, block_context)
+    begin
+      block_context.instance_variables.each { |ivar| proxy_context.instance_variable_set(ivar, block_context.instance_variable_get(ivar)) }
+      proxy_context.instance_eval(&block)
+    ensure
+      block_context.instance_variables.each { |ivar| block_context.instance_variable_set(ivar, proxy_context.instance_variable_get(ivar)) }
+    end
+    dsl
+  end
+  module_function :dsl_eval
+end

data/lib/docile/fallback_context_proxy.rb

@@ -0,0 +1,52 @@
+require 'set'
+
+module Docile
+  class FallbackContextProxy
+    NON_PROXIED_METHODS = Set[:object_id, :__send__, :__id__, :==, :equal?, :"!", :"!=", :instance_eval,
+                              :instance_variables, :instance_variable_get, :instance_variable_set,
+                              :remove_instance_variable]
+
+    NON_PROXIED_INSTANCE_VARIABLES = Set[:@__receiver__, :@__fallback__]
+
+    instance_methods.each do |method|
+      unless NON_PROXIED_METHODS.include?(method.to_sym)
+        undef_method(method)
+      end
+    end
+
+    def initialize(receiver, fallback)
+      @__receiver__ = receiver
+      @__fallback__ = fallback
+    end
+
+    def id
+      @__receiver__.__send__(:id)
+    end
+
+    # Special case due to `Kernel#sub`'s existence
+    def sub(*args, &block)
+      __proxy_method__(:sub, *args, &block)
+    end
+
+    # Special case to allow proxy instance variables
+    def instance_variables
+      super - NON_PROXIED_INSTANCE_VARIABLES.to_a
+    end
+
+    def method_missing(method, *args, &block)
+      __proxy_method__(method, *args, &block)
+    end
+
+    def __proxy_method__(method, *args, &block)
+      begin
+        @__receiver__.__send__(method.to_sym, *args, &block)
+      rescue ::NoMethodError => e
+        begin
+          @__fallback__.__send__(method.to_sym, *args, &block)
+        rescue ::NoMethodError
+          raise(e)
+        end
+      end
+    end
+  end
+end

data/lib/docile/version.rb

@@ -0,0 +1,3 @@
+module Docile
+  VERSION = "0.9.0"
+end

data/spec/docile_spec.rb

@@ -0,0 +1,94 @@
+require "spec_helper"
+
+describe Docile do
+
+  context :dsl_eval do
+
+    class InnerDSL
+      def initialize; @b = 'b'; end
+      attr_accessor :b
+    end
+
+    class OuterDSL
+      def initialize; @a = 'a'; end
+      attr_accessor :a
+      def inner(&block)
+        Docile.dsl_eval(InnerDSL.new, &block)
+      end
+    end
+
+    def outer(&block)
+      Docile.dsl_eval(OuterDSL.new, &block)
+    end
+
+    it "should return the DSL object" do
+      Docile.dsl_eval([]) do
+        push 1
+        push 2
+        pop
+        push 3
+      end.should == [1, 3]
+    end
+
+    context "methods" do
+      it "should find method of outer dsl in outer dsl scope" do
+        outer { a.should == 'a' }
+      end
+
+      it "should find method of inner dsl in inner dsl scope" do
+        outer { inner { b.should == 'b' } }
+      end
+
+      it "should find method of outer dsl in inner dsl scope" do
+        outer { inner { a.should == 'a' } }
+      end
+
+      it "should find method of block's context in outer dsl scope" do
+        def c; 'c'; end
+        outer { c.should == 'c' }
+      end
+
+      it "should find method of block's context in inner dsl scope" do
+        def c; 'c'; end
+        outer { inner { c.should == 'c' } }
+      end
+
+      it "should find method of outer dsl in preference to block context" do
+        def a; 'not a'; end
+        outer { a.should == 'a' }
+      end
+    end
+
+    context "local variables" do
+      it "should find local variable from block context in outer dsl scope" do
+        foo = 'foo'
+        outer { foo.should == 'foo' }
+      end
+
+      it "should find local variable from block definition in inner dsl scope" do
+        bar = 'bar'
+        outer { inner { bar.should == 'bar' } }
+      end
+    end
+
+    context "instance variables" do
+      it "should find instance variable from block definition in outer dsl scope" do
+        @iv1 = 'iv1'; outer { @iv1.should == 'iv1' }
+      end
+
+      it "should write instance variable assigned in block into outer dsl scope" do
+        @iv1 = 'foo'; outer { @iv1 = 'bar' }; @iv1.should == 'bar'
+      end
+
+      it "should find instance variable from block definition in inner dsl scope" do
+        @iv2 = 'iv2'; outer { inner { @iv2.should == 'iv2' } }
+      end
+
+      it "should find instance variable from block definition in inner dsl scope" do
+        @iv2 = 'foo'; outer { inner { @iv2 = 'bar' } }; @iv2.should == 'bar'
+      end
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'rspec'
+
+test_dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift test_dir unless $LOAD_PATH.include?(test_dir)
+
+lib_dir = File.join(File.dirname(test_dir), 'lib')
+$LOAD_PATH.unshift lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+require 'docile'

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification 
+name: docile
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.9.0
+platform: ruby
+authors: 
+- Marc Siegel
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-12-06 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.7.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: redcarpet
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: github-markup
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+description: Docile turns any Ruby object into a DSL. Especially useful with the Builder pattern.
+email: 
+- msiegel@usainnov.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .yardopts
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- docile.gemspec
+- lib/docile.rb
+- lib/docile/fallback_context_proxy.rb
+- lib/docile/version.rb
+- spec/docile_spec.rb
+- spec/spec_helper.rb
+homepage: http://docile.github.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: docile
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Docile keeps your Ruby DSL's tame and well-behaved
+test_files: 
+- spec/docile_spec.rb
+- spec/spec_helper.rb
+has_rdoc: