glue 0.13.0 → 0.14.0

data/vendor/extensions/binding.rb

@@ -0,0 +1,224 @@
+#!/usr/local/bin/ruby -w
+#
+# == extensions/binding.rb
+#
+# Adds methods to the builtin Binding class.
+#
+
+require "extensions/_base"
+require "extensions/continuation"
+
+  #
+  # Ruby's built-in Binding class doesn't contain any methods.  It is merely a "context" object
+  # that can be used in calls to <tt>Kernel.eval</tt>, like this:
+  #
+  #   def example(_binding)
+  #     return eval("x", _binding)
+  #   end
+  #
+  #   x = 55
+  #   current_binding = Kernel.binding
+  #   example(current_binding)                # -> 55
+  #
+  # The most useful method introduced to Binding by the _extensions_ package is
+  # Binding.of_caller.  It allows you to access the binding of the calling method, thus
+  # enabling you to access local variables in that scope.  The other methods are a convenient
+  # object-oriented facade for operations that you can already do with #eval as demonstrated
+  # above.  Here is an example that showcases all of the Binding methods included in
+  # _extensions_.
+  #
+  #   def example
+  #     Binding.of_caller do |b|
+  #       puts "x + y = #{b.eval('x + y')}"
+  #       puts "x = #{b[:x]}"
+  #       puts "Local variables: " + b.local_variables.join(', ')
+  #       b[:y] += 1
+  #       puts "Changed value of y in calling context to #{b[:y]}"
+  #       puts "Is 'z' defined in calling context?  " + (b.defined?(:z) ? 'Yes' : 'No')
+  #     end
+  #   end
+  #
+  #   x = 5
+  #   y = 17
+  #   example
+  #   y              # -> 18
+  #
+  # Binding.of_caller was written by Florian Gross.  The other methods were written by Tom
+  # Sawyer.
+  #
+class Binding
+end
+
+#
+# * Binding.of_caller
+#
+ExtensionsProject.implement(Binding, :of_caller, :class) do
+  class Binding
+      #
+      # This method returns the binding of the method that called your method, enabling you to
+      # access its local variables.  If you call it without being in a method, it will raise an
+      # Exception.
+      #
+      # === Example
+      #
+      #   def inc_counter
+      #     Binding.of_caller do |b|
+      #       eval("counter += 1", b)
+      #     end
+      #     #              <--- line (A)
+      #   end
+      #   counter = 0
+      #   inc_counter
+      #   inc_counter
+      #   counter           # -> 2
+      #
+      # === Warning
+      #
+      # <tt>Binding.of_caller</tt> must be the _last_ method call in the method.  For example,
+      # if you insert some code at line *A* in the example above, an Exception will be raised.
+      # You'll get away with a simple assignment, but anything involving a method call is
+      # trouble.
+      #
+      # === Explanation
+      #
+      # It works by installing a temporary trace_func (see Kernel.set_trace_func).  This makes
+      # available -- to the trace function -- the binding of a method after it has returned.
+      # Using a continuation, <tt>Binding.of_caller</tt> will let _your_ method return,
+      # retrieve the binding, and return to the <tt>of_caller</tt> call with that binding in
+      # hand.  This time it executes the block.
+      #
+      # Because it is actually running <tt>Binding.of_caller</tt> twice, and returning from
+      # your method twice, any code between the <tt>of_caller</tt> call and the end of your
+      # method will be run twice.  This is obviously not desirable, so an Exception is raised
+      # if any code is found.
+      #
+      # See the thread around ruby-talk:109607 for more discussion.
+      #
+      # === Extra Warning
+      #
+      # If you have a trace function in place, <tt>Binding.of_caller</tt> will destroy that.
+      # Ruby does not allow you to access the current trace function, so it can't be restored
+      # afterwards.  XXX: will this clash with the profiler and/or debugger?
+      #
+      # === Credits
+      #
+      # <tt>Binding.of_caller</tt> was written by Florian Frank.
+      #
+    def Binding.of_caller(&block)
+      old_critical = Thread.critical
+      Thread.critical = true
+      count = 0
+      cc, result, error = Continuation.create(nil, nil)
+      error.call if error
+
+      tracer = lambda do |*args|
+        type, context = args[0], args[4]
+        if type == "return"
+          count += 1
+          # First this method and then calling one will return --
+          # the trace event of the second event gets the context
+          # of the method which called the method that called this
+          # method.
+          if count == 2
+            # It would be nice if we could restore the trace_func
+            # that was set before we swapped in our own one, but
+            # this is impossible without overloading set_trace_func
+            # in current Ruby.
+            set_trace_func(nil)
+            cc.call(eval("binding", context), nil)
+          end
+        elsif type != "line"
+          set_trace_func(nil)
+          error_msg = "Binding.of_caller used in non-method context or " +
+            "trailing statements of method using it aren't in the block."
+          cc.call(nil, lambda { raise(Exception, error_msg ) })
+        end
+      end
+
+      unless result
+        set_trace_func(tracer)
+        return nil
+      else
+        Thread.critical = old_critical
+        yield result
+      end
+    end
+  end  # class Binding
+end
+
+
+#
+# * Binding#eval
+#
+ExtensionsProject.implement(Binding, :eval, :instance) do
+  class Binding
+      #
+      # Evaluates the given string in the context of this binding.
+      #
+    def eval(str)
+      Kernel.eval(str, self)
+    end
+  end
+end
+
+
+#
+# * Binding#local_variables
+#
+ExtensionsProject.implement(Binding, :local_variables, :instance) do
+  class Binding
+      #
+      # Returns the variables that are local to this binding.
+      #
+    def local_variables
+      self.eval('local_variables')
+    end
+  end
+end
+
+
+#
+# * Binding#[]
+#
+ExtensionsProject.implement(Binding, :[], :instance) do
+  class Binding
+      #
+      # Returns the value of the given variable in this binding.
+      #
+    def [](variable)
+      self.eval(variable.to_s)
+    end
+  end
+end
+
+
+#
+# * Binding#[]=
+#
+ExtensionsProject.implement(Binding, :[]=, :instance) do
+  class Binding
+      #
+      # Sets the given variable (in this binding) to the given value.
+      #
+    def []=(variable, value)
+      self.eval("lambda { |v| #{variable} = v }").call(value)
+    end
+  end
+end
+
+
+#
+# * Binding#defined?
+#
+ExtensionsProject.implement(Binding, :defined?, :instance) do
+  class Binding
+      #
+      # Evaluates <tt>defined?</tt> in this binding.
+      #
+    def defined?(variable)
+      self.eval("defined?(#{variable})")
+    end
+  end
+end
+
+

data/vendor/extensions/class.rb

@@ -0,0 +1,50 @@
+#!/usr/local/bin/ruby -w
+#
+# == extensions/class.rb
+#
+# Adds methods to the builtin Class class. 
+#
+
+require "extensions/_base"
+
+ExtensionsProject.implement(Class, :autoinit) do
+  class Class
+    #
+    # A shorthand for the common chore of assigning initialize's parameters to
+    # instance variables.  For example:
+    #  
+    #   class Circle
+    #
+    #     attr_reader :radius, :location, :area
+    #
+    #     autoinit(:radius, :location) do
+    #       @area = Math::PI * @radius ** 2
+    #     end
+    #
+    #   end
+    #
+    # A TypeError is raised unless all the arguments to +autoinit+ are strings
+    # or symbols.
+    #
+    #--
+    # Taken from ruby-talk:11668, by Avi Bryant.
+    def autoinit(*args, &block) # :yield:
+      unless args.all? { |a| Symbol === a or String === a }
+        raise TypeError, "All arguments must be symbols or strings"
+      end
+      block = proc {} if block.nil?
+      define_method(:__init_proc) { block }
+      params = args.join(", ")
+      vars = args.map { |a| "@#{a}" }.join(", ")
+
+      code = %{
+          def initialize(#{params})
+            #{vars} = #{params}
+            instance_eval(&__init_proc)
+          end
+        }
+      class_eval code
+    end
+  end
+end
+

data/vendor/extensions/continuation.rb

@@ -0,0 +1,71 @@
+#!/usr/local/bin/ruby -w
+#
+# == extensions/continuation.rb
+#
+# Adds methods to the builtin Continuation class. 
+#
+
+require "extensions/_base"
+
+#
+# * Continuation.create
+#
+ExtensionsProject.implement(Continuation, :create, :class) do
+  class Continuation
+    #
+    # <tt>Continuation.create</tt> offers a nicer interface for creating continuations than
+    # <tt>Kernel.callcc</tt>.
+    # 
+    # === Example
+    #
+    # Count down from 10 to 0 using a continuation.
+    #
+    #   continuation, counter = Continuation.create(10)
+    #   puts counter
+    #   continuation.call(counter - 1) if counter > 0
+    #
+    # Implement a workalike of <tt>Array#inject</tt> using continuations.  For simplicity's
+    # sake, this is not fully compatible with the real <tt>#inject</tt>.
+    #
+    #   class Array
+    #     def cc_inject( value=nil )
+    #       copy = self.clone
+    #       cc, result, item = Continuation.create( value, nil )
+    #       next_item = copy.shift 
+    #       if result and item
+    #         cc.call( yield(result, item), next_item ) 
+    #       elsif next_item
+    #         cc.call( next_item, result ) 
+    #       end
+    #       result 
+    #     end 
+    #   end
+    #
+    #   [1,2,3,4,5].cc_inject { |acc, n| acc + n }       # -> 15
+    #
+    # === Explanation
+    #
+    # I've got no idea how it works.  TODO: work it out.  In particular, what do the arguments
+    # do?  And what the hell is going on in #cc_inject???!?
+    #
+    # === See Also
+    #
+    # This method is included in the 'extensions' package primarily to support
+    # Binding.of_caller.
+    #
+    # === Credits
+    #
+    # <tt>Continuation.create</tt> was written and demonstrated by Florian Gross.  See
+    # ruby-talk:94681.
+    #
+    def Continuation.create(*args, &block)
+      cc = nil
+      result = callcc { |c|
+        cc = c
+        block.call(cc) if block and args.empty?
+      }
+      result ||= args
+      return *[cc, *result]
+    end
+  end
+end

data/vendor/extensions/enumerable.rb

@@ -0,0 +1,250 @@
+#
+# == extensions/enumerable.rb
+#
+# Adds methods to the builtin Enumerable module. 
+#
+
+require "extensions/_base"
+
+#
+# * Enumerable#build_hash
+#
+ExtensionsProject.implement(Enumerable, :build_hash) do
+  module Enumerable
+    #
+    # Like <tt>#map</tt>/<tt>#collect</tt>, but it generates a Hash.  The block
+    # is expected to return two values: the key and the value for the new hash.
+    #   numbers  = (1..3)
+    #   squares  = numbers.build_hash { |n| [n, n*n] }   # 1=>1, 2=>4, 3=>9
+    #   sq_roots = numbers.build_hash { |n| [n*n, n] }   # 1=>1, 4=>2, 9=>3
+    #
+    def build_hash
+      result = {}
+      self.each do |elt|
+        key, value = yield elt
+        result[key] = value
+      end
+      result
+    end
+  end
+
+  # There was a bug in Hash which causes the above code to issue a warning when
+  # used with a Hash.  That was fixed on 2003-10-24.
+  if RUBY_RELEASE_DATE < "2003-10-25"
+    class Hash #:nodoc:
+      def build_hash
+        result = {}
+        self.each_pair do |k, v|
+          key, value = yield(k, v)
+          result[key] = value
+        end
+        result
+      end
+    end
+  end
+end
+
+
+#
+# Enumerable#mapf
+#
+ExtensionsProject.implement(Enumerable, :mapf) do
+  module Enumerable
+    #
+    # "map function"
+    #   enum.mapf(:x)
+    # is short for
+    #   enum.map { |elt| elt.x }
+    #
+    def mapf(message)
+      self.map { |elt| elt.send(message) }
+    end
+  end
+end
+
+
+#
+# Enumerable#collectf
+#
+ExtensionsProject.implement(Enumerable, :collectf) do
+  module Enumerable
+    alias collectf mapf
+  end
+end
+
+
+#
+# * Enumerable#includes?
+#
+ExtensionsProject.implement(Enumerable, :includes?) do
+  module Enumerable
+    alias includes? include?
+  end
+end
+
+
+#
+# * Enumerable#contains?
+#
+ExtensionsProject.implement(Enumerable, :contains?) do
+  module Enumerable
+    alias contains? include?
+  end
+end
+
+
+#
+# * Enumerable#has?
+#
+ExtensionsProject.implement(Enumerable, :has?) do
+  module Enumerable
+    alias has? include?
+  end
+end
+
+
+#
+# * Enumerable#map_with_index
+#
+ExtensionsProject.implement(Enumerable, :map_with_index) do
+  module Enumerable
+    #
+    # Same as Enumerable#map, but the index is yielded as well.  See
+    # Enumerable#each_with_index.
+    #   puts files.map_with_index { |fn, idx| "#{idx}. #{fn}" }
+    #   print "Please select a file (0-#{files.size}): "
+    #
+    def map_with_index
+      result = []
+      self.each_with_index do |elt, idx|
+        result << yield(elt, idx)
+      end
+      result
+    end
+  end
+end
+
+
+#
+# * Enumerable#collect_with_index
+#
+ExtensionsProject.implement(Enumerable, :collect_with_index) do
+  module Enumerable
+    alias  collect_with_index  map_with_index
+  end
+end
+
+
+#
+# * Enumerable#partition_by
+#
+ExtensionsProject.implement(Enumerable, :partition_by) do
+  module Enumerable
+    #
+    # See Enumerable#partition for the background.  #partition_by is best
+    # explained by example.
+    #
+    #   (1..5).partition_by { |n| n % 3 } 
+    #        # -> { 0 => [3], 1 => [1, 4], 2 => [2,5] } 
+    #
+    #   ["I had", 1, "dollar and", 50, "cents"].partition_by { |e| e.class }
+    #        # -> { String => ["I had","dollar and","cents"], Fixnum => [1,50] } 
+    #
+    # #partition_by is used to group items in a collection by something they
+    # have in common.  The common factor is the key in the resulting hash, the
+    # array of like elements is the value.
+    #
+    def partition_by
+      result = {}
+      self.each do |e|
+        value = yield e
+        (result[value] ||= []) << e
+      end
+      result
+    end
+  end
+end
+
+
+#
+# * Enumerable#none?
+#
+ExtensionsProject.implement(Enumerable, :none?) do
+  module Enumerable
+    #
+    # Enumerable#none? is the logical opposite of the builtin method Enumerable#any?.  It
+    # returns +true+ if and only if _none_ of the elements in the collection satisfy the
+    # predicate.
+    #
+    # If no predicate is provided, Enumerable#none? returns +true+ if and only if _none_ of the
+    # elements have a true value (i.e. not +nil+ or +false+).
+    #
+    #   [].none?                      # true
+    #   [nil].none?                   # true
+    #   [5,8,9].none?                 # false
+    #   (1...10).none? { |n| n < 0 }  # true
+    #   (1...10).none? { |n| n > 0 }  # false
+    #
+    def none?  # :yield: e
+      if block_given?
+        not self.any? { |e| yield e }
+      else
+        not self.any?
+      end
+    end
+  end
+end
+
+
+#
+# * Enumerable#one?
+#
+ExtensionsProject.implement(Enumerable, :one?) do
+  module Enumerable
+    #
+    # Enumerable#one? returns +true+ if and only if <em>exactly one</em> element in the
+    # collection satisfies the given predicate.
+    #
+    # If no predicate is provided, Enumerable#one? returns +true+ if and only if <em>exactly
+    # one</em> element has a true value (i.e. not +nil+ or +false+).
+    #
+    #   [].one?                      # false
+    #   [nil].one?                   # false
+    #   [5].one?                     # true
+    #   [5,8,9].one?                 # false
+    #   (1...10).one? { |n| n == 5 } # true
+    #   (1...10).one? { |n| n < 5 }  # false
+    #
+    def one?  # :yield: e
+      matches = 0
+      if block_given?
+        self.each do |e|
+          if yield(e)
+            matches += 1
+            return false if matches > 1
+          end
+        end
+        return (matches == 1)
+      else
+        one? { |e| e }
+      end
+    end
+  end
+end
+
+
+#
+# * Object.in?
+# This has special treatment: it's included here and in object.rb, so we don't
+# want a warning if it's alredy defined.
+#
+unless Object.method_defined?(:in?)
+  ExtensionsProject.implement(Object, :in?) do
+    class Object
+      def in?(enumerable) # :nodoc: It's documented in object.rb.
+        enumerable.include?(self)
+      end
+    end
+  end
+end
+