iron-extensions 1.0.1 → 1.1.0

data/History.txt

@@ -1,3 +1,7 @@
+== 1.1.0 / 2012-03-06
+
+* Added DslProxy class and specs, which enables slim and sexy DSL construction
+
 == 1.0.1 / 2012-03-03
 
 * Updated docs, fixed up minor packaging issues

data/README.rdoc

@@ -57,7 +57,7 @@ Helpful extensions to core Ruby classes
 
 * Numeric#bound - bound a given number to a range
 
-    4.bound(5,10) # => 4
+    4.bound(5,10) # => 5
 
 * Object#in? - sugar to make expressing inclusion clearer
 
@@ -84,15 +84,33 @@ Helpful extensions to core Ruby classes
 * Symbol#blank? - always false
 * Symbol#to_dashcase - same as for String
 
+== ADDED CLASSES/MODULES
+
+* DslProxy - a cool and sexy way to make powerful DSLs (domain-specific languages) look easy - see the docs for details
+
+    # DslProxy makes this code possible:
+    @items = ['one', 'two']
+    Console.out do
+      # No explicit receiver for DSL method calls
+      p 'Item List'
+      hr
+      indent do
+        # Even nested, local variables are still available
+        @items.each {|item| p item }
+      end
+    end
+
 == SYNOPSIS
 
 To use:
 
     require 'iron/extensions'
+    
+After that, simply write code to make use of the new extensions and helper classes.
 
 == REQUIREMENTS
 
-* None
+* Ruby 1.9.2 or later
 
 == INSTALL
 

data/Version.txt

@@ -1 +1 @@
-1.0.1
+1.1.0

data/lib/iron/extensions/dsl_proxy.rb

@@ -0,0 +1,112 @@
+# Specialty helper class for building elegant DSLs (domain-specific languages)
+# The purpose of the class is to allow seamless DSL's by allowing execution
+# of blocks with the instance variables of the calling context preserved, but
+# all method calls be proxied to a given receiver.  This sounds pretty abstract,
+# so here's an example:
+# 
+#   class ControlBuilder
+#     def initialize; @controls = []; end
+#     def control_list; @controls; end
+#     def knob; @controls << :knob; end
+#     def button; @controls << :button; end
+#     def switch; @controls << :switch; end
+#     def self.define(&block)
+#       @builder = self.new
+#       DslProxy.exec(@builder, &block)
+#       # Do something here with the builder's list of controls
+#       @builder.control_list
+#     end
+#   end
+#
+#   @knob_count = 5
+#   new_list = ControlBuilder.define do
+#     switch
+#     @knob_count.times { knob }
+#     button
+#   end
+#
+# Notice the lack of explicit builder receiver to the calls to #switch, #knob and #button.
+# Those calls are automatically proxied to the @builder we passed to the DslProxy.
+#
+# In quick and dirty DSLs, like Rails' migrations, you end up with a lot of
+# pointless receiver declarations for each method call, like so:
+#
+# def change
+#   create_table do |t|
+#     t.integer :counter
+#     t.text :title
+#     t.text :desc
+#     # ... tired of typing "t." yet? ...
+#   end
+# end
+#
+# This is not a big deal if you're using a simple DSL, but when you have multiple nested
+# builders going on at once, it is ugly, pointless, and can cause bugs when
+# the throwaway arg names you choose (eg 't' above) overlap in scope.
+# 
+# In addition, simply using a yield statment loses the instance variables set in the calling
+# context.  This is a major pain in eg Rails views, where most of the interesting
+# data resides in instance variables.  You can get around this when #yield-ing by
+# explicitly creating a local variable to be picked up by the closure created in the
+# block, but it kind of sucks.
+# 
+# In summary, DslProxy allows you to keep all the local and instance variable context
+# from your block declarations, while proxying all method calls to a given
+# receiver.  If you're not building DSLs, this class is not for you, but if you are,
+# I hope it helps!
+class DslProxy < BasicObject
+  
+  # Pass in a builder-style class, or other receiver you want set as "self" within the
+  # block, and off you go.  The passed block will be executed with all
+  # block-context local and instance variables available, but with all
+  # method calls sent to the receiver you pass in.  The block's result will
+  # be returned.  If the receiver doesn't
+  def self.exec(receiver, &block) # :yields: receiver
+    proxy = DslProxy.new(receiver, &block)
+    return proxy._result
+  end
+  
+  # Create a new proxy and execute the passed block
+  def initialize(builder, &block) # :yields: receiver
+    # Save the dsl target as our receiver for proxying
+    @_receiver = builder
+
+    # Find the context within which the block was defined
+    @_context = ::Kernel.eval('self', block.binding)
+    # Run each instance variable, and set it to ourselves so we can proxy it
+    @_context.instance_variables.each do |var|
+      value = @_context.instance_variable_get(var.to_s)
+      instance_eval "#{var} = value"
+    end
+    
+    # Run the block with ourselves as the new "self", passing the receiver in case
+    # the code wants to disambiguate for some reason
+    @_result = instance_exec(@_receiver, &block)
+    
+    # Run each instance variable, and set it to ourselves so we can proxy it
+    @_context.instance_variables.each do |var|
+      @_context.instance_variable_set(var.to_s, instance_eval("#{var}"))
+    end
+  end
+  
+  # Returns value of the exec'd block
+  def _result
+    @_result
+  end
+
+  # Proxies all calls to our receiver, or to the block's context
+  # if the receiver doesn't respond_to? it.
+  def method_missing(method, *args, &block)
+    if @_receiver.respond_to?(method)
+      @_receiver.send(method, *args, &block)
+    else
+      @_context.send(method, *args, &block)
+    end
+  end
+  
+  # Proxies searching for constants to the context
+  def self.const_missing(name)
+    @_context.class.const_get(name)
+  end
+  
+end

data/spec/extensions/dsl_proxy_spec.rb

@@ -0,0 +1,86 @@
+describe DslProxy do
+
+  # Sample DSL builder class for use in testing
+  class ControlBuilder
+    def initialize; @controls = []; end
+    def controls; @controls; end
+    def knob; @controls << :knob; end
+    def button; @controls << :button; end
+    def switch; @controls << :switch; end
+
+    def self.define(&block)
+      @builder = self.new
+      DslProxy.exec(@builder, &block)
+      @builder.controls
+    end
+  end
+  
+  it 'should proxy calls to the receiver' do
+    receiver = Object.new
+    DslProxy.exec(receiver) do
+      self.class.name.should == 'Object'
+    end
+  end
+  
+  it 'should proxy respond_to? to the receiver' do
+    receiver = Object.new
+    DslProxy.exec(receiver) do
+      respond_to?(:garbaz).should == false
+      respond_to?(:dup).should == true
+    end
+  end
+  
+  it 'should proxy local variables from the binding context' do
+    @foo = 'bar'
+    DslProxy.exec(Object.new) do
+      @foo.should == 'bar'
+    end
+  end
+
+  it 'should propagate local variable changes back to the binding context' do
+    @foo = 'bar'
+    DslProxy.exec(Object.new) do
+      @foo = 'no bar!'
+    end
+    @foo.should == 'no bar!'
+  end
+  
+  it 'should proxy missing methods on the receiver to the context' do
+    class TestContext
+      def bar
+        'something'
+      end
+      
+      def test
+        DslProxy.exec(Object.new) do
+          bar
+        end
+      end
+    end
+    
+    TestContext.new.test.should == 'something'
+  end
+
+  it 'should return the result of the block' do
+    res = DslProxy.exec(Object.new) do
+      'foo'
+    end
+    res.should == 'foo'
+  end
+
+  it 'should allow access to global constants' do
+    DslProxy.exec(self) do # Use self here, so #be_a is defined.  :-)
+      Object.new.should be_a(Object)
+    end
+  end
+  
+  it 'should put it all together' do
+    @knob_count = 5
+    controls = ControlBuilder.define do
+      switch
+      @knob_count.times { knob }
+    end
+    controls.count.should == 6
+  end
+  
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iron-extensions
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-03 00:00:00.000000000Z
+date: 2012-03-07 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2156310200 !ruby/object:Gem::Requirement
+  requirement: &2160170500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,7 +21,7 @@ dependencies:
         version: '2.6'
   type: :development
   prerelease: false
-  version_requirements: *2156310200
+  version_requirements: *2160170500
 description: Adds common extensions to core Ruby classes
 email:
 - rob@irongaze.com
@@ -30,6 +30,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/iron/extensions/array.rb
+- lib/iron/extensions/dsl_proxy.rb
 - lib/iron/extensions/enumerable.rb
 - lib/iron/extensions/file.rb
 - lib/iron/extensions/fixnum.rb
@@ -43,6 +44,7 @@ files:
 - lib/iron/extensions/string.rb
 - lib/iron/extensions/symbol.rb
 - lib/iron/extensions.rb
+- spec/extensions/dsl_proxy_spec.rb
 - spec/extensions/enumerable_spec.rb
 - spec/extensions/kernel_spec.rb
 - spec/extensions/numeric_spec.rb