dslkit 0.2.0

data/lib/dslkit/polite.rb

@@ -0,0 +1,538 @@
+# = dslkit - Building Blocks for Domain Specific Languages (DSL)
+#
+# == Description
+#
+# This library contains recurring patterns, that are useful in the creation of
+# internal Domain Specific Languages (DSL) in Ruby.
+#
+# == Author
+#
+# Florian Frank <mailto:flori@ping.de>
+#
+# == License 
+#
+# This is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License Version 2 as published by the Free
+# Software Foundation: www.gnu.org/copyleft/gpl.html
+# 
+# == Download
+#
+# The latest version of this library can be downloaded at
+#
+# * http://rubyforge.org/frs?group_id=2248
+#
+# Online Documentation should be located at
+#
+# * http://dslkit.rubyforge.org
+#
+# == Examples
+#
+# Some nice examples on how to use dslkit are located in the examples/
+# subdirectory of this library.
+#
+module DSLKit
+  # This module contains some handy methods to deal with eigenclasses. Those
+  # are also known as virtual classes, singleton classes, metaclasses, plus all
+  # the other names Matz doesn't like enough to actually accept one of the
+  # names.
+  #
+  # The module can be included into other modules/classes to make the methods available.
+  module Eigenclass
+    # Returns the eigenclass of this object.
+    def eigenclass
+      class << self; self; end
+    end
+
+    # Evaluates the _block_ in context of the eigenclass of this object.
+    def eigenclass_eval(&block)
+      eigenclass.instance_eval(&block)
+    end
+  end
+
+  module ClassMethod
+    include Eigenclass
+
+    # Define a class method named _name_ using _block_. To be able to take
+    # blocks as arguments in the given _block_ Ruby 1.9 is required.
+    def class_define_method(name, &block)
+      eigenclass_eval { define_method(name, &block) }
+    end
+
+    # Define reader and writer attribute methods for all <i>*ids</i>.
+    def class_attr_accessor(*ids)
+      eigenclass_eval { attr_accessor(*ids) }
+    end
+
+    # Define reader attribute methods for all <i>*ids</i>.
+    def class_attr_reader(*ids)
+      eigenclass_eval { attr_reader(*ids) }
+    end
+
+    # Define writer attribute methods for all <i>*ids</i>.
+    def class_attr_writer(*ids)
+      eigenclass_eval { attr_writer(*ids) }
+    end
+
+    # I boycott attr!
+  end
+
+  module ThreadLocal
+    # Define a thread local variable named _name_ in this module/class. If the
+    # value _value_ is given, it is used to initialize the variable.
+    def thread_local(name, value = nil)
+      is_a?(Module) or raise TypeError, "receiver has to be a Module"
+
+      name = name.to_s
+      my_id = "__thread_local_#{__id__}__"
+
+      cleanup = eval <<-'EOT', TOPLEVEL_BINDING
+      lambda do |my_object_id|
+        my_id = "__thread_local_#{my_object_id}__"
+        begin 
+          old = Thread.critical
+          Thread.critical = true
+          for t in Thread.list
+            t[my_id] = nil if t[my_id]
+          end
+        ensure
+          Thread.critical = old
+        end
+      end
+      EOT
+      ObjectSpace.define_finalizer(self, cleanup)
+
+      define_method(name) do
+        Thread.current[my_id] ||= {}
+        Thread.current[my_id][name]
+      end
+
+      define_method("#{name}=") do |value|
+        Thread.current[my_id] ||= {}
+        Thread.current[my_id][name] = value
+      end
+
+      if value
+        Thread.current[my_id] = {}
+        Thread.current[my_id][name] = value
+      end
+      self
+    end
+
+    # Define a thread local variable for the current instance with name _name_.
+    # If the value _value_ is given, it is used to initialize the variable.
+    def instance_thread_local(name, value = nil)
+      sc = class << self
+        extend DSLKit::ThreadLocal
+        self
+      end
+      sc.thread_local name, value
+      self
+    end
+  end
+
+  module ThreadGlobal
+    # Define a thread global variable named _name_ in this module/class. If the
+    # value _value_ is given, it is used to initialize the variable.
+    def thread_global(name, value = nil)
+      is_a?(Module) or raise TypeError, "receiver has to be a Module"
+     
+      require 'thread'
+      name = name.to_s
+      var_name = "@__#{name}_#{__id__.abs}__"
+
+      lock = Mutex.new
+      modul = self
+
+      define_method(name) do
+        lock.synchronize { modul.instance_variable_get var_name }
+      end
+
+      define_method(name + "=") do |value|
+        lock.synchronize { modul.instance_variable_set var_name, value }
+      end
+
+      modul.instance_variable_set var_name, value if value
+      self
+    end
+
+    # Define a thread global variable for the current instance with name
+    # _name_. If the value _value_ is given, it is used to initialize the
+    # variable.
+    def instance_thread_global(name, value = nil)
+      sc = class << self
+        extend DSLKit::ThreadGlobal
+        self
+      end
+      sc.thread_global name, value
+      self
+    end
+  end
+
+  module InstanceExec
+    class << self
+      attr_accessor :pool
+      attr_accessor :count
+    end
+    self.count = 0
+    self.pool = []
+
+    # This is a pure ruby implementation of Ruby 1.9's instance_exec method. It
+    # executes _block_ in the context of this object while parsing <i>*args</i> into
+    # the block.
+    def instance_exec(*args, &block)
+      instance = self
+      id = instance_exec_fetch_symbol
+      InstanceExec.module_eval do
+        begin
+          define_method id, block
+          instance.__send__ id, *args
+        ensure
+          remove_method id if method_defined?(id)
+        end
+      end
+    ensure
+      InstanceExec.pool << id
+    end
+
+    private
+
+    # Fetch a symbol from a pool in thread save way. If no more symbols are
+    # available create a new one, that will be pushed into the pool later.
+    def instance_exec_fetch_symbol
+      old = Thread.critical
+      Thread.critical = true
+      if InstanceExec.pool.empty?
+        InstanceExec.count += 1
+        symbol = :"__instance_exec_#{InstanceExec.count}__"
+      else
+        symbol = InstanceExec.pool.shift
+      end
+      return symbol
+    ensure
+      Thread.critical = old
+    end
+  end
+
+  module Interpreter
+    include InstanceExec
+
+    # Interpret the string _source_ as a body of a block, while passing
+    # <i>*args</i> into the block.
+    #
+    # A small example explains how the method is supposed to be used and how
+    # the <i>*args</i> can be fetched:
+    #
+    #  class A
+    #    include DSLKit::Interpreter
+    #    def c
+    #      3
+    #    end
+    #  end
+    # 
+    #  A.new.interpret('|a,b| a + b + c', 1, 2) # => 6
+    #
+    # To use a specified binding see #interpret_with_binding.
+    def interpret(source, *args)
+      interpret_with_binding(source, binding, *args)
+    end
+
+    # Interpret the string _source_ as a body of a block, while passing
+    # <i>*args</i> into the block and using _my_binding_ for evaluation.
+    #
+    # A small example:
+    #
+    #  class A
+    #    include DSLKit::Interpreter
+    #    def c
+    #      3
+    #    end
+    #    def foo
+    #      b = 2 
+    #      interpret_with_binding('|a| a + b + c', binding, 1) # => 6
+    #    end
+    #  end
+    #  A.new.foo # => 6
+    #
+    # See also #interpret.
+    def interpret_with_binding(source, my_binding, *args)
+      path = '(interpret)'
+      if source.respond_to? :to_io
+        path = source.path if source.respond_to? :path
+        source = source.to_io.read
+      end
+      block = lambda { |*a| eval("lambda { #{source} }", my_binding, path).call(*a) }
+      instance_exec(*args, &block)
+    end
+  end
+
+  # This module contains the _constant_ method. For small example of its usage
+  # see the documentation of the DSLAccessor module.
+  module Constant
+    # Create a constant named _name_, that refers to value _value_. _value is
+    # frozen, if this is possible. If you want to modify/exchange a value use
+    # DSLAccessor#dsl_reader/DSLAccessor#dsl_accessor instead.
+    def constant(name, value)
+      value = value.freeze rescue value 
+      define_method(name) { value }
+    end
+  end
+
+  # The DSLAccessor module contains some methods, that can be used to make
+  # simple accessors for a DSL.
+  #
+  # 
+  #  class CoffeeMaker
+  #    extend DSLKit::Constant
+  #
+  #    constant :on,  :on
+  #    constant :off, :off
+  #
+  #    extend DSLKit::DSLAccessor
+  #
+  #    dsl_accessor(:state) { off } # Note: the off constant from above is used
+  #
+  #    dsl_accessor :allowed_states, :on, :off
+  #
+  #    def process
+  #      allowed_states.include?(state) or fail "Explode!!!"
+  #      if state == on
+  #        puts "Make coffee."
+  #      else
+  #        puts "Idle..."
+  #      end
+  #    end
+  #  end
+  #
+  #  cm = CoffeeMaker.new
+  #  cm.instance_eval do
+  #    state      # => :off
+  #    state on
+  #    state      # => :on
+  #    process    # => outputs "Make coffee."
+  #  end
+  #
+  # Note that DSLKit::SymbolMaker is an alternative for DSLKit::Constant in
+  # this example. On the other hand SymbolMaker can make debugging more
+  # difficult.
+  module DSLAccessor
+    # This method creates a dsl accessor named _name_. If nothing else is given
+    # as argument it defaults to nil. If <i>*default</i> is given as a single
+    # value it is used as a default value, if more than one value is given the
+    # _default_ array is used as the default value. If no default value but a
+    # block _block_ is given as an argument, the block is executed everytime
+    # the accessor is read <b>in the context of the current instance</b>.
+    #
+    # After setting up the accessor, the set or default value can be retrieved
+    # by calling the method +name+. To set a value one can call <code>name
+    # :foo</code> to set the attribute value to <code>:foo</code> or
+    # <code>name(:foo, :bar)</code> to set it to <code>[ :foo, :bar ]</code>.
+    def dsl_accessor(name, *default, &block)
+      variable = "@#{name}"
+      define_method(name) do |*args|
+        if args.empty?
+          result = instance_variable_get(variable)
+          if result.nil?
+            if default.empty?
+              block && instance_eval(&block)
+            elsif default.size == 1
+              default.first
+            else
+              default
+            end
+          else
+            result
+          end
+        else
+          instance_variable_set(variable, args.size == 1 ? args.first : args)
+        end
+      end
+    end
+
+    # This method creates a dsl reader accessor, that behaves exactly like a
+    # #dsl_accessor but can only be read not set.
+    def dsl_reader(name, *default, &block)
+      variable = "@#{name}"
+      define_method(name) do |*args|
+        if args.empty?
+          result = instance_variable_get(variable)
+          if result.nil?
+            if default.empty?
+              block && instance_eval(&block)
+            elsif default.size == 1
+              default.first
+            else
+              default
+            end
+          else
+            result
+          end
+        else
+          raise ArgumentError, "wrong number of arguments (#{args.size} for 0)"
+        end
+      end
+    end
+  end
+
+  # This module can be included in another module/class. It generates a symbol
+  # for every missing method that was called in the context of this
+  # module/class.
+  module SymbolMaker
+    # Returns a symbol (_id_) for every missing method named _id_.
+    def method_missing(id, *args)
+      if args.empty?
+        id
+      else
+        super
+      end
+    end
+  end
+
+  # This module can be used to extend another module/class. It generates
+  # symbols for every missing constant under the namespace of this
+  # module/class.
+  module ConstantMaker
+    # Returns a symbol (_id_) for every missing constant named _id_.
+    def const_missing(id)
+      id
+    end
+  end
+
+  module BlankSlate
+    # Creates an anonymous blank slate class, that only responds to the methods
+    # <i>*ids</i>. ids can be Symbols, Strings, and Regexps that have to match
+    # the method name with #===.
+    def self.with(*ids)
+      ids = ids.map { |id| Regexp === id ? id : id.to_s }
+      klass = Class.new
+      klass.instance_eval do
+        instance_methods.each do |m|
+          undef_method m unless m =~ /^__/ or ids.any? { |i| i === m }
+        end
+      end
+      klass
+    end
+  end
+
+  # See examples/recipe.rb and examples/recipe2.rb how this works at the
+  # moment.
+  module Deflect
+    # The basic Deflect exception
+    class DeflectError < StandardError; end
+
+    class << self
+      extend DSLKit::ThreadLocal
+
+      # A thread local variable, that holds a DeflectorCollection instance for
+      # the current thread.
+      thread_local :deflecting
+    end
+
+    # A deflector is called with a _class_, a method _id_, and its
+    # <i>*args</i>.
+    class Deflector < Proc; end
+
+    # This class implements a collection of deflectors, to make them available
+    # by emulating Ruby's message dispatch.
+    class DeflectorCollection
+      def initialize
+        @classes = {}
+      end
+
+      # Add a new deflector _deflector_ for class _klass_ and method name _id_,
+      # and return self.
+      #
+      def add(klass, id, deflector)
+        k = @classes[klass]
+        k = @classes[klass] = {} unless k
+        k[id.to_s] = deflector
+        self
+      end
+
+      # Return true if messages are deflected for class _klass_ and method name
+      # _id_, otherwise return false.
+      def member?(klass, id)
+        !!(k = @classes[klass] and k.key?(id.to_s))
+      end
+
+      # Delete the deflecotor class _klass_ and method name _id_. Returns the
+      # deflector if any was found, otherwise returns true.
+      def delete(klass, id)
+        if k = @classes[klass]
+          d = k.delete id.to_s
+          @classes.delete klass if k.empty?
+          d
+        end
+      end
+
+      # Try to find a deflector for class _klass_ and method _id_ and return
+      # it. If none was found, return nil instead.
+      def find(klass, id)
+        klass.ancestors.find do |k|
+          if d = @classes[k] and d = d[id.to_s]
+            return d
+          end
+        end
+      end
+    end
+
+    # Start deflecting method calls named _id_ to the _from_ class using the
+    # Deflector instance deflector.
+    def deflect_start(from, id, deflector)
+      old = Thread.critical
+      Thread.critical = true
+      Deflect.deflecting ||= DeflectorCollection.new
+      Deflect.deflecting.member?(from, id) and
+        raise DeflectError, "#{from}##{id} is already deflected"
+      Deflect.deflecting.add(from, id, deflector)
+      from.class_eval do
+        define_method(id) do |*args|
+          if Deflect.deflecting and d = Deflect.deflecting.find(self.class, id)
+            Thread.critical = old
+            d.call(self, id, *args)
+          else
+            Thread.critical = old
+            super
+          end
+        end
+      end
+    ensure
+      Thread.critical = old
+    end
+
+    # Return true if method _id_ is deflected from class _from_, otherwise
+    # return false.
+    def self.deflect?(from, id)
+      Deflect.deflecting && Deflect.deflecting.member?(from, id)
+    end
+
+    # Return true if method _id_ is deflected from class _from_, otherwise
+    # return false.
+    def deflect?(from, id)
+      Deflect.deflect?(from, id)
+    end
+
+    # Start deflecting method calls named _id_ to the _from_ class using the
+    # Deflector instance deflector. After that yield to the given block and
+    # stop deflecting again.
+    def deflect(from, id, deflector)
+      old = Thread.critical
+      Thread.critical = true
+      deflect_start(from, id, deflector)
+      yield
+    ensure
+      deflect_stop(from, id)
+      Thread.critical = old
+    end
+
+    # Stop deflection method calls named _id_ to class _from_.
+    def deflect_stop(from, id)
+      old = Thread.critical
+      Thread.critical = true
+      Deflect.deflecting.delete(from, id) or
+        raise DeflectError, "#{from}##{id} is not deflected from"
+      from.instance_eval { remove_method id }
+    ensure
+      Thread.critical = old
+    end
+  end
+end

data/lib/dslkit/rude.rb

@@ -0,0 +1,23 @@
+# This file contains some "rude" defaults that tamper with Ruby's open classes
+# to augment them with DSLKit methods. Although this shouldn't break anything, it's
+# perhaps better to require 'dslkit/polite' instead and include/extend your
+# classes with a finer granularity.
+require 'dslkit/polite'
+
+module DSLKit
+  class ::Module
+    include DSLKit::Constant
+    include DSLKit::DSLAccessor
+    include DSLKit::ClassMethod
+  end
+
+  class ::Object
+    include DSLKit::ThreadLocal
+    include DSLKit::ThreadGlobal
+    include DSLKit::InstanceExec
+    include DSLKit::Interpreter
+    include DSLKit::Deflect
+    include DSLKit::ThreadLocal
+    include DSLKit::Eigenclass
+  end
+end

data/lib/dslkit.rb

@@ -0,0 +1,2 @@
+# This file just requires 'dslkit/polite', which is the default.
+require 'dslkit/polite'

data/tests/runner.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+$:.unshift '../lib'
+$:.unshift 'tests'
+
+warn "Test polite."
+fork { load 'test_polite.rb' }
+Process.waitpid
+warn "Test rude."
+fork { load 'test_rude.rb' }
+Process.waitpid
+  # vim: set et sw=2 ts=2: