utilrb 0.2

data/lib/utilrb.rb

@@ -0,0 +1,2 @@
+require 'utilrb/kernel/require'
+require_dir(__FILE__)

data/lib/utilrb/array.rb

@@ -0,0 +1,2 @@
+require 'utilrb/kernel/require'
+require_dir(__FILE__)

data/lib/utilrb/array/to_s.rb

@@ -0,0 +1,16 @@
+class Array
+    def to_s
+	stack = (Thread.current[:array_to_s] ||= [])
+	if stack.include?(self)
+	    "..."
+	else
+	    begin
+		stack.push self
+		map { |obj| obj.to_s }.join(", ")
+	    ensure
+		stack.pop
+	    end
+	end
+    end
+end
+

data/lib/utilrb/common.rb

@@ -0,0 +1,50 @@
+module Utilrb
+    VERSION = "0.2" unless defined? Utilrb::VERSION
+
+    unless defined? UTILRB_FASTER_MODE
+	if ENV['UTILRB_FASTER_MODE'] == 'no'
+	    UTILRB_FASTER_MODE = nil
+	    STDERR.puts "Utilrb: not loading the C extension"
+	else
+	    begin
+		require 'utilrb/faster'
+		UTILRB_FASTER_MODE = true
+		STDERR.puts "Utilrb: loaded C extension" if ENV['UTILRB_FASTER_MODE']
+	    rescue LoadError => e
+		raise unless e.message =~ /no such file to load/
+		if ENV['UTILRB_FASTER_MODE'] == 'yes'
+		    raise LoadError, "unable to load Util.rb C extension: #{e.message}"
+		else
+		    UTILRB_FASTER_MODE = nil
+		end
+	    end
+	end
+    end
+
+    # Yields if the faster extension is not present
+    # This is used by Utilrb libraries to provide a 
+    # Ruby version if the C extension is not loaded
+    def self.unless_faster # :yield:
+	unless UTILRB_FASTER_MODE
+	    return yield if block_given?
+	end
+    end
+
+    # Yields if the faster extension is present. This is used for Ruby code
+    # which depends on methods in the C extension
+    def self.if_faster(&block)
+	require_faster(nil, &block)
+    end
+
+    # Yields if the faster extension is present, and 
+    # issue a warning otherwise. This is used for Ruby
+    # code which depends on methods in the C extension
+    def self.require_faster(name)
+	if UTILRB_FASTER_MODE
+	    yield if block_given?
+	elsif name
+	    STDERR.puts "Utilrb: not loading #{name} since the C extension is not available"
+	end
+    end
+end
+

data/lib/utilrb/enumerable.rb

@@ -0,0 +1,2 @@
+require 'utilrb/kernel/require'
+require_dir(__FILE__)

data/lib/utilrb/enumerable/null.rb

@@ -0,0 +1,18 @@
+# A null enumerator which can be used to seed sequence enumeration. See
+# Kernel#null_enum
+class NullEnumerator
+    def each; self end
+    include Enumerable
+end
+
+module Kernel
+    # returns always the same null enumerator, to avoid creating objects. 
+    # It can be used as a seed to #inject:
+    #
+    #   enumerators.inject(null_enum) { |a, b| a + b }.each do |element|
+    #   end
+    def null_enum
+	@@null_enumerator ||= NullEnumerator.new.freeze
+    end
+end
+

data/lib/utilrb/enumerable/random_element.rb

@@ -0,0 +1,16 @@
+module Enumerable
+    def random_element
+	if Array === self
+	    self[rand(size)]
+	elsif respond_to?(:to_ary)
+	    to_ary.random_element
+	elsif respond_to?(:size)
+	    element = rand(size)
+	    each_with_index { |e, i| return e if i == element }
+	    nil
+	elsif respond_to?(:to_a)
+	    to_a.random_element
+	end
+    end
+end
+

data/lib/utilrb/enumerable/sequence.rb

@@ -0,0 +1,24 @@
+# An enumerator which iterates on a sequence of enumerator
+class SequenceEnumerator
+    def initialize; @sequence = Array.new end
+    # Adds +object+ at the back of the sequence
+    def <<(object); @sequence << object; self end
+    alias :+ :<<
+
+    def each
+	@sequence.each { |enum| enum.each { |o| yield(o) } } if block_given?
+	self
+    end
+
+    include Enumerable
+end
+
+module Enumerable # :nodoc
+    # Builds a sequence of enumeration object.
+    #	([1, 2].enum_for + [2, 3]).each		=> 1, 2, 2, 3
+    def +(other_enumerator) # :nodoc
+	SequenceEnumerator.new << self << other_enumerator
+    end
+end
+
+

data/lib/utilrb/enumerable/uniq.rb

@@ -0,0 +1,61 @@
+require 'utilrb/common'
+require 'enumerator'
+require 'set'
+
+# Enumerator object which removes duplicate entries. See
+# Kernel#each_uniq
+class UniqEnumerator < Enumerable::Enumerator
+    def initialize(root, enum_with, args, key = nil)
+	super(root, enum_with, *args)
+	@key = key
+	@result = Hash.new
+    end
+
+    def each
+	if block_given?
+	    @result.clear
+	    result = @result
+	    super() do |v|
+		k = @key ? @key.call(v) : v
+
+		if !result.has_key?(k)
+		    result[k] = v
+		    yield(v)
+		end
+	    end
+
+	    result.values
+	else
+	    self
+	end
+    end
+
+    include Enumerable
+end
+
+class Object
+    # Enumerate removing the duplicate entries
+    def enum_uniq(enum_with = :each, *args, &filter)
+	UniqEnumerator.new(self, enum_with, args, filter)
+    end
+end
+
+Utilrb.unless_faster do
+    module Enumerable
+	# call-seq:
+	#  enum.each_uniq { |obj| ... }
+	# 
+	# Yields all unique values found in +enum+
+	# 
+	def each_uniq(&iterator)
+	    seen = Set.new
+	    each do |obj|
+		if !seen.include?(obj)
+		    seen << obj
+		    yield(obj)
+		end
+	    end
+	end
+    end
+end
+

data/lib/utilrb/exception.rb

@@ -0,0 +1,2 @@
+require 'utilrb/kernel/require'
+require_dir(__FILE__)

data/lib/utilrb/exception/full_message.rb

@@ -0,0 +1,8 @@
+
+class Exception
+    def full_message
+	first, *remaining = backtrace
+	"#{first}: #{message} (#{self.class})\n\tfrom " + remaining.join("\n\tfrom ")
+    end
+end
+

data/lib/utilrb/gc.rb

@@ -0,0 +1,2 @@
+require 'utilrb/kernel/require'
+require_dir(__FILE__)

data/lib/utilrb/gc/force.rb

@@ -0,0 +1,11 @@
+module GC
+    # Forcefully starts the GC even when GC.disable has been called
+    def self.force
+	already_enabled = !GC.enable
+	GC.start
+    ensure
+	GC.disable unless already_enabled
+    end
+end
+
+

data/lib/utilrb/hash.rb

@@ -0,0 +1,2 @@
+require 'utilrb/kernel/require'
+require_dir(__FILE__)

data/lib/utilrb/hash/slice.rb

@@ -0,0 +1,6 @@
+class Hash
+    def slice(*keys)
+	keys.inject({}) { |h, k| h[k] = self[k] if has_key?(k); h }
+    end
+end
+

data/lib/utilrb/hash/to_s.rb

@@ -0,0 +1,6 @@
+class Hash
+    def to_s
+	map { |k, v| "#{k} => #{v}" }.join(", ")
+    end
+end
+

data/lib/utilrb/hash/to_sym_keys.rb

@@ -0,0 +1,6 @@
+class Hash
+    def to_sym_keys
+	inject({}) { |h, (k, v)| h[k.to_sym] = v; h }
+    end
+end
+

data/lib/utilrb/kernel.rb

@@ -0,0 +1,2 @@
+require 'utilrb/kernel/require'
+require_dir(__FILE__)

data/lib/utilrb/kernel/arity.rb

@@ -0,0 +1,10 @@
+module Kernel
+    # Raises if +object+ can accept calls with exactly +arity+ arguments. 
+    # object should respond to #arity
+    def check_arity(object, arity)
+        unless object.arity == arity || (object.arity < 0 && object.arity > - arity - 2)
+            raise ArgumentError, "#{object} does not accept to be called with #{arity} argument(s)", caller(2)
+        end
+    end
+end
+

data/lib/utilrb/kernel/options.rb

@@ -0,0 +1,69 @@
+require 'utilrb/hash/to_sym_keys'
+require 'utilrb/hash/slice'
+module Kernel
+    # Partitions an option hash between known arguments and unknown
+    # arguments, with default value support. All option keys are
+    # converted to symbols for consistency.
+    #
+    # call-seq:
+    #   filter_options(option, hash)       -> known, unknown
+    #   filter_options(option, array)	   -> known, unknown
+    #   filter_options(nil, known_options) -> default_options, {}
+    #
+    def filter_options(options, option_spec)
+        options     = (options || Hash.new).to_sym_keys
+	# cannot use #to_sym_keys as option_spec can be an array
+	option_spec = option_spec.inject({}) { |h, (k, v)| h[k.to_sym] = v; h }
+
+	unknown_options = options.slice(*(options.keys - option_spec.keys))
+	known_options   = options.slice(*option_spec.keys)
+
+        # Set default values defined in the spec
+        option_spec.each_key do |k| 
+            value = option_spec[k]
+	    if !known_options.has_key?(k) && !value.nil?
+		known_options[k] ||= value
+	    end
+        end
+
+        return *[known_options, unknown_options]
+    end
+
+    # Validates an option hash, with default value support. See #filter_options
+    # 
+    # In the first form, +option_hash+ should contain keys which are also 
+    # in known_hash. The non-nil values of +known_hash+ are used as default
+    # values. In the second form, +known_array+ is an array of option
+    # keys. +option_hash+ keys shall be in +known_array+. +nil+ is treated 
+    # as an empty option hash, all keys are converted into symbols.
+    #
+    def validate_options(options, known_options)
+	opt, unknown = filter_options(options, known_options)
+	unless unknown.empty?
+	    not_valid = unknown.keys.map { |m| "'#{m}'" }.join(" ")
+	    raise ArgumentError, "unknown options #{not_valid}", caller(1)
+	end
+
+	opt
+    end
+
+    # call-seq:
+    #	validate_option(options, name, required, message) { |v| ... }
+    #	validate_option(options, name, required, message)
+    #
+    # Validates option +name+ in the +options+ hash. If required is true,
+    # raises ArgumentError if the option is not present. Otherwise, yields
+    # its value to an optional block, which should return if the value is
+    # valid, or false otherwise. If the value is invalid, raises ArgumentError
+    # with +message+ or a standard message.
+    def validate_option(options, name, required, message = nil)
+        if required && !options.has_key?(name)
+            raise ArgumentError, "missing required option #{name}"
+        elsif options.has_key?(name) && block_given?
+            if !yield(options[name])
+                raise ArgumentError, (message || "invalid option value #{options[name]} for #{name}")
+            end
+        end
+    end
+end
+

data/lib/utilrb/kernel/poll.rb

@@ -0,0 +1,24 @@
+module Kernel
+    # Yields every +cycle+ seconds
+    def poll(cycle)
+	loop do
+	    yield
+	    sleep(cycle)
+	end
+    end
+    # Yields every +cycle+ seconds until
+    # the block returns true.
+    def wait_until(cycle)
+        until yield
+	    sleep(cycle)
+	end
+    end
+    # Yields every +cycle+ seconds until
+    # the block returns false.
+    def wait_while(cycle)
+        while yield
+            sleep(cycle)
+        end
+    end
+end
+

data/lib/utilrb/kernel/require.rb

@@ -0,0 +1,12 @@
+module Kernel
+    # Require all .rb files in the +filename+ directory
+    def require_dir(filename)
+	dirname = filename.gsub(/.rb$/, '')
+	Dir.new(dirname).each do |file|
+	    if file =~ /\.rb$/
+		require File.join(dirname, file)
+	    end
+	end
+    end
+end
+

data/lib/utilrb/kernel/swap.rb

@@ -0,0 +1,2 @@
+require 'utilrb/common'
+Utilrb.require_faster('Kernel#swap!')

data/lib/utilrb/logger.rb

@@ -0,0 +1,3 @@
+require 'logger'
+require 'utilrb/kernel/require'
+require_dir(__FILE__)

data/lib/utilrb/logger/forward.rb

@@ -0,0 +1,15 @@
+class Logger
+    # Forward logger output methods to the logger attribute, so that
+    # we can do
+    #	MyModule.debug "debug_info"
+    # instead of 
+    #   MyModule.logger.debug "debug_info"
+    module Forward
+        [ :debug, :info, :warn, :error, :fatal, :unknown ].each do |level|
+            class_eval <<-EOF
+                def #{level}(*args, &proc); logger.#{level}(*args, &proc) end
+            EOF
+        end
+    end
+end
+

data/lib/utilrb/logger/hierarchy.rb

@@ -0,0 +1,34 @@
+require 'facet/module/dirname'
+require 'facet/kernel/constant'
+class Logger
+    # Define a hierarchy of loggers mapped to the module hierarchy.
+    # It defines the #logger accessor which either returns the logger
+    # attribute of the module, if one is defined, or its parent logger
+    # attribute.
+    # 
+    # module First
+    #   include Hierarchy
+    #   self.logger = Logger.new
+    #
+    #   module Second
+    #     include Hierarchy
+    #   end
+    # end
+    #
+    # Second.logger will return First.logger. If we do
+    # Second.logger = Logger.new, then this one would
+    # be returned.
+    module Hierarchy
+        attr_writer :logger
+        def logger
+            return @logger if defined?(@logger) && @logger
+            if kind_of?(Module)
+                constant(self.dirname).logger
+            else
+                self.class.logger
+            end
+        end
+    end
+end
+
+