docile 1.1.5 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4df64881f4215d866d038e00f55d5b1ca2a45cb2
-  data.tar.gz: 26a8de33f8bf657873666a2754bf09f605334e9d
+  metadata.gz: efc3f0539f1c253fdc8487bcc23f671e8c74fab5
+  data.tar.gz: 4a6ff57d636604f406e6d19ca27b6fce30110d9f
 SHA512:
-  metadata.gz: 75669d4f578d70ba4c8be7dd6c19676041506e0f9408ba26ea0b1ad7931cf59636ccf36a4363ae709a1476464caba5ca1c429b07233dda7d797d5007f3c0af10
-  data.tar.gz: e0e0e7364436ce92f4ab5efc52c2782e5da098d302652ca8698d74bcccc27c695b269c04ced3d224eec1a5b3833ba91c44232a2cc4c55fe061504246a715ef49
+  metadata.gz: 410b86373972c31e31811dad9dc257501be169d43484023f98a54f63ff1a9c61cc5ac5974aaea384e4373a93eeab763f1f5d7db80803f2d605581963f19c9f4c
+  data.tar.gz: 84dd464b50e7d368c198570370233e8ea1c2fef17e1d114a0b1798a302c0bf7126ff38bfe1a53d6a2e1609f524e689ae6b9233af7c9b5bca6978f0f68fd817e0

data/.gitignore

@@ -6,4 +6,6 @@ pkg
 doc
 .yardoc
 coverage
-vendor
+vendor
+.ruby-gemset
+.ruby-version

data/.travis.yml

@@ -1,21 +1,37 @@
 language: ruby
-cache: bundler
+
+# 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
+
 rvm:
+  # MRI
   - ruby-head
-  - 2.1.2
-  - 2.1.1
-  - 2.1.0
-  - 2.0.0
+  - 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.9.2
   - 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
-  - rbx-2
+  # Rubinius
+  - rubinius-3
+
 matrix:
   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
   fast_finish: true

data/Gemfile

@@ -1,4 +1,12 @@
+require File.expand_path('on_what', File.dirname(__FILE__))
 source 'https://rubygems.org'
 
+# Travis-only dependencies go here
+if on_travis? && !on_1_8?
+  group :test do
+    gem 'codecov', '>= 0.0.9', :require => false
+  end
+end
+
 # Specify gem's dependencies in docile.gemspec
 gemspec

data/HISTORY.md

@@ -1,5 +1,14 @@
 # HISTORY
 
+## [Unreleased changes](http://github.com/ms-ati/docile/compare/v1.2.0...master)
+
+## [v1.2.0 (Jan 11, 2018)](http://github.com/ms-ati/docile/compare/v1.1.5...v1.2.0)
+
+  - Special thanks to Christina Koller (@cmkoller)
+    - add DSL evaluation returning *return value of the block* (see `.dsl_eval_with_block_return`)
+  - add an example to README
+  - keep travis builds passing on old ruby versions
+
 ## [v1.1.5 (Jun 15, 2014)](http://github.com/ms-ati/docile/compare/v1.1.4...v1.1.5)
 
   - as much as possible, loosen version restrictions on development dependencies

data/LICENSE

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

@@ -1,11 +1,16 @@
 # Docile
-[![Gem Version](https://badge.fury.io/rb/docile.png)](http://badge.fury.io/rb/docile)
-[![Build Status](https://travis-ci.org/ms-ati/docile.png)](https://travis-ci.org/ms-ati/docile)
-[![Dependency Status](https://gemnasium.com/ms-ati/docile.png)](https://gemnasium.com/ms-ati/docile)
-[![Code Climate](https://codeclimate.com/github/ms-ati/docile.png)](https://codeclimate.com/github/ms-ati/docile)
-[![Coverage Status](https://coveralls.io/repos/ms-ati/docile/badge.png)](https://coveralls.io/r/ms-ati/docile)
-[![Inline docs](http://inch-ci.org/github/ms-ati/docile.png)](http://inch-ci.org/github/ms-ati/docile)
-[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/ms-ati/docile/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
+
+[![Gem Version](https://img.shields.io/gem/v/docile.svg)](https://rubygems.org/gems/docile)
+[![Gem Downloads](https://img.shields.io/gem/dt/docile.svg)](https://rubygems.org/gems/docile)
+
+[![Join the chat at https://gitter.im/ms-ati/docile](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/ms-ati/docile?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/ms-ati/docile)
+[![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)
 
 Ruby makes it possible to create very expressive **Domain Specific
 Languages**, or **DSL**'s for short. However, it requires some deep knowledge and
@@ -20,7 +25,7 @@ coding a bit more docile...
 
 ## Usage
 
-### Basic
+### Basic: Ruby [Array](http://ruby-doc.org/core-2.2.2/Array.html) 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?
@@ -43,9 +48,54 @@ def with_array(arr=[], &block)
 end
 ```
 
-Easy!
+**Easy!**
+
+### 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.
+
+For example:
+
+```ruby
+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.
 
-### Advanced
+### Build a Pizza
 
 Mutating (changing) an Array instance is fine, but what usually makes a good DSL is a [Builder Pattern][2].
 
@@ -83,7 +133,7 @@ PizzaBuilder.new.cheese.pepperoni.sauce(:extra).build
 
 Then implement your DSL like this:
 
-``` ruby
+```ruby
 def pizza(&block)
   Docile.dsl_eval(PizzaBuilder.new, &block).build
 end
@@ -93,6 +143,38 @@ It's just that easy!
 
 [2]: http://stackoverflow.com/questions/328496/when-would-you-use-the-builder-pattern  "Builder Pattern"
 
+### 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][4]:
+
+```ruby
+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][4] for details.
+
+[4]: https://gist.github.com/ms-ati/2bb17bdf10a430faba98
+
 ### Block parameters
 
 Parameters can be passed to the DSL block.
@@ -153,7 +235,7 @@ end
 
 [3]: http://www.sinatrarb.com "Sinatra"
 
-### Functional-Style DSL Objects
+### Functional-Style Immutable DSL Objects
 
 Sometimes, you want to use an object as a DSL, but it doesn't quite fit the
 [imperative](http://en.wikipedia.org/wiki/Imperative_programming) pattern shown
@@ -192,6 +274,33 @@ 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.
+
+```ruby
+arr = []
+with_array(arr) do
+  push "a"
+  push "b"
+  push "c"
+  length
+end
+#=> 3
+
+arr
+#=> ["a", "b", "c"]
+```
+
+```ruby
+def with_array(arr=[], &block)
+  Docile.dsl_eval_with_block_return(arr, &block)
+end
+```
+
 ## Features
 
   1.  Method lookup falls back from the DSL object to the block's context
@@ -234,7 +343,7 @@ Used by some pretty cool gems to implement their DSLs, notably including [Simple
 
 ## Copyright & License
 
-Copyright (c) 2012-2014 Marc Siegel.
+Copyright (c) 2012-2018 Marc Siegel.
 
 Licensed under the [MIT License](http://choosealicense.com/licenses/mit/), see [LICENSE](LICENSE) for details.
 

data/Rakefile

@@ -13,8 +13,8 @@ RSpec::Core::RakeTask.new
 CLOBBER.include('pkg', 'doc', 'coverage')
 
 # To limit needed compatibility with versions of dependencies, only configure
-#   yard doc generation when *not* on Travis, JRuby, or 1.8
-if !on_travis? && !on_jruby? && !on_1_8?
+#   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'

data/docile.gemspec

@@ -22,22 +22,24 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 1.8.7'
 
   # Run rspec tests from rake
-  s.add_development_dependency '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'
 
-  # NOTE: needed for Travis builds on 1.8, but can't yet reproduce failure locally
-  s.add_development_dependency 'mime-types', '~> 1.25.1' if on_1_8?
+  # 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?
 
   # To limit needed compatibility with versions of dependencies, only configure
-  #   yard doc generation when *not* on Travis, JRuby, or 1.8
-  if !on_travis? && !on_jruby? && !on_1_8?
+  #   yard doc generation when *not* on Travis, JRuby, or < 2.0
+  if !on_travis? && !on_jruby? && !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'
   end
-
-  # Coveralls test coverage tool, basically hosted SimpleCov
-  s.add_development_dependency 'coveralls'
 end

data/lib/docile.rb

@@ -45,6 +45,45 @@ module Docile
   end
   module_function :dsl_eval
 
+  # Execute a block in the context of an object whose methods represent the
+  # commands in a DSL, and return *the block's return value*.
+  #
+  # @note Use with an *imperative* DSL (commands modify the context object)
+  #
+  # Use this method to execute an *imperative* DSL, which means that:
+  #
+  #   1. Each command mutates the state of the DSL context object
+  #   2. The return value of each command is ignored
+  #   3. The final return value is the original context object
+  #
+  # @example Use a String as a DSL
+  #   Docile.dsl_eval_with_block_return("Hello, world!") do
+  #     reverse!
+  #     upcase!
+  #     first
+  #   end
+  #   #=> "!"
+  #
+  # @example Use an Array as a DSL
+  #   Docile.dsl_eval_with_block_return([]) do
+  #     push "a"
+  #     push "b"
+  #     pop
+  #     push "c"
+  #     length
+  #   end
+  #   #=> 2
+  #
+  # @param dsl   [Object] context object whose methods make up the DSL
+  # @param args  [Array]  arguments to be passed to the block
+  # @param block [Proc]   the block of DSL commands to be executed against the
+  #                         `dsl` context object
+  # @return      [Object] the return value from executing the block
+  def dsl_eval_with_block_return(dsl, *args, &block)
+    exec_in_proxy_context(dsl, FallbackContextProxy, *args, &block)
+  end
+  module_function :dsl_eval_with_block_return
+
   # Execute a block in the context of an immutable object whose methods,
   # and the methods of their return values, represent the commands in a DSL.
   #

data/lib/docile/version.rb

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

data/on_what.rb

@@ -6,9 +6,17 @@ def on_travis?
 end
 
 def on_jruby?
-  (defined?(RUBY_ENGINE) && 'jruby' == RUBY_ENGINE)
+  defined?(RUBY_ENGINE) && 'jruby' == RUBY_ENGINE
 end
 
 def on_1_8?
   RUBY_VERSION.start_with? '1.8'
-end
+end
+
+def on_less_than_1_9_3?
+  RUBY_VERSION < '1.9.3'
+end
+
+def on_less_than_2_0?
+  RUBY_VERSION < '2.0.0'
+end

data/spec/docile_spec.rb

@@ -263,6 +263,29 @@ describe Docile do
 
   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

data/spec/spec_helper.rb

@@ -1,26 +1,27 @@
 require File.expand_path('on_what', File.dirname(File.dirname(__FILE__)))
 
-begin
-  require 'simplecov'
-  require 'coveralls'
-
-  # On Ruby 1.9+ use SimpleCov and publish to Coveralls.io
-  if !on_1_8?
-    SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
-      SimpleCov::Formatter::HTMLFormatter,
-      Coveralls::SimpleCov::Formatter
-    ]
+# 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 '/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
 
-    # Remove Docile, which was required by SimpleCov, to require again later
+    # 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
-rescue LoadError
-  warn 'warning: simplecov/coveralls gems not found; skipping coverage'
 end
 
 lib_dir = File.join(File.dirname(File.dirname(__FILE__)), 'lib')

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: docile
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 1.2.0
 platform: ruby
 authors:
 - Marc Siegel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-15 00:00:00.000000000 Z
+date: 2018-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '11.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '11.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -80,20 +80,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: coveralls
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: Docile turns any Ruby object into a DSL. Especially useful with the Builder
   pattern.
 email: marc@usainnov.com
@@ -103,8 +89,6 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
-- ".ruby-gemset"
-- ".ruby-version"
 - ".travis.yml"
 - ".yardopts"
 - Gemfile
@@ -141,11 +125,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.6.13
 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
-has_rdoc: 

data/.ruby-gemset

@@ -1 +0,0 @@
-docile

data/.ruby-version

@@ -1 +0,0 @@
-ruby-2.1.0