facets 1.3.3 → 1.4.0

data/lib/facets/more/inheritor.rb

@@ -1,21 +1,27 @@
-#--
-# Inheritor
+# = inheritor.rb
 #
-# Copyright (c) 2005 Thomas Sawyer
+# == Copyright (c) 2005 Thomas Sawyer
 #
-# Permission is granted for use, copying, modification, distribution,
-# and distribution of modified versions of this work as long as the
-# above copyright notice is included.
+#   Ruby License
 #
-# ==========================================================================
-#  Revision History
-# ==========================================================================
-#  2005.10.01  trans
-#  * created
-# ==========================================================================
-#++
-
-# :title: Inheritor
+#   This module is free software. You may use, modify, and/or redistribute this
+#   software under the same terms as Ruby.
+#
+#   This program is distributed in the hope that it will be useful, but WITHOUT
+#   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#   FOR A PARTICULAR PURPOSE.
+#
+# == Author(s)
+#
+# * Thomas Sawyer
+
+# Author::    Thomas Sawyer
+# Copyright:: Copyright (c) 2006 Thomas Sawyer
+# License::   Ruby License
+
+require 'facets/more/classinherit'
+
+# = Inheritor
 #
 # Inheritor providse a means to store and inherit data via
 # the class heirarchy. An inheritor creates two methods
@@ -39,8 +45,9 @@
 #   X.x => [:a]
 #   Y.x => [:a, :b]
 #
-
-require 'facets/more/classinherit'
+# It is interesting to note that the only reason inheritor is needed at all
+# is becuase Ruby does not allow modules to be inherited at the class-level, or
+# conversely that the "class-levels" of classes are not modules instead.
 
 class Object
 
@@ -69,15 +76,17 @@ class Object
       end
     end
 
+    # TODO This is an issue if you try to include a module
+    # into Module or Class itself. How to fix?
+
     # if the object is a module (not a class or other object)
     if self == Class or self == Module
       class_eval &deflambda
     elsif is_a?(Class)
       (class << self; self; end).class_eval &deflambda
     elsif is_a?(Module)
-      class_inherit &deflambda      
-      #class_inherit &deflambda
-    else
+      class_inherit &deflambda
+    else # other Object
       (class << self; self; end).class_eval &deflambda
     end
 
@@ -87,7 +96,6 @@ class Object
 end
 
 
-
 #  _____         _
 # |_   _|__  ___| |_
 #   | |/ _ \/ __| __|

data/lib/facets/more/interval.rb

@@ -1,29 +1,33 @@
-#--
-# Interval
+# = interval.rb
 #
-# Copyright (c) 2004,2005 Thomas Sawyer
+# == Copyright (c) 2004 Thomas Sawyer
 #
-# Ruby License
+#   Ruby License
 #
-# This module is free software. You may use, modify, and/or redistribute this
-# software under the same terms as Ruby.
+#   This module is free software. You may use, modify, and/or redistribute this
+#   software under the same terms as Ruby.
 #
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE.
+#   This program is distributed in the hope that it will be useful, but WITHOUT
+#   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#   FOR A PARTICULAR PURPOSE.
 #
+# == Author(s)
 #
-# ==========================================================================
-# Revision History ::
-# --------------------------------------------------------------------------
-#  04.06   Trans    * Minor modifications to documentation.
-# ==========================================================================
+# * Thomas Sawyer
 #
-# NOTE Still need to tie in Infinity.
+# == Developer Notes
 #
-#++
+#   TODO Still need to tie in Infinity.
+
+# Author::    Thomas Sawyer
+# Copyright:: Copyright (c) 2006 Thomas Sawyer
+# License::   Ruby License
+
+require 'facets/more/multiton'
+require 'facets/more/enumerablepass'
+#require 'facets/more/infinity'
 
-#:title: Interval
+# = Interval
 #
 # While Ruby support the Range class out of the box, is does not quite
 # fullfil the role od a real Interval class. For instance, it does
@@ -54,14 +58,6 @@
 #   i = Interval[1,3]
 #   i.to_a(1,2)  #=> [1.0,1.5,2.0,2.5,3.0]
 #
-# == Author(s)
-#
-# * Thomas Sawyer
-#
-
-require 'facets/more/multiton'
-require 'facets/more/enumerablepass'
-#require 'facets/more/infinity'
 
 class Interval
 

data/lib/facets/more/ioredirect.rb

@@ -1,44 +1,40 @@
-#--
-# IORedirect
+# = ioredirect.rb
 #
-# Copyright (C) 2002 Paul Brannan <paul@atdesk.com>
-# (Ported from Ruby Treasures)
+# == Copyright (C) 2002 Paul Brannan
 #
-# Ruby License
+#   Ruby License
 #
-# This module is free software. You may use, modify, and/or redistribute this
-# software under the same terms as Ruby.
+#   This module is free software. You may use, modify, and/or redistribute this
+#   software under the same terms as Ruby.
 #
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE.
+#   This program is distributed in the hope that it will be useful, but WITHOUT
+#   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#   FOR A PARTICULAR PURPOSE.
 #
+# == Special Thanks
 #
-# ==========================================================================
-# Revision History ::
-# --------------------------------------------------------------------------
-#  2004-09  Trans    * Ported to Calibre.
-# ==========================================================================
-#++
-
-#:title: IORedirect
+# IORedirect was ported from Paul Brannan's Ruby Treasures.
+#
+# == Author(s)
+#
+# * Paul Brannan
+
+# Author::    Paul Brannan
+# Copyright:: Copyright (c) 2002 Paul Brannan <paul@atdesk.com>
+# License::   Ruby License
+
+# = IORedirect
 #
 # A class to redirect $stdout, or other IO object, to a StringIO object,
 # or any other object with a write() method.
 #
 # == Synopsis
 #
-#   require 'mega/io-redirect'
-#
 #   s = StringIO.new
 #   r = Redirector.redirect($stdout, s) do
 #     $stdout.puts "this is a test"
 #   end
 #
-# == Author(s)
-#
-# * Paul Brannan
-#
 
 class IORedirect
 
@@ -54,7 +50,7 @@ class IORedirect
   # Start redirection, if it has not already been started.
   def start
     raise "Redirection already in progress" if @t
-    tmp = @from.dup        
+    tmp = @from.dup
     r, w = IO.pipe
     @from.reopen(w)
     @t = Thread.new do

data/lib/facets/more/json.rb

@@ -1,26 +1,40 @@
-#--
-# JSON library for Ruby
+# = json.rb
 #
-# Copyright (c) 2006, Florian Frank
+# == Copyright (c) 2006 Florian Frank
 #
-# 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
+#   GNU General Public License
 #
-# Original Version (0.4.1) Download
+#   This program is free software; you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation; either version 2 of the License, or (at
+#   your option) any later version.
 #
-# The latest version of this library can be downloaded at
+#   This program is distributed in the hope that it will be useful, but
+#   WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#   General Public License for more details.
 #
-# * http://rubyforge.org/frs?group_id=953
+#   You should have received a copy of the GNU General Public License
+#   along with this program; if not, write to the Free Software
+#   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+#
+# == Author(s)
 #
-# Online Documentation should be located at
+# * Florian Frank
 #
+# == Additional Information
+#
+# The latest version of this library can be downloaded at:
+# * http://rubyforge.org/frs?group_id=953
+#
+# Online Documentation should be located at:
 # * http://json.rubyforge.org
-#++
 
-($VERSION ||= {})['json'] = '0.4.1'
+# Author::    Florian Frank <mailto:flori@ping.de>
+# Copyright:: Copyright (c) 2006 Florian Frank
+# License::   GNU General Public License (GPL)
 
-# :title: JSON
+# = JSON library for Ruby
 #
 # Ruby support of Javascript Object Notation.
 #
@@ -114,10 +128,6 @@
 # pretty_unparse output to the console, that work analogous to Kernel#p and
 # Kernel#pp.
 #
-# == Author(s)
-#
-# Florian Frank <mailto:flori@ping.de>
-#
 
 require 'strscan'
 

data/lib/facets/more/lazy.rb

@@ -0,0 +1,238 @@
+# = lazy.rb
+#
+# == Copyright (c) 2005 MenTaLguY
+#
+#    Ruby License
+#
+#   This module is free software. You may use, modify, and/or redistribute this
+#   software under the same terms as Ruby.
+#
+#   This program is distributed in the hope that it will be useful, but WITHOUT
+#   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#   FOR A PARTICULAR PURPOSE.
+#
+# == Author(s)
+#
+# * MenTaLguY
+
+# Author::    MenTaLguY
+# Copyright:: Copyright (c) 2005 MenTaLguY <mental@rydia.net>
+# License::   Ruby License
+
+# = Lazy
+#
+# Everything you need for Lazy evaluation in Ruby.
+
+module Lazy
+
+  # Raised when a demanded computation diverges (e.g. if it tries to directly
+  # use its own result)
+
+  class DivergenceError < Exception #:nodoc:
+    def initialize( message="Computation diverges" )
+      super( message )
+    end
+  end
+
+  # Wraps an exception raised by a lazy computation.
+  #
+  # The reason we wrap such exceptions in LazyException is that they need to
+  # be distinguishable from similar exceptions which might normally be raised
+  # by whatever strict code we happen to be in at the time.
+
+  class LazyException < DivergenceError #:nodoc:
+    # the original exception
+    attr_reader :reason
+
+    def initialize( reason )
+      @reason = reason
+      super( "Exception in lazy computation: #{ reason } (#{ reason.class })" )
+      set_backtrace( reason.backtrace.dup ) if reason
+    end
+  end
+
+  # = Promise
+  #
+  # A handle for a promised computation.  They are transparent, so that in
+  # most cases, a promise can be used as a proxy for the computation's result
+  # object.  The one exception is truth testing -- a promise will always look
+  # true to Ruby, even if the actual result object is nil or false.
+  #
+  # If you want to test the result for truth, get the unwrapped result object
+  # via Kernel.demand.
+
+  class Promise
+
+    alias __class__ class #:nodoc:
+    instance_methods.each { |m| undef_method m unless m =~ /^__/ }
+
+    def initialize( &computation ) #:nodoc:
+      @computation = computation
+    end
+    def __synchronize__ #:nodoc:
+      yield
+    end
+
+    # create this once here, rather than creating a proc object for
+    # every evaluation
+    diverges = lambda { raise DivergenceError.new }
+    def diverges.inspect
+      "DIVERGES"
+    end
+    DIVERGES = diverges
+
+    def __result__ #:nodoc:
+      __synchronize__ do
+        if @computation
+          raise LazyException.new( @exception ) if @exception
+
+          computation = @computation
+          @computation = DIVERGES # trap divergence due to over-eager recursion
+
+          begin
+            @result = demand( computation.call( self ) )
+            @computation = nil
+          rescue DivergenceError
+            raise
+          rescue Exception => exception
+            # handle exceptions
+            @exception = exception
+            raise LazyException.new( @exception )
+          end
+        end
+
+        @result
+      end
+    end
+
+    def inspect #:nodoc:
+      __synchronize__ do
+        if @computation
+          "#<#{ __class__ } computation=#{ @computation.inspect }>"
+        else
+          @result.inspect
+        end
+      end
+    end
+
+    def respond_to?( message ) #:nodoc:
+      message = message.to_sym
+      message == :__result__ or
+      message == :inspect or
+      __result__.respond_to? message
+    end
+
+    def method_missing( *args, &block ) #:nodoc:
+      __result__.__send__( *args, &block )
+    end
+  end
+
+  # = PromiseSafe
+  #
+  # Thread safe version of Promise class.
+
+  class PromiseSafe < Promise
+    def __synchronize__ #:nodoc:
+      current = Thread.current
+
+      Thread.critical = true
+      unless @computation
+        # fast path for evaluated thunks
+        Thread.critical = false
+        yield
+      else
+        if @owner == current
+          Thread.critical = false
+          raise DivergenceError.new
+        end
+        while @owner # spinlock
+          Thread.critical = false
+          Thread.pass
+          Thread.critical = true
+        end
+        @owner = current
+        Thread.critical = false
+
+        begin
+          yield
+        ensure
+          @owner = nil
+        end
+      end
+    end
+  end
+
+  # = Future
+  #
+  # Future class subclasses PromiseSafe.
+
+  class Future < PromiseSafe
+    def initialize( &computation ) #:nodoc:
+      result = nil
+      exception = nil
+
+      thread = Thread.new do
+        begin
+          result = computation.call( self )
+        rescue Exception => exception
+        end
+      end
+
+      super() do
+        raise DivergenceError.new if Thread.current == thread
+        thread.join
+        raise exception if exception
+        result
+      end
+    end
+  end
+
+end
+
+
+module Kernel
+
+  # The promise() function is used together with demand() to implement
+  # lazy evaluation.  It returns a promise to evaluate the provided
+  # block at a future time.  Evaluation can be demanded and the block's
+  # result obtained via the demand() function.
+  #
+  # Implicit evaluation is also supported: the first message sent to it will
+  # demand evaluation, after which that message and any subsequent messages
+  # will be forwarded to the result object.
+  #
+  # As an aid to circular programming, the block will be passed a promise
+  # for its own result when it is evaluated.  Be careful not to force
+  # that promise during the computation, lest the computation diverge.
+  #
+  def promise( &computation ) #:yields: result
+    Lazy::Promise.new &computation
+  end
+
+  # Forces the result of a promise to be computed (if necessary) and returns
+  # the bare result object.  Once evaluated, the result of the promise will
+  # be cached.  Nested promises will be evaluated together, until the first
+  # non-promise result.
+  #
+  # If called on a value that is not a promise, it will simply return it.
+  #
+  def demand( promise )
+    if promise.respond_to? :__result__
+      promise.__result__
+    else # not really a promise
+      promise
+    end
+  end
+
+  # Schedules a computation to be run asynchronously in a background thread
+  # and returns a promise for its result.  An attempt to demand the result of
+  # the promise will block until the computation finishes.
+  #
+  # As with Kernel.promise, this passes the block a promise for its own result.
+  # Use wisely.
+  #
+  def future( &computation ) #:yields: result
+    Lazy::Future.new &computation
+  end
+
+end