extensions 0.4.0

data/install.sh

@@ -0,0 +1,3 @@
+ruby install.rb config
+ruby install.rb setup
+ruby install.rb install

data/lib/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/lib/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/lib/extensions/all.rb

@@ -0,0 +1,17 @@
+#
+# == 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/class.rb'
+require 'extensions/enumerable.rb'
+require 'extensions/hash.rb'
+require 'extensions/io.rb'
+require 'extensions/numeric.rb'
+require 'extensions/object.rb'
+require 'extensions/ostruct.rb'
+require 'extensions/string.rb'
+require 'extensions/symbol.rb'

data/lib/extensions/array.rb

@@ -0,0 +1,24 @@
+#!/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
+

data/lib/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/lib/extensions/enumerable.rb

@@ -0,0 +1,183 @@
+#
+# == 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
+
+
+#
+# * 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
+