docile 1.0.4 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b295f680ae1c64b5825a284bea4efbd8ddaa2c5b
-  data.tar.gz: d4f19b3d37e262cdbe117c98d40695798c8bfb94
+  metadata.gz: 75054a395059cd55ba3132c00dc49ae15cc6b954
+  data.tar.gz: 71f6114e6ac5d727240bd50c8e967127af688a53
 SHA512:
-  metadata.gz: 88e3011f1060083fac18a51a6337fc0f6f8f85f6c87ff45a596a8da35164374a5d815a47d20b76bee791bc346874b77062b702f90bbb81e6a5058049503cbf5a
-  data.tar.gz: 6d53a3345ce3f6ed0612cc445bdc338e8f6c3e8e53e405aedf70cfc106c9c56c02377bad6d331147b48e910f8936bcd510846bf1c6ad17a4c8e14f954905662b
+  metadata.gz: 57476b49adfb0e49f909c391420f6c7b1fdacd2fcf5aaced53443bd3c138ca6ca70ba047b261c9c20dc899a1a35e70950d3582f0dc267d33a2d5748dfd53aee1
+  data.tar.gz: 46b4708db7b9cb68b3f1415edb0f07d5dcc49ba6d86831a51b96e1774abcea346aa3f7412e106572d32893f2473ff7ccddae0596470efad85a1c08a1d737b91c

data/HISTORY.md

@@ -1,5 +1,10 @@
 # HISTORY
 
+## [v1.0.5 (Jul 28, 2013)](http://github.com/ms-ati/docile/compare/v1.0.4...v1.0.5)
+
+  - achieve 100% yard docs coverage
+  - fix rendering of docs at http://rubydoc.info/gems/docile
+
 ## [v1.0.4 (Jul 25, 2013)](http://github.com/ms-ati/docile/compare/v1.0.3...v1.0.4)
 
   - simplify and clarify code

data/README.md

@@ -30,6 +30,7 @@ end
 ```
 
 No problem, just define the method `with_array` like this:
+
 ``` ruby
 def with_array(arr=[], &block)
   Docile.dsl_eval(arr, &block)
@@ -43,6 +44,7 @@ Easy!
 Mutating (changing) an Array instance is fine, but what usually makes a good DSL is a [Builder Pattern][2].
 
 For example, let's say you want a DSL to specify how you want to build a Pizza:
+
 ```ruby
 @sauce_level = :extra
 
@@ -55,6 +57,7 @@ end
 ```
 
 And let's say we have a PizzaBuilder, which builds a Pizza like this:
+
 ```ruby
 Pizza = Struct.new(:cheese, :pepperoni, :bacon, :sauce)
 
@@ -89,6 +92,7 @@ It's just that easy!
 Parameters can be passed to the DSL block.
 
 Supposing you want to make some sort of cheap [Sinatra][3] knockoff:
+
 ```ruby
 @last_request = nil
 respond '/path' do |request|
@@ -106,6 +110,7 @@ end
 ```
 
 You'd put together a dispatcher something like this:
+
 ```ruby
 require 'singleton'
 

data/Rakefile

@@ -1,7 +1,17 @@
+require "rake/clean"
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-# Don't require doc generation gems on Travis
+# Default task for `rake` is to run rspec
+task :default => [:spec]
+
+# Use default rspec rake task
+RSpec::Core::RakeTask.new
+
+# Configure `rake clobber` to delete all generated files
+CLOBBER.include("pkg", "doc", "coverage")
+
+# Only configure yard doc generation when *not* on Travis
 if ENV['CI'] != 'true'
   require "github/markup"
   require "redcarpet"
@@ -14,7 +24,3 @@ if ENV['CI'] != 'true'
     t.options = %w(--markup-provider=redcarpet --markup=markdown --main=README.md)
   end
 end
-
-RSpec::Core::RakeTask.new
-
-task :default => [:spec]

data/lib/docile.rb

@@ -1,34 +1,53 @@
 require "docile/version"
 require "docile/fallback_context_proxy"
 
+# Docile keeps your Ruby DSLs tame and well-behaved
+# @see http://ms-ati.github.com/docile/
 module Docile
-  # Executes a block in the context of an object whose interface represents a DSL.
+  # Execute a block in the context of an object whose methods represent the
+  # commands in a DSL.
   #
-  # Example of using an Array as a DSL:
+  # @note Use with an *imperative* DSL (commands modify the context object)
   #
-  #     Docile.dsl_eval [] do
-  #       push 1
-  #       push 2
-  #       pop
-  #       push 3
-  #     end
-  #     #=> [1, 3]
+  # Use this method to execute an *imperative* DSL, which means that:
   #
-  # @param dsl   [Object] an object whose methods represent a DSL
+  #   1. each command mutates the state of the DSL context object
+  #   2. the return values of the commands are ignored
+  #
+  # @example Use a String as a DSL
+  #   Docile.dsl_eval("Hello, world!") do
+  #     reverse!
+  #     upcase!
+  #   end
+  #   #=> "!DLROW ,OLLEH"
+  #
+  # @example Use an Array as a DSL
+  #   Docile.dsl_eval([]) do
+  #     push 1
+  #     push 2
+  #     pop
+  #     push 3
+  #   end
+  #   #=> [1, 3]
+  #
+  # @param dsl   [Object] context object whose methods make up the DSL
   # @param args  [Array]  arguments to be passed to the block
-  # @param block [Proc]   a block to execute in the DSL context
-  # @return      [Object] the dsl object, after execution of the block
+  # @yield                the block of DSL commands to be executed against the
+  #                         `dsl` context object
+  # @return      [Object] the `dsl` context object after executing the block
   def dsl_eval(dsl, *args, &block)
     block_context = eval("self", block.binding)
     proxy_context = FallbackContextProxy.new(dsl, block_context)
     begin
       block_context.instance_variables.each do |ivar|
-        proxy_context.instance_variable_set(ivar, block_context.instance_variable_get(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)
+      proxy_context.instance_exec(*args, &block)
     ensure
       block_context.instance_variables.each do |ivar|
-        block_context.instance_variable_set(ivar, proxy_context.instance_variable_get(ivar))
+        value_from_dsl_proxy = proxy_context.instance_variable_get(ivar)
+        block_context.instance_variable_set(ivar, value_from_dsl_proxy)
       end
     end
     dsl

data/lib/docile/fallback_context_proxy.rb

@@ -1,28 +1,51 @@
 require 'set'
 
 module Docile
+  # A proxy object with a primary receiver as well as a secondary
+  # fallback receiver.
+  #
+  # Will attempt to forward all method calls first to the primary receiver,
+  # and then to the fallback receiver if the primary does not handle that
+  # method.
   class FallbackContextProxy
+    # 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_variable_get, :instance_variable_set,
                               :remove_instance_variable]
 
+    # 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.
     NON_PROXIED_INSTANCE_VARIABLES = Set[:@__receiver__, :@__fallback__]
 
+    # Undefine all instance methods except those in {NON_PROXIED_METHODS}
     instance_methods.each do |method|
       undef_method(method) unless NON_PROXIED_METHODS.include?(method.to_sym)
     end
 
+    # @param [Object] receiver  the primary proxy target to which all methods
+    #                             initially will be forwarded
+    # @param [Object] fallback  the fallback proxy target to which any methods
+    #                             not handled by `receiver` will be forwarded
     def initialize(receiver, fallback)
       @__receiver__ = receiver
       @__fallback__ = fallback
     end
 
+    # @return [Array<Symbol>]  Instance variable names, excluding
+    #                            {NON_PROXIED_INSTANCE_VARIABLES}
+    #
+    # @note on Ruby 1.8.x, the instance variable names are actually of
+    #   type `String`.
     def instance_variables
       # Ruby 1.8.x returns string names, convert to symbols for compatibility
       super.select { |v| !NON_PROXIED_INSTANCE_VARIABLES.include?(v.to_sym) }
     end
 
+    # Proxy all methods, excluding {NON_PROXIED_METHODS}, first to `receiver`
+    # and then to `fallback` if not found.
     def method_missing(method, *args, &block)
       @__receiver__.__send__(method.to_sym, *args, &block)
     rescue ::NoMethodError => e

data/lib/docile/version.rb

@@ -1,3 +1,4 @@
 module Docile
-  VERSION = "1.0.4"
+  # The current version of this library
+  VERSION = "1.0.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: docile
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.5
 platform: ruby
 authors:
 - Marc Siegel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-25 00:00:00.000000000 Z
+date: 2013-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake