docile 1.2.0 → 1.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: efc3f0539f1c253fdc8487bcc23f671e8c74fab5
-  data.tar.gz: 4a6ff57d636604f406e6d19ca27b6fce30110d9f
+SHA256:
+  metadata.gz: 3ecef57f8977694d10721b6f18ece9744d03288b21e67d8fd8a4d3bca2837a57
+  data.tar.gz: e10ccdb31a0ffeb6fca27bb1f54250fd0c0a881afa70d2eac58145b05616a820
 SHA512:
-  metadata.gz: 410b86373972c31e31811dad9dc257501be169d43484023f98a54f63ff1a9c61cc5ac5974aaea384e4373a93eeab763f1f5d7db80803f2d605581963f19c9f4c
-  data.tar.gz: 84dd464b50e7d368c198570370233e8ea1c2fef17e1d114a0b1798a302c0bf7126ff38bfe1a53d6a2e1609f524e689ae6b9233af7c9b5bca6978f0f68fd817e0
+  metadata.gz: 0f8331a837ca968790f87bb9cdcc213d35da6c5973f4d9dcb56a604849c476c8d99d20dcdc921388389aed85f3b7eb2894eabcb90abfd42a1f1214817a631264
+  data.tar.gz: cffe4f42680621637b3103607a96c5511712f0d298c30401e04bfce08997a702fdcc5f965b8737e8531f12d330612ada1887818f93e109facfaaac215eb9243c

data/.travis.yml

@@ -1,37 +1,43 @@
 language: ruby
 
-# Apparently sudo is required to test on Rubinius and JRuby-head
-sudo: required
-
-# See https://docs.travis-ci.com/user/languages/ruby/#Rubinius
-dist: trusty
+branches:
+  only:
+    - master
 
 rvm:
   # MRI
   - ruby-head
+  - 2.7
+  - 2.6
+  - 2.5
   - 2.4
   - 2.3
   - 2.2
   - 2.1
-  - 2.0
-  - 1.9.2 # allowed to fail until Travis binary for this is fixed
   - 1.9.3
-  - 1.8.7
+  - 1.8.7	
   - ree
   # JRuby
   - jruby-head
-  - jruby-9.1 # allowed to fail due to https://github.com/travis-ci/travis-ci/issues/9049
-  - jruby-9.0
-  - jruby-19mode
-  - jruby-18mode
-  # Rubinius
-  - rubinius-3
+  - jruby-9.2
+  # Truffleruby
+  - truffleruby-head
+  - truffleruby-20.3.0
 
-matrix:
+jobs:
   allow_failures:
     - rvm: ruby-head
-    - rvm: 1.9.2 # See build error https://travis-ci.org/tcrayford/Values/jobs/202728857
     - rvm: jruby-head
-    - rvm: jruby-9.1 # See build error https://travis-ci.org/ms-ati/docile/jobs/327830706
-    - rvm: rubinius-3
+    - rvm: truffleruby-head
+    # NOTE (2020-12-18): Failing access to Rubygems with following error:
+    #   Unable to download data from https://rubygems.org/ - hostname was not
+    #   match with the server certificate (https://rubygems.org/specs.4.8.gz)
+    #
+    #   See Travis CI topic here:
+    #   https://travis-ci.community/t/ruby-1-8-7-and-ree-builds-broken-by-ssl-certificate-failure/10866
+    #
+    # TODO (2020-12-18): Either find a fix or remove testing of 1.8 versions
+    - rvm: 1.8.7
+    - rvm: ree
+
   fast_finish: true

data/Gemfile

@@ -1,10 +1,10 @@
-require File.expand_path('on_what', File.dirname(__FILE__))
-source 'https://rubygems.org'
+require File.expand_path("on_what", File.dirname(__FILE__))
+source "https://rubygems.org"
 
 # Travis-only dependencies go here
-if on_travis? && !on_1_8?
+if on_travis? && !on_less_than_2_3? && !on_rubinius?
   group :test do
-    gem 'codecov', '>= 0.0.9', :require => false
+    gem "codecov", ">= 0.0.9", :require => false
   end
 end
 

data/HISTORY.md

@@ -1,6 +1,36 @@
 # HISTORY
 
-## [Unreleased changes](http://github.com/ms-ati/docile/compare/v1.2.0...master)
+## [Unreleased changes](http://github.com/ms-ati/docile/compare/v1.3.4...master)
+
+  - ...
+
+## [v1.3.4 (Dec 22, 2020)](http://github.com/ms-ati/docile/compare/v1.3.3...v1.3.4)
+
+- Special thanks to Benoit Daloze (@eregon):
+    - Fix delegation on Ruby 2.7 (issues #45 and #44, PR #52)
+
+## [v1.3.3 (Dec 18, 2020)](http://github.com/ms-ati/docile/compare/v1.3.2...v1.3.3)
+
+- Special thanks (again!) to Taichi Ishitani (@taichi-ishitani):
+    - Fix keyword arg warnings on Ruby 2.7 (issue #44, PR #45)
+    - Filter Docile's source files from backtrace (issue #35, PR #36)
+
+## [v1.3.2 (Jun 12, 2019)](http://github.com/ms-ati/docile/compare/v1.3.1...v1.3.2)
+
+  - Special thanks (again!) to Taichi Ishitani (@taichi-ishitani):
+    - Fix for DSL object is replaced when #dsl_eval is nested (#33, PR #34)
+
+## [v1.3.1 (May 24, 2018)](http://github.com/ms-ati/docile/compare/v1.3.0...v1.3.1)
+
+  - Special thanks to Taichi Ishitani (@taichi-ishitani):
+    - Fix for when DSL object is also the block's context (#30)
+
+## [v1.3.0 (Feb 7, 2018)](http://github.com/ms-ati/docile/compare/v1.2.0...v1.3.0)
+
+  - Allow helper methods in block's context to call DSL methods
+  - Add SemVer release policy explicitly
+  - Standardize on double-quoted string literals
+  - Workaround some more Travis CI shenanigans
 
 ## [v1.2.0 (Jan 11, 2018)](http://github.com/ms-ati/docile/compare/v1.1.5...v1.2.0)
 

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2012-2018 Marc Siegel
+Copyright (c) 2012-2021 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

data/README.md

@@ -8,9 +8,8 @@
 [![Docs Coverage](http://inch-ci.org/github/ms-ati/docile.png)](http://inch-ci.org/github/ms-ati/docile)
 
 [![Build Status](https://img.shields.io/travis/ms-ati/docile/master.svg)](https://travis-ci.org/ms-ati/docile)
-[![Dependency Status](https://gemnasium.com/ms-ati/docile.svg)](https://gemnasium.com/ms-ati/docile)
-[![Code Climate](https://img.shields.io/codeclimate/github/ms-ati/docile.svg)](https://codeclimate.com/github/ms-ati/docile)
 [![Code Coverage](https://img.shields.io/codecov/c/github/ms-ati/docile.svg)](https://codecov.io/github/ms-ati/docile)
+[![Maintainability](https://api.codeclimate.com/v1/badges/79ca631bc123f7b83b34/maintainability)](https://codeclimate.com/github/ms-ati/docile/maintainability)
 
 Ruby makes it possible to create very expressive **Domain Specific
 Languages**, or **DSL**'s for short. However, it requires some deep knowledge and
@@ -48,13 +47,41 @@ def with_array(arr=[], &block)
 end
 ```
 
-**Easy!**
+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?
+
+```ruby
+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!
 
-Let's be very specific. Docile internally uses `instance_exec` (see [execution.rb#25](lib/docile/execution.rb#L25)), 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.
+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](lib/docile/execution.rb#L26)), 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:
 
@@ -328,6 +355,10 @@ Works on [all ruby versions since 1.8.7](https://github.com/ms-ati/docile/blob/m
 
 Used by some pretty cool gems to implement their DSLs, notably including [SimpleCov](https://github.com/colszowka/simplecov). Keep an eye out for new gems using Docile at the [Ruby Toolbox](https://www.ruby-toolbox.com/projects/docile).
 
+## Release Policy
+
+Docile releases follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+
 ## Note on Patches/Pull Requests
 
   * Fork the project.
@@ -343,7 +374,7 @@ Used by some pretty cool gems to implement their DSLs, notably including [Simple
 
 ## Copyright & License
 
-Copyright (c) 2012-2018 Marc Siegel.
+Copyright (c) 2012-2021 Marc Siegel.
 
 Licensed under the [MIT License](http://choosealicense.com/licenses/mit/), see [LICENSE](LICENSE) for details.
 

data/Rakefile

@@ -1,7 +1,7 @@
-require 'rake/clean'
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require File.expand_path('on_what', File.dirname(__FILE__))
+require "rake/clean"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require File.expand_path("on_what", File.dirname(__FILE__))
 
 # Default task for `rake` is to run rspec
 task :default => [:spec]
@@ -10,19 +10,19 @@ task :default => [:spec]
 RSpec::Core::RakeTask.new
 
 # Configure `rake clobber` to delete all generated files
-CLOBBER.include('pkg', 'doc', 'coverage')
+CLOBBER.include("pkg", "doc", "coverage")
 
 # To limit needed compatibility with versions of dependencies, only configure
 #   yard doc generation when *not* on Travis, JRuby, or < 2.0
 if !on_travis? && !on_jruby? && !on_less_than_2_0?
-  require 'github/markup'
-  require 'redcarpet'
-  require 'yard'
-  require 'yard/rake/yardoc_task'
+  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.files   = ["lib/**/*.rb", OTHER_PATHS]
     t.options = %w(--markup-provider=redcarpet --markup=markdown --main=README.md)
   end
 end

data/docile.gemspec

@@ -1,45 +1,55 @@
-require File.expand_path('on_what', File.dirname(__FILE__))
-$:.push File.expand_path('../lib', __FILE__)
-require 'docile/version'
+$:.push File.expand_path("../lib", __FILE__)
+require File.expand_path("on_what", File.dirname(__FILE__))
+require "docile/version"
 
 Gem::Specification.new do |s|
-  s.name        = 'docile'
+  s.name        = "docile"
   s.version     = Docile::VERSION
-  s.author      = 'Marc Siegel'
-  s.email       = 'marc@usainnov.com'
-  s.homepage    = 'https://ms-ati.github.io/docile/'
-  s.summary     = 'Docile keeps your Ruby DSLs tame and well-behaved'
-  s.description = 'Docile turns any Ruby object into a DSL. Especially useful with the Builder pattern.'
-  s.license     = 'MIT'
+  s.author      = "Marc Siegel"
+  s.email       = "marc@usainnov.com"
+  s.homepage    = "https://ms-ati.github.io/docile/"
+  s.summary     = "Docile keeps your Ruby DSLs tame and well-behaved."
+  s.description = "Docile treats the methods of a given ruby object as a DSL " \
+                  "(domain specific language) within a given block. \n\n"      \
+                  "Killer feature: you can also reference methods, instance "  \
+                  "variables, and local variables from the original (non-DSL) "\
+                  "context within the block. \n\n"                             \
+                  "Docile releases follow Semantic Versioning as defined at "  \
+                  "semver.org."
+  s.license     = "MIT"
 
   # Files included in the gem
-  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 = %w(lib)
+  s.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  s.require_paths = ["lib"]
 
   # Specify oldest supported Ruby version
-  s.required_ruby_version = '>= 1.8.7'
+  s.required_ruby_version = ">= 1.8.7"
 
-  # Run rspec tests from rake
-  s.add_development_dependency 'rake', '~> 10.5.0' if on_less_than_1_9_3? # Pin compatible rake on old rubies, see: https://github.com/travis-ci/travis.rb/issues/380
-  s.add_development_dependency 'rake', '< 11.0'    unless on_less_than_1_9_3? # See http://stackoverflow.com/questions/35893584/nomethoderror-undefined-method-last-comment-after-upgrading-to-rake-11
-  s.add_development_dependency 'rspec', '~> 3.0.0'
+  # Run rspec tests from rake even on old Ruby versions
+  s.add_development_dependency "rake", "~> 10.5" if on_less_than_1_9_3? # Pin compatible rake on old rubies, see: https://github.com/travis-ci/travis.rb/issues/380
+  s.add_development_dependency "rake", "< 11.0"  unless on_less_than_1_9_3? # See http://stackoverflow.com/questions/35893584/nomethoderror-undefined-method-last-comment-after-upgrading-to-rake-11
+  s.add_development_dependency "rspec", "~> 3.0"
+  s.add_development_dependency "rspec-expectations", "!= 3.8.3" # Workaround for RSpec's issue, see: https://github.com/rspec/rspec-expectations/issues/1111
 
-  # Pin versions for Travis builds on 1.9
-  s.add_development_dependency 'json', '< 2.0' if on_less_than_2_0?
+  # Run code coverage where possible - not on Rubinius
+  unless on_rubinius?
+    # Pin versions for Travis builds on 1.9
+    s.add_development_dependency "json", "< 2.0" if on_less_than_2_0?
 
-  # Pin versions for Travis builds on 1.8
-  s.add_development_dependency 'mime-types' , '~> 1.25.1' if on_1_8?
-  s.add_development_dependency 'rest-client', '~> 1.6.8'  if on_1_8?
+    # Pin versions for Travis builds on 1.8
+    s.add_development_dependency "mime-types" , "~> 1.25.1" if on_1_8?
+    s.add_development_dependency "rest-client", "~> 1.6.8"  if on_1_8?
+  end
 
   # To limit needed compatibility with versions of dependencies, only configure
-  #   yard doc generation when *not* on Travis, JRuby, or < 2.0
-  if !on_travis? && !on_jruby? && !on_less_than_2_0?
+  #   yard doc generation when *not* on Travis, JRuby, Rubinius, or < 2.0
+  if !on_travis? && !on_jruby? && !on_rubinius? && !on_less_than_2_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'
+    s.add_development_dependency "yard"
+    s.add_development_dependency "redcarpet"
+    s.add_development_dependency "github-markup"
   end
 end

data/lib/docile.rb

@@ -1,7 +1,8 @@
-require 'docile/version'
-require 'docile/execution'
-require 'docile/fallback_context_proxy'
-require 'docile/chaining_fallback_context_proxy'
+require "docile/version"
+require "docile/execution"
+require "docile/fallback_context_proxy"
+require "docile/chaining_fallback_context_proxy"
+require "docile/backtrace_filter"
 
 # Docile keeps your Ruby DSLs tame and well-behaved.
 module Docile

data/lib/docile/backtrace_filter.rb

@@ -0,0 +1,22 @@
+module Docile
+  # @api private
+  #
+  # This is used to remove entries pointing to Docile's source files
+  # from {Exception#backtrace} and {Exception#backtrace_locations}.
+  #
+  # If {NoMethodError} is caught then the exception object will be extended
+  # by this module to add filter functionalities.
+  module BacktraceFilter
+    FILTER_PATTERN = /lib\/docile/
+
+    def backtrace
+      super.select { |trace| trace !~ FILTER_PATTERN }
+    end
+
+    if ::Exception.public_method_defined?(:backtrace_locations)
+      def backtrace_locations
+        super.select { |location| location.absolute_path !~ FILTER_PATTERN }
+      end
+    end
+  end
+end

data/lib/docile/chaining_fallback_context_proxy.rb

@@ -1,4 +1,4 @@
-require 'docile/fallback_context_proxy'
+require "docile/fallback_context_proxy"
 
 module Docile
   # @api private
@@ -17,4 +17,4 @@ module Docile
       @__receiver__ = super(method, *args, &block)
     end
   end
-end
+end

data/lib/docile/execution.rb

@@ -15,16 +15,22 @@ module Docile
     # @param block      [Proc]   the block of DSL commands to be executed
     # @return           [Object] the return value of the block
     def exec_in_proxy_context(dsl, proxy_type, *args, &block)
-      block_context = eval('self', block.binding)
+      block_context = eval("self", block.binding)
       proxy_context = proxy_type.new(dsl, block_context)
       begin
         block_context.instance_variables.each do |ivar|
           value_from_block = block_context.instance_variable_get(ivar)
           proxy_context.instance_variable_set(ivar, value_from_block)
         end
+
         proxy_context.instance_exec(*args, &block)
       ensure
+        if block_context.respond_to?(:__docile_undo_fallback__)
+          block_context.send(:__docile_undo_fallback__)
+        end
+
         block_context.instance_variables.each do |ivar|
+          next unless proxy_context.instance_variables.include?(ivar)
           value_from_dsl_proxy = proxy_context.instance_variable_get(ivar)
           block_context.instance_variable_set(ivar, value_from_dsl_proxy)
         end
@@ -32,4 +38,4 @@ module Docile
     end
     module_function :exec_in_proxy_context
   end
-end
+end

data/lib/docile/fallback_context_proxy.rb

@@ -1,4 +1,4 @@
-require 'set'
+require "set"
 
 module Docile
   # @api private
@@ -17,10 +17,14 @@ module Docile
     # The set of methods which will **not** be proxied, but instead answered
     # by this object directly.
     NON_PROXIED_METHODS = Set[:__send__, :object_id, :__id__, :==, :equal?,
-                              :'!', :'!=', :instance_exec, :instance_variables,
+                              :"!", :"!=", :instance_exec, :instance_variables,
                               :instance_variable_get, :instance_variable_set,
                               :remove_instance_variable]
 
+    # The set of methods which will **not** fallback from the block's context
+    # to the dsl object.
+    NON_FALLBACK_METHODS = Set[:class, :self, :respond_to?, :instance_of?]
+
     # The set of instance variables which are local to this object and hidden.
     # All other instance variables will be copied in and out of this object
     # from the scope in which this proxy was created.
@@ -38,6 +42,32 @@ module Docile
     def initialize(receiver, fallback)
       @__receiver__ = receiver
       @__fallback__ = fallback
+
+      # Enables calling DSL methods from helper methods in the block's context
+      unless fallback.respond_to?(:method_missing)
+        # NOTE: There's no {#define_singleton_method} on Ruby 1.8.x
+        singleton_class = (class << fallback; self; end)
+
+        # instrument {#method_missing} on the block's context to fallback to
+        # the DSL object. This allows helper methods in the block's context to
+        # contain calls to methods on the DSL object.
+        singleton_class.
+          send(:define_method, :method_missing) do |method, *args, &block|
+            m = method.to_sym
+            if !NON_FALLBACK_METHODS.include?(m) && !fallback.respond_to?(m) && receiver.respond_to?(m)
+              receiver.__send__(method.to_sym, *args, &block)
+            else
+              super(method, *args, &block)
+            end
+          end
+
+        # instrument a helper method to remove the above instrumentation
+        singleton_class.
+          send(:define_method, :__docile_undo_fallback__) do
+            singleton_class.send(:remove_method, :method_missing)
+            singleton_class.send(:remove_method, :__docile_undo_fallback__)
+          end
+      end
     end
 
     # @return [Array<Symbol>]  Instance variable names, excluding
@@ -56,8 +86,14 @@ module Docile
       if @__receiver__.respond_to?(method.to_sym)
         @__receiver__.__send__(method.to_sym, *args, &block)
       else
-        @__fallback__.__send__(method.to_sym, *args, &block)
+        begin
+          @__fallback__.__send__(method.to_sym, *args, &block)
+        rescue NoMethodError => e
+          e.extend(BacktraceFilter)
+          raise e
+        end
       end
     end
+    ruby2_keywords :method_missing if respond_to?(:ruby2_keywords, true)
   end
 end

data/lib/docile/version.rb

@@ -1,4 +1,4 @@
 module Docile
   # The current version of this library
-  VERSION = '1.2.0'
+  VERSION = "1.3.4"
 end

data/on_what.rb

@@ -2,21 +2,29 @@
 #   between Rakefile, gemspec, and spec_helper. Not for use in actual library.
 
 def on_travis?
-  ENV['CI'] == 'true'
+  ENV["CI"] == "true"
 end
 
 def on_jruby?
-  defined?(RUBY_ENGINE) && 'jruby' == RUBY_ENGINE
+  defined?(RUBY_ENGINE) && "jruby" == RUBY_ENGINE
+end
+
+def on_rubinius?
+  defined?(RUBY_ENGINE) && "rbx" == RUBY_ENGINE
 end
 
 def on_1_8?
-  RUBY_VERSION.start_with? '1.8'
+  RUBY_VERSION.start_with? "1.8"
 end
 
 def on_less_than_1_9_3?
-  RUBY_VERSION < '1.9.3'
+  RUBY_VERSION < "1.9.3"
 end
 
 def on_less_than_2_0?
-  RUBY_VERSION < '2.0.0'
+  RUBY_VERSION < "2.0.0"
+end
+
+def on_less_than_2_3?
+  RUBY_VERSION < "2.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: docile
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.4
 platform: ruby
 authors:
 - Marc Siegel
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2018-01-11 00:00:00.000000000 Z
+date: 2020-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -30,14 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "!="
+      - !ruby/object:Gem::Version
+        version: 3.8.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "!="
+      - !ruby/object:Gem::Version
+        version: 3.8.3
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -80,8 +94,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Docile turns any Ruby object into a DSL. Especially useful with the Builder
-  pattern.
+description: "Docile treats the methods of a given ruby object as a DSL (domain specific
+  language) within a given block. \n\nKiller feature: you can also reference methods,
+  instance variables, and local variables from the original (non-DSL) context within
+  the block. \n\nDocile releases follow Semantic Versioning as defined at semver.org."
 email: marc@usainnov.com
 executables: []
 extensions: []
@@ -98,18 +114,17 @@ files:
 - Rakefile
 - docile.gemspec
 - lib/docile.rb
+- lib/docile/backtrace_filter.rb
 - lib/docile/chaining_fallback_context_proxy.rb
 - lib/docile/execution.rb
 - lib/docile/fallback_context_proxy.rb
 - lib/docile/version.rb
 - on_what.rb
-- spec/docile_spec.rb
-- spec/spec_helper.rb
 homepage: https://ms-ati.github.io/docile/
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -124,11 +139,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.13
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
-summary: Docile keeps your Ruby DSLs tame and well-behaved
-test_files:
-- spec/docile_spec.rb
-- spec/spec_helper.rb
+summary: Docile keeps your Ruby DSLs tame and well-behaved.
+test_files: []

data/spec/docile_spec.rb

@@ -1,362 +0,0 @@
-require 'spec_helper'
-require 'singleton'
-
-describe Docile do
-
-  describe '.dsl_eval' do
-
-    context 'when DSL context object is an Array' do
-      let(:array) { [] }
-      let!(:result) { execute_dsl_against_array }
-
-      def execute_dsl_against_array
-        Docile.dsl_eval(array) do
-          push 1
-          push 2
-          pop
-          push 3
-        end
-      end
-
-      it 'executes the block against the DSL context object' do
-        expect(array).to eq([1, 3])
-      end
-
-      it 'returns the DSL object after executing block against it' do
-        expect(result).to eq(array)
-      end
-
-      it "doesn't proxy #__id__" do
-        Docile.dsl_eval(array) { expect(__id__).not_to eq(array.__id__) }
-      end
-
-      it "raises NoMethodError if the DSL object doesn't implement the method" do
-        expect { Docile.dsl_eval(array) { no_such_method } }.to raise_error(NoMethodError)
-      end
-    end
-
-    Pizza = Struct.new(:cheese, :pepperoni, :bacon, :sauce)
-
-    class PizzaBuilder
-      def cheese(v=true);    @cheese    = v; end
-      def pepperoni(v=true); @pepperoni = v; end
-      def bacon(v=true);     @bacon     = v; end
-      def sauce(v=nil);      @sauce     = v; end
-      def build
-        Pizza.new(!!@cheese, !!@pepperoni, !!@bacon, @sauce)
-      end
-    end
-
-    context 'when DSL context object is a Builder pattern' do
-      let(:builder) { PizzaBuilder.new }
-      let(:result) { execute_dsl_against_builder_and_call_build }
-
-      def execute_dsl_against_builder_and_call_build
-        @sauce = :extra
-        Docile.dsl_eval(builder) do
-          bacon
-          cheese
-          sauce @sauce
-        end.build
-      end
-
-      it 'returns correctly built object' do
-        expect(result).to eq(Pizza.new(true, false, true, :extra))
-      end
-    end
-
-    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
-
-      def inner_with_params(param, &block)
-        Docile.dsl_eval(InnerDSL.new, param, :foo, &block)
-      end
-    end
-
-    def outer(&block)
-      Docile.dsl_eval(OuterDSL.new, &block)
-    end
-
-    context 'when given parameters for the DSL block' do
-      def parameterized(*args, &block)
-        Docile.dsl_eval(OuterDSL.new, *args, &block)
-      end
-
-      it 'passes parameters to the block' do
-        parameterized(1,2,3) do |x,y,z|
-          expect(x).to eq(1)
-          expect(y).to eq(2)
-          expect(z).to eq(3)
-        end
-      end
-
-      it 'finds parameters before methods' do
-        parameterized(1) { |a| expect(a).to eq(1) }
-      end
-
-      it 'find outer dsl parameters in inner dsl scope' do
-        parameterized(1,2,3) do |a,b,c|
-          inner_with_params(c) do |d,e|
-            expect(a).to eq(1)
-            expect(b).to eq(2)
-            expect(c).to eq(3)
-            expect(d).to eq(c)
-            expect(e).to eq(:foo)
-          end
-        end
-      end
-    end
-
-    class DSLWithNoMethod
-      def initialize(b); @b = b; end
-      attr_accessor :b
-      def push_element
-        @b.push 1
-      end
-    end
-
-    context 'when DSL have NoMethod error inside' do
-      it 'raise error from nil' do
-        Docile.dsl_eval(DSLWithNoMethod.new(nil)) do
-          expect { push_element }.to raise_error(NoMethodError, /undefined method `push' (for|on) nil:NilClass/)
-        end
-      end
-    end
-
-    context 'when DSL blocks are nested' do
-
-      context 'method lookup' do
-        it 'finds method of outer dsl in outer dsl scope' do
-          outer { expect(a).to eq('a') }
-        end
-
-        it 'finds method of inner dsl in inner dsl scope' do
-          outer { inner { expect(b).to eq('b') } }
-        end
-
-        it 'finds method of outer dsl in inner dsl scope' do
-          outer { inner { expect(a).to eq('a') } }
-        end
-
-        it "finds method of block's context in outer dsl scope" do
-          def c; 'c'; end
-          outer { expect(c).to eq('c') }
-        end
-
-        it "finds method of block's context in inner dsl scope" do
-          def c; 'c'; end
-          outer { inner { expect(c).to eq('c') } }
-        end
-
-        it 'finds method of outer dsl in preference to block context' do
-          def a; 'not a'; end
-          outer { expect(a).to eq('a') }
-          outer { inner { expect(a).to eq('a') } }
-        end
-      end
-
-      context 'local variable lookup' do
-        it 'finds local variable from block context in outer dsl scope' do
-          foo = 'foo'
-          outer { expect(foo).to eq('foo') }
-        end
-
-        it 'finds local variable from block definition in inner dsl scope' do
-          bar = 'bar'
-          outer { inner { expect(bar).to eq('bar') } }
-        end
-      end
-
-      context 'instance variable lookup' do
-        it 'finds instance variable from block definition in outer dsl scope' do
-          @iv1 = 'iv1'; outer { expect(@iv1).to eq('iv1') }
-        end
-
-        it "proxies instance variable assignments in block in outer dsl scope back into block's context" do
-          @iv1 = 'foo'; outer { @iv1 = 'bar' }; expect(@iv1).to eq('bar')
-        end
-
-        it 'finds instance variable from block definition in inner dsl scope' do
-          @iv2 = 'iv2'; outer { inner { expect(@iv2).to eq('iv2') } }
-        end
-
-        it "proxies instance variable assignments in block in inner dsl scope back into block's context" do
-          @iv2 = 'foo'; outer { inner { @iv2 = 'bar' } }; expect(@iv2).to eq('bar')
-        end
-      end
-
-    end
-
-    context 'when DSL context object is a Dispatch pattern' do
-      class DispatchScope
-        def params
-          { :a => 1, :b => 2, :c => 3 }
-        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, &block)
-        MessageDispatch.instance.add_responder(path, &block)
-      end
-
-      def send_request(path, request)
-        MessageDispatch.instance.dispatch(path, request)
-      end
-
-      it 'dispatches correctly' do
-        @first = @second = nil
-
-        respond '/path' do |request|
-          @first = request
-        end
-
-        respond '/new_bike' do |bike|
-          @second = "Got a new #{bike}"
-        end
-
-        def x(y) ; "Got a #{y}"; end
-        respond '/third' do |third|
-          expect(x(third)).to eq('Got a third thing')
-        end
-
-        fourth = nil
-        respond '/params' do |arg|
-          fourth = params[arg]
-        end
-
-        send_request '/path', 1
-        send_request '/new_bike', 'ten speed'
-        send_request '/third', 'third thing'
-        send_request '/params', :b
-
-        expect(@first).to eq(1)
-        expect(@second).to eq('Got a new ten speed')
-        expect(fourth).to eq(2)
-      end
-
-    end
-
-  end
-
-  describe '.dsl_eval_with_block_return' do
-    let(:array) { [] }
-    let!(:result) { execute_dsl_against_array }
-
-    def execute_dsl_against_array
-      Docile.dsl_eval_with_block_return(array) do
-        push 1
-        push 2
-        pop
-        push 3
-        'Return me!'
-      end
-    end
-
-    it 'executes the block against the DSL context object' do
-      expect(array).to eq([1, 3])
-    end
-
-    it "returns the block's return value" do
-      expect(result).to eq('Return me!')
-    end
-  end
-
-  describe '.dsl_eval_immutable' do
-
-    context 'when DSL context object is a frozen String' do
-      let(:original) { "I'm immutable!".freeze }
-      let!(:result) { execute_non_mutating_dsl_against_string }
-
-      def execute_non_mutating_dsl_against_string
-        Docile.dsl_eval_immutable(original) do
-          reverse
-          upcase
-        end
-      end
-
-      it "doesn't modify the original string" do
-        expect(original).to eq("I'm immutable!")
-      end
-
-      it 'chains the commands in the block against the DSL context object' do
-        expect(result).to eq("!ELBATUMMI M'I")
-      end
-    end
-
-    context 'when DSL context object is a number' do
-      let(:original) { 84.5 }
-      let!(:result) { execute_non_mutating_dsl_against_number }
-
-      def execute_non_mutating_dsl_against_number
-        Docile.dsl_eval_immutable(original) do
-          fdiv(2)
-          floor
-        end
-      end
-
-      it 'chains the commands in the block against the DSL context object' do
-        expect(result).to eq(42)
-      end
-    end
-  end
-
-end
-
-describe Docile::FallbackContextProxy do
-
-  describe '#instance_variables' do
-    subject { create_fcp_and_set_one_instance_variable.instance_variables }
-    let(:expected_type_of_names) { type_of_ivar_names_on_this_ruby }
-    let(:actual_type_of_names) { subject.first.class }
-    let(:excluded) { Docile::FallbackContextProxy::NON_PROXIED_INSTANCE_VARIABLES }
-
-    def create_fcp_and_set_one_instance_variable
-      fcp = Docile::FallbackContextProxy.new(nil, nil)
-      fcp.instance_variable_set(:@foo, 'foo')
-      fcp
-    end
-
-    def type_of_ivar_names_on_this_ruby
-      @a = 1
-      instance_variables.first.class
-    end
-
-    it 'returns proxied instance variables' do
-      expect(subject.map(&:to_sym)).to include(:@foo)
-    end
-
-    it "doesn't return non-proxied instance variables" do
-      expect(subject.map(&:to_sym)).not_to include(*excluded)
-    end
-
-    it 'preserves the type (String or Symbol) of names on this ruby version' do
-      expect(actual_type_of_names).to eq(expected_type_of_names)
-    end
-  end
-
-end

data/spec/spec_helper.rb

@@ -1,31 +0,0 @@
-require File.expand_path('on_what', File.dirname(File.dirname(__FILE__)))
-
-# Code coverage (via SimpleCov) on Ruby 1.9+
-unless on_1_8?
-  begin
-    require 'simplecov'
-    SimpleCov.start do
-      add_filter '/spec/'      # exclude test code
-      add_filter '/vendor/'    # exclude gems which are vendored on Travis CI
-      add_filter '/on_what.rb' # exclude help used only in gemspec
-    end
-
-    # On CI we publish simplecov results to codecov.io
-    if on_travis?
-      require 'codecov'
-      SimpleCov.formatter = SimpleCov::Formatter::Codecov
-    end
-
-    # Due to circular dependency (simplecov depends on docile), remove docile and require again below
-    Object.send(:remove_const, :Docile)
-    $LOADED_FEATURES.reject! { |f| f =~ /\/docile\// }
-  rescue LoadError
-    warn 'warning: simplecov or codecov gems not found; skipping coverage'
-  end
-end
-
-lib_dir = File.join(File.dirname(File.dirname(__FILE__)), 'lib')
-$LOAD_PATH.unshift lib_dir unless $LOAD_PATH.include? lib_dir
-
-# Require Docile again, now with coverage enabled on 1.9+
-require 'docile'