iron-dsl 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 58e6a28f277a7fb6305e7ffb268f26d2f737c0e2
+  data.tar.gz: 2e08931bde299f5ac6f84f93f924b3e4beecf85f
+SHA512:
+  metadata.gz: 51b0a8cea42976e123c25471d8558cdea7e4f53ecd8d47de187d9551f87ec4f55429087fd9826f893ce18e729cfb3baffe344b6f942772f2d8fe28b8a0748bb4
+  data.tar.gz: 55e093337f7a637640d4d99acb6b4880be3515aabc0f949c23fb8ceaf5ea7a043dbdb62bc4a46145d1e8b4691a3c7e71fd02507da0ce5aea39384abb1c2ba352

data/.rspec

@@ -0,0 +1 @@
+--require <%= File.join(File.expand_path(File.dirname(__FILE__)), 'spec', 'spec_helper.rb') %>

data/History.txt

@@ -0,0 +1,5 @@
+== 1.0.0 / 2015-01-26
+
+* Broke out iron-dsl from older iron-extensions gem
+* Improved documentation a bit
+* Updated dsl_accessor to capture blocks

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Irongaze Consulting LLC
+
+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.rdoc

@@ -0,0 +1,149 @@
+= GEM: iron-dsl
+
+Written by Rob Morris @ Irongaze Consulting LLC (http://irongaze.com)
+
+== DESCRIPTION
+
+The iron-dsl gem provides a set of powerful tools for building "domain-specific languages"
+in Ruby.  Ruby's natural DSL construction capabilities (through, e.g. instance_eval) are
+very solid, but to make truly clean DSLs requires additional magic.  This gem provides
+that magic in a nice self-contained package.
+
+== USAGE
+
+There are 3 main pieces to this gem: DslBuilder, a set of accessor helpers, and DslProxy.
+
+DslBuilder is simply an empty class, suitable for use as a base class for your DSL receiver class.
+It is similar to BasicObject in the standard library, but has methods such as #respond_to? 
+and #send that are required for any real DSL building effort.
+
+You can use DslBuilder, or any other class, as the basis for your DSL system.  In any case,
+you want a clean way to set attributes on an instance of that class.  For that, we have
+two class-level methods: #dsl_accessor and #dsl_flag
+
+The first, #dsl_accessor, is a helpful method for defining accessors on DSL builder-style classes:
+
+    require 'iron/dsl'
+
+    class MyBuilder < DslBuilder
+      # Declare an accessor on this receiver class, just like you'd use attr_accessor
+      dsl_accessor :name
+    end
+    
+    # When you create an instance, you have a set of behavior for the #name accessor you declared
+    builder = MyBuilder.new
+    
+    # You can set a value by calling #name as a setter, and get the value by using #name as a getter
+    builder.name = 'ProjectX'
+    builder.name # => 'ProjectX'
+    
+    # But you can also set the value by simply calling #name with the value to set:
+    builder.name 'ProjectY'
+    builder.name  # => 'ProjectY'
+    
+    # This makes for a cleaner syntax when using your DSL with DslProxy#exec below..
+    DslProxy.exec(builder) do
+      name 'Project Omega'
+    end
+    builder.name  # => 'Project Omega'
+    
+    # You can also capture blocks this way, which is often useful in DSL creation for values
+    # that need to be dynamically calculated at run-time
+    builder.name do
+      "Project " + Date.today
+    end
+    
+The second accessor helper is #dsl_flag, which is the same as #dsl_accessor, but designed for 
+boolean values.
+
+    class AnotherBuilder < DslBuilder
+      dsl_flag :awesome
+    end
+    
+    builder = AnotherBuilder
+    builder.awesome?  # => false on uninitialized value
+    builder.awesome!  # => sets @awesome to true
+    # dsl_flags can still be set normally
+    builder.awesome true
+    builder.awesome false
+    
+Bringing it all together, and the key to the whole system, is DslProxy.  DslProxy is a more powerful version of
+#instance_exec that handles instance variable propagation and other nifty tricks like nesting and propagating 
+method references and constant lookups to the calling scope.  That all sounds like gibberish, so here's a few
+hopefully illustrative examples.
+
+    @name = 'Bob'
+    
+    # First, how you would traditionally do it:
+    instance_exec(some_receiver) do
+      # This fails - the instance var from the calling context is not defined.  Sucks if you're in Rails
+      # and trying to define something in a controller or view, where all the state is typically in
+      # instance vars!
+      self.name = @name
+    end
+    
+    # This, however, totally works
+    DslProxy.exec(some_receiver) do
+      # @name has bubbled into our block and can be referenced!
+      self.name = @name
+      # But of course, we'd use a dsl_accessor so we could lose the 'self.' and the '='
+      name @name
+      
+      # Having nested DSLs is also supported, all instance vars are available at all levels
+      sub_define do
+        page_title @name + ' Likes Bees'
+      end
+    end
+
+In summary, making DSLs is a bit of an art, and what this gem attempts to do is make pretty DSLs like this
+easier to build:
+
+    grid = Grid.define do
+      url '/orders/grid'
+      souce Order.by_date
+  
+      columns do
+        column :id
+        column :customer do
+          no_wrap!
+        column :total do
+          render_as :currency
+        end
+      end
+      
+      pagination do
+        default 40
+        allow_custom!
+      end
+    end
+
+Using code to configure complex systems (rather than hashes of hashes, or manually constructed settings objects)
+allows for a much more expressive codebase.  At Irongaze, we use this type of builder for grid controls, pagination,
+filters, forms, fields, and so forth.  Places where the MVC system breaks down, and complexity that bridges
+controller and view needs to be managed.
+      
+== SYNOPSIS
+
+To use:
+
+    require 'iron/dsl'
+    
+After that, simply write code to make use of the new extensions and helper classes.
+
+== REQUIREMENTS
+
+* Ruby 1.9.2 or later
+
+== INSTALL
+
+To install, simply run:
+
+    sudo gem install iron-dsl
+
+RVM users should drop the 'sudo':
+
+    gem install iron-dsl
+    
+Then simply require the library:
+
+    require 'iron/dsl'

data/Version.txt

@@ -0,0 +1 @@
+1.0.0

data/lib/iron/dsl.rb

@@ -0,0 +1,5 @@
+# Requires all classes
+search_path = File.join(File.expand_path(File.dirname(__FILE__)), '*', '*.rb')
+Dir.glob(search_path) do |path|
+  require path
+end

data/lib/iron/dsl/class.rb

@@ -0,0 +1,46 @@
+class Class
+  
+  # Provides a DSL-friendly way to set values.  Similar to attr_accessor, but
+  # supports setting values like so:
+  #
+  #   class Widget
+  #     dsl_accessor :size
+  #   end
+  #   @w = Widget.new
+  #   @w.size = 5  # normal setter, same as...
+  #   @w.size 5    # note the lack of explicit = sign
+  #   puts @w.size # still get reader access
+  #
+  # Useful in DslProxy blocks:
+  #
+  #   DslProxy.exec(Widget.new) do
+  #     size 10    # sets size to 10, as expected
+  #     size = 10  # fails, creates local variable 'size' instead of invoking Widget#size
+  #   end
+  #
+  def dsl_accessor(*keys)
+    keys.each do |key|
+      class_eval "def #{key}(val = :__UNDEFINED, &block); if val != :__UNDEFINED ; @#{key} = val ; elsif block ; @#{key} = block ; end ; @#{key}; end"
+      class_eval "def #{key}=(val); @#{key} = val; end"
+    end
+  end
+  
+  # Like #dsl_accessor, but adds imperative and query versions of the keys as well to set the
+  # flag to true and to query the true-ness of the flag.
+  #
+  #   class Widget
+  #     dsl_flag :heavy
+  #   end
+  #   @w = Widget.new
+  #   @w.heavy?  # => false
+  #   @w.heavy!  # now is true
+  #
+  def dsl_flag(*keys)
+    dsl_accessor(*keys)
+    keys.each do |key|
+      class_eval "def #{key}!; @#{key} = true; end"
+      class_eval "def #{key}?; @#{key} === true; end"
+    end
+  end
+  
+end

data/lib/iron/dsl/dsl_builder.rb

@@ -0,0 +1,14 @@
+# Provides a base class for building DSL (domain specific language) builder
+# classes, ie classes that define a minimal subset of methods and act as aggregators
+# of settings or functionality.  Similar to BasicObject in the standard library, but
+# has methods such as respond_to? and send that are required for any real DSL building
+# effort.
+class DslBuilder < Object
+  
+  # Remove all methods not explicitly desired
+  instance_methods.each do |m|
+    keepers = [:inspect, :send]
+    undef_method m if m =~ /^[a-z]+[0-9]?$/ && !keepers.include?(m)
+  end
+  
+end

data/lib/iron/dsl/dsl_proxy.rb

@@ -0,0 +1,176 @@
+# 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 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 receiver 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 respond_to? a method, any missing methods
+  # will be proxied to the enclosing context.
+  def self.exec(receiver, *to_yield, &block) # :yields: receiver
+    # Find the context within which the block was defined
+    context = ::Kernel.eval('self', block.binding)
+
+    # Create or re-use our proxy object
+    if context.respond_to?(:_to_dsl_proxy)
+      # If we're nested, we don't want/need a new dsl proxy, just re-use the existing one
+      proxy = context._to_dsl_proxy
+    else
+      # Not nested, create a new proxy for our use
+      proxy = DslProxy.new(context)
+    end
+
+    # Exec the block and return the result
+    proxy._proxy(receiver, *to_yield, &block)
+  end
+  
+  # Simple state setup
+  def initialize(context)
+    @_receivers = []
+    @_instance_original_values = {}
+    @_context = context
+  end
+  
+  def _proxy(receiver, *to_yield, &block) # :yields: receiver
+    # Sanity!
+    raise 'Cannot proxy with a DslProxy as receiver!' if receiver.respond_to?(:_to_dsl_proxy)
+    
+    if @_receivers.empty?
+      # On first proxy call, run each context instance variable, 
+      # and set it to ourselves so we can proxy it
+      @_context.instance_variables.each do |var|
+        unless var[0...2] == '@_'
+          value = @_context.instance_variable_get(var.to_s)
+          @_instance_original_values[var] = value
+          instance_eval "#{var} = value"
+        end
+      end
+    end
+
+    # Save the dsl target as our receiver for proxying
+    _push_receiver(receiver)
+
+    # Run the block with ourselves as the new "self", passing the given yieldable(s) or
+    # the receiver in case the code wants to disambiguate for some reason
+    to_yield = [receiver] if to_yield.empty?
+    to_yield = to_yield.first(block.arity)
+    result = instance_exec(*to_yield, &block)
+    
+    # Pop the last receiver off the stack
+    _pop_receiver
+    
+    if @_receivers.empty?
+      # Run each local instance variable and re-set it back to the context if it has changed during execution
+      #instance_variables.each do |var|
+      @_context.instance_variables.each do |var|
+        unless var[0...2] == '@_'
+          value = instance_eval("#{var}")
+          if @_instance_original_values[var] != value
+            @_context.instance_variable_set(var.to_s, value)
+          end
+        end
+      end
+    end
+    
+    return result
+  end
+  
+  # For nesting multiple proxies
+  def _to_dsl_proxy
+    self
+  end
+  
+  # Set the currently active receiver
+  def _push_receiver(receiver)
+    @_receivers.push receiver
+  end
+  
+  # Remove the currently active receiver, restore old receiver if nested
+  def _pop_receiver
+    @_receivers.pop
+  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)
+    #$stderr.puts "Method missing: #{method}"
+    if @_receivers.last.respond_to?(method)
+      #$stderr.puts "Proxy [#{method}] to receiver"
+      @_receivers.last.__send__(method, *args, &block)
+    else
+      #$stderr.puts "Proxy [#{method}] to context"
+      @_context.__send__(method, *args, &block)
+    end
+  end
+  
+  # Let anyone who's interested know what our proxied objects will accept
+  def respond_to?(method, include_private = false)
+    return true if method == :_to_dsl_proxy
+    @_receivers.last.respond_to?(method, include_private) || @_context.respond_to?(method, include_private)
+  end
+  
+  # Proxies searching for constants to the context, so that eg Kernel::foo can actually
+  # find Kernel - BasicObject does not partake in the global scope!
+  def self.const_missing(name)
+    #$stderr.puts "Constant missing: #{name} - proxy to context"
+    @_context.class.const_get(name)
+  end
+  
+end

data/spec/dsl/class_spec.rb

@@ -0,0 +1,33 @@
+describe Class do
+
+  context 'when using dsl_accessor' do
+    class MyBuilder < DslBuilder
+      dsl_accessor :process
+    end
+    
+    before do
+      @builder = MyBuilder.new
+    end
+    
+    it 'should set via =' do
+      @builder.process.should be_nil
+      @builder.process = 5
+      @builder.process.should == 5
+    end
+    
+    it 'should set via call' do
+      @builder.process.should be_nil
+      @builder.process 5
+      @builder.process.should == 5
+    end
+    
+    it 'should capture blocks' do
+      @builder.process do 
+        puts 'foo'
+      end
+      @builder.process.should be_a Proc
+    end
+    
+  end
+  
+end

data/spec/dsl/dsl_builder_spec.rb

@@ -0,0 +1,29 @@
+describe DslBuilder do
+
+  # TODO: break this out a bit...
+  it 'should allow using DSL-style accessors' do
+    class MyBuilder < DslBuilder
+      dsl_accessor :name
+      dsl_flag :flagged
+    end
+    builder = MyBuilder.new
+
+    # Test standalone
+    builder.name 'ProjectX'
+    builder.name.should == 'ProjectX'
+    
+    builder.flagged?.should be_false
+    builder.flagged = true
+    builder.flagged?.should be_true
+    builder.flagged = false
+    
+    # Test as part of DslProxy usage (common case)
+    DslProxy.exec(builder) do
+      name 'Project Omega'
+      flagged!
+    end
+    builder.name.should == 'Project Omega'
+    builder.flagged?.should be_true
+  end
+  
+end

data/spec/dsl/dsl_proxy_spec.rb

@@ -0,0 +1,110 @@
+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 = ControlBuilder.new
+    DslProxy.exec(receiver) do
+      respond_to?(:garbaz).should == false
+      respond_to?(:button).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 calling 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 proxy correctly even when nested' do
+    def outerfunc
+      5
+    end
+    @instance_var = nil
+    local_var = nil
+    DslProxy.exec(self) do
+      DslProxy.exec(Object.new) do
+        outerfunc.should == 5
+        @instance_var.should be_nil
+        local_var.should be_nil
+        @instance_var = 10
+        local_var = 11
+      end
+    end
+    @instance_var.should == 10
+    local_var.should == 11
+  end
+  
+  it 'should pass additional args to block as argument' do
+    l = lambda {|arg1, arg2| arg1 + arg2}
+    DslProxy.exec(Object.new, 5, 1, &l).should == 6
+  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

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+# Require our library
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'iron', 'dsl'))
+
+# Config RSpec options
+RSpec.configure do |config|
+  config.color = true
+  config.add_formatter 'documentation'
+  config.backtrace_clean_patterns = [/rspec/]
+end
+
+

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: iron-dsl
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Rob Morris
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Provides the DslProxy and DslBuilder classes plus DSL-friendly accessor
+  and flag support
+email:
+- rob@irongaze.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- History.txt
+- LICENSE
+- README.rdoc
+- Version.txt
+- lib/iron/dsl.rb
+- lib/iron/dsl/class.rb
+- lib/iron/dsl/dsl_builder.rb
+- lib/iron/dsl/dsl_proxy.rb
+- spec/dsl/class_spec.rb
+- spec/dsl/dsl_builder_spec.rb
+- spec/dsl/dsl_proxy_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/irongaze/iron-dsl
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: Powerful and concise construction helpers for Domain Specific Languages
+test_files: []