og 0.7.0 → 0.8.0

data/vendor/extensions/_base.rb

@@ -0,0 +1,153 @@
+
+#
+# This file is 'required' by all files that implement standard class
+# extensions as part of the "Ruby/Extensions" project.
+#
+# The "Extensions" project requires 1.8.0 or greater to run, as it is too
+# much hassle at the moment to consider supporting older versions.  That may
+# one day be implemented if demand is there.  One option would be to require
+# "shim", so that we can assume all 1.8 library methods are implemented.
+#
+# This file is only of interest to developers of the package, so no detailed
+# documentation is included here.  However, by way of introduction, this is what
+# it's all about.  Each method that is implemented as part of this package is
+# done so through a framework implemented in this file.  Take the following
+# simple example:
+#
+#   ExtensionsProject.implement(Integer, :even?, :instance) do
+#     class Integer
+#       #
+#       # RDoc comments.
+#       # 
+#       def even?
+#         self % 2 == 0
+#       end
+#     end
+#   end
+#
+# This purposes of this are as follows:
+# - if the intended method (in this case IO.write) is already defined,
+#   we don't want to overwrite it (we issue a warning and move on)
+# - if the intended method is _not_ implemented as a result of the block,
+#   we have not done as we said, and an error is raised
+# - the ExtensionsProject class gathers information on which methods have
+#   been implemented, making for a very handy command-line reference (+rbxtm+)
+#
+# The <tt>ExtensionsProject.implement</tt> method is responsible for ensuring
+# these are so.  It gives us documentation, and some assurance that the
+# extensions are doing what we say they are doing.
+#
+
+# :enddoc:
+
+#
+# For what reason does Ruby define Module#methods, Module#instance_methods,
+# and Module#method_defined?, but not Module#instance_method_defined? ?
+#
+# No matter, extending standard classes is the name of the game here.
+#
+class Module
+  if Module.method_defined?(:instance_method_defined?)
+    STDERR.puts "Warning: Module#instance_method_defined? already defined; not overwriting"
+  else
+    def instance_method_defined?(_method)
+      instance_methods(true).find { |m| m == _method.to_s }
+    end
+  end
+
+  if Module.method_defined?(:module_method_defined?)
+    STDERR.puts "Warning: Module#module_method_defined? already defined; not overwriting"
+  else
+    def module_method_defined?(_method)
+      singleton_methods(true).find { |m| m == _method.to_s }
+    end
+  end
+end
+
+
+class ExtensionsProject
+
+  class << ExtensionsProject
+    @@extension_methods = []
+
+    #
+    # The list of methods implemented in this project.
+    #
+    def extension_methods
+      @@extension_methods
+    end
+
+    #
+    # Return the name of the project.  To be used in error messages, etc., for
+    # consistency.
+    #
+    def project_name
+      "Ruby/Extensions"
+    end
+
+    #
+    # Wraps around the implementation of a method, emitting a warning if the
+    # method is already defined.  Returns true to indicate - false to indicate
+    # failure (i.e. method is already defined).  Raises an error if the
+    # specified method is not actually implemented by the block.
+    #
+    def implement(_module, _method, _type=:instance)
+      raise "Internal error: #{__FILE__}:#{__LINE__}" unless
+        _module.is_a? Module and
+        _method.is_a? Symbol and
+        _type == :instance or _type == :class or _type == :module
+
+      fullname = _module.to_s + string_rep(_type) + _method.to_s
+
+      if _defined?(_module, _method, _type)
+        STDERR.puts "#{project_name}: #{fullname} is already defined; not overwriting"
+        return false
+      else
+        yield # Perform the block; presumably a method implementation.
+        if _method == :initialize and _type == :instance
+          # Special case; we can't verify this.
+          @@extension_methods<< "#{_module}::new"
+        else
+          unless _defined?(_module, _method, _type)
+            raise "#{project_name}: internal error: was supposed to implement " +
+              "#{fullname}, but it didn't!"
+          end
+          @@extension_methods << fullname
+        end
+        return true
+      end
+    end
+
+
+    # See whether the given module implements the given method, taking account
+    # of the type (class/instance) required.
+    def _defined?(_module, _method, _type)
+      case _type
+      when :instance
+        _module.instance_method_defined?(_method) # See definition above.
+      when :class, :module
+        _module.module_method_defined?(_method)   # See definition above.
+      end
+    end
+    private :_defined?
+
+
+    # Return the string representation of the given method type.
+    def string_rep(method_type)
+      case method_type
+      when :instance then "#"
+      when :class    then "."
+      when :module   then "."
+      else
+        nil
+      end
+    end
+    private :string_rep
+  end
+end    # class ExtensionsProject
+
+
+if VERSION < "1.8.0"
+  raise "#{ExtensionsProject.project_name} requires Ruby 1.8.0 at least (for now)"
+end
+

data/vendor/extensions/_template.rb

@@ -0,0 +1,36 @@
+#!/usr/local/bin/ruby -w
+# A template for new files in the project; of no interest to end users.  An
+# error will be raised if you +require+ it.
+#--
+# :enddoc:
+#
+# == extensions/XXX.rb
+#
+# Adds methods to the builtin XXX class. 
+#
+
+raise "Do not load this file!"
+
+require "extensions/_base"
+
+#
+# * Enumerable#build_hash
+#
+ExtensionsProject.implement(Enumerable, :build_hash) do
+  module Enumerable
+    #
+    # Like #map/#collect, but it generates a Hash.
+    #
+    #   [1,5,11].build_hash { |x| [x, x**2] }
+    #      => { 1 => 2, 5 => 25, 11 => 121 }
+    #
+    def build_hash
+      result = {}
+      self.each do |elt|
+        key, value = yield elt
+        result[key] = value
+      end
+      result
+    end
+  end
+end

data/vendor/extensions/all.rb

@@ -0,0 +1,21 @@
+#
+# == extensions/all.rb
+#
+# Require this file in order to access all of the standard class extensions
+# available, or require individual extension files to narrow the selection.
+#
+
+require 'extensions/array.rb'
+require 'extensions/binding.rb'
+require 'extensions/class.rb'
+require 'extensions/continuation.rb'
+require 'extensions/enumerable.rb'
+require 'extensions/hash.rb'
+require 'extensions/io.rb'
+require 'extensions/kernel.rb'
+require 'extensions/module.rb'
+require 'extensions/numeric.rb'
+require 'extensions/object.rb'
+require 'extensions/ostruct.rb'
+require 'extensions/string.rb'
+require 'extensions/symbol.rb'

data/vendor/extensions/array.rb

@@ -0,0 +1,68 @@
+#!/usr/local/bin/ruby -w
+#
+# == extensions/array.rb
+#
+# Adds methods to the builtin Array class. 
+#
+
+require "extensions/_base"
+
+#
+# * Array#select!
+#
+ExtensionsProject.implement(Array, :select!) do
+  class Array
+    #
+    # In-place version of Array#select.  (Counterpart to, and opposite of, the
+    # built-in #reject!)
+    #
+    def select!
+      reject! { |e| not yield(e) }
+    end
+  end
+end
+
+
+#
+# * Array#only
+#
+ExtensionsProject.implement(Array, :only) do
+  class Array
+    #
+    # Returns the _only_ element in the array.  Raises an IndexError if the array's size is not
+    # 1.
+    #
+    #   [5].only      # -> 5
+    #   [1,2,3].only  # -> IndexError
+    #   [].only       # -> IndexError
+    #
+    def only
+      unless size == 1
+        raise IndexError, "Array#only called on non-single-element array"
+      end
+      first
+    end
+  end
+end
+
+#
+# * Array#rand
+#
+ExtensionsProject.implement(Array, :rand) do
+  class Array
+    #
+    # Return a randomly-chosen (using Kernel.rand) element from the array.
+    #
+    #   arr = [48, 71, 3, 39, 15]
+    #   arr.rand     # -> 71
+    #   arr.rand     # -> 39
+    #   arr.rand     # -> 48
+    #   # etc.
+    #
+    def rand
+      idx = Kernel.rand(size)
+      at(idx)
+    end
+  end
+end
+

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