facets 1.3.3 → 1.4.0

data/lib/facets/more/methodprobe.rb

@@ -1,73 +1,70 @@
-#--
-# Method Probe
+# = methodprobe.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.
 #
-#
-# ===========================================================================
-# Revision History ::
-# ---------------------------------------------------------------------------
-#  5.7.21  Trans   * Changed name from DuckHunter to Method::Probe.
-# ===========================================================================
-#++
-
-#:title: Method Probe
-#
-# Method::Probe (aka DuckHunter) is a decoy object which is dropped into
-# methods which records the calls made against it --hence a method probe.
-# Of course, it is not perfect --an inescapable matter it seems for any
-# internal probe. There are a couple of issues related to conditionals.
-# Since the method test for a certain condition against the decoy, how
-# is the decoy to respond? Thus ceratin paths in the code may never get
-# exceuted and thus go unmapped. If Ruby had better conditional reflection
-# (i.e. if 'if', 'case', 'unless', 'when', etc. were true methods) then
-# this could be fixed by making the Probe reentrant, mapping out variant
-# true/false/nil replies. The likely insurmountable problem though is the
-# Halting problem. A probe can cause some methods to complete execution.
-# It's pretty rare, but it can happen and little can be done about it (I think).
-#
-# Note, the alternative to this kind of probe is a program that examines, rather
-# then executes, the code. This would circumvent the above problems, but run
-# into difficulties with dynamic evals. It would also be more complicated,
-# but might prove a better means in the future.
-#
-# This script is provided for experimetnal purposes. Please inform the author
-# if you find ways to improve it or put it to an interesting use.
-#
-# == Synopsis
-#
-#   require 'methodprobe'
-#
-#   def amethod(x)
-#     x + 1
-#   end
-#
-#   p method(:amethod).signiture
-#   p method(:amethod).signiture(:class)
-#   p method(:amethod).signiture(:pretty)
-#
-# produces
-#
-#   [["+"]]
-#   [{"+"=>[["Fixnum"]]}]
-#   [["+( Fixnum )"]]
-#
-# == Authors(s)
+# == Author(s)
 #
 # * Thomas Sawyer
+
+# Author::    Thomas Sawyer
+# Copyright:: Copyright (c) 2006 Thomas Sawyer
+# License::   Ruby License
+
 #
 
 class Method
 
+  # = Method Probe
+  #
+  # Method::Probe (aka DuckHunter) is a decoy object which is dropped into
+  # methods which records the calls made against it --hence a method probe.
+  # Of course, it is not perfect --an inescapable matter it seems for any
+  # internal probe. There are a couple of issues related to conditionals.
+  # Since the method test for a certain condition against the decoy, how
+  # is the decoy to respond? Thus ceratin paths in the code may never get
+  # exceuted and thus go unmapped. If Ruby had better conditional reflection
+  # (i.e. if 'if', 'case', 'unless', 'when', etc. were true methods) then
+  # this could be fixed by making the Probe reentrant, mapping out variant
+  # true/false/nil replies. The likely insurmountable problem though is the
+  # Halting problem. A probe can cause some methods to complete execution.
+  # It's pretty rare, but it can happen and little can be done about it (I think).
+  #
+  # Note, the alternative to this kind of probe is a program that examines, rather
+  # then executes, the code. This would circumvent the above problems, but run
+  # into difficulties with dynamic evals. It would also be more complicated,
+  # but might prove a better means in the future.
+  #
+  # This script is provided for experimetnal purposes. Please inform the author
+  # if you find ways to improve it or put it to an interesting use.
+  #
+  # == Synopsis
+  #
+  #   require 'methodprobe'
+  #
+  #   def amethod(x)
+  #     x + 1
+  #   end
+  #
+  #   p method(:amethod).signiture
+  #   p method(:amethod).signiture(:class)
+  #   p method(:amethod).signiture(:pretty)
+  #
+  # produces
+  #
+  #   [["+"]]
+  #   [{"+"=>[["Fixnum"]]}]
+  #   [["+( Fixnum )"]]
+  #
+
   class Probe
 
     def Probe.duckcall
@@ -125,7 +122,6 @@ class Method
 
   end #class Probe
 
-
   # Outputs migration information.
   def migration
     parameters = []; argc = self.arity
@@ -139,7 +135,6 @@ class Method
   end
   private :migration
 
-
   # Outputs signiture information.
   def signature(detail=nil)
     ds = []

data/lib/facets/more/mock.rb

@@ -1,30 +1,37 @@
-#--
-# Mock
+# = mock.rb
 #
-# Copyright (c) 2005 Thomas Sawyer, Michael Granger and George Moschovitis
+# == Copyright (c) 2005 George Moschovitis, Michael Granger
 #
-# 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 ::
-# --------------------------------------------------------------------------
-#  0.5.8.24  trans  Created, based-off of George's initial Mock idea, and
-#                   largely influence by Michael Granger's Test::Unit::Mock.
-# ==========================================================================
+# Thanks goes to Michael Granger for Test::Unit::Mock on which
+# this library is partially based.
 #
-#++
+# == Author(s)
+#
+# * Thomas Sawyer
+#
+# == Developer Notes
+#
+#   TODO Rename to MockObject ?
+#        Should this be under Test::Unit too ?
+
+# Author::    George Moschovitis, Michael Granger
+# Copyright:: Copyright (c) 2005 George Moschovitis, Michael Granger
+# License::   Ruby License
 
 require 'ostruct'
 
-#:title: Mock
+# = Mock
 #
 # A straightfoward mocking facility. Typically used in test cases.
 # The Mock class offers a few constructors for quickly building

data/lib/facets/more/multipliers.rb

@@ -1,25 +1,29 @@
-#--
-# multipliers.rb
+# = multipliers.rb
 #
-# Copyright (c) 2005 Thomas Sawyer
+# == Copyright (c) 2005 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.
 #
-# ==========================================================================
-# Revision History ::
-# --------------------------------------------------------------------------
-#  2005.08.10  trans   * Created, inspired by Rich Kilmer's bytes.rb.
-# ==========================================================================
-#++
-
-#:title: Multipliers
+# == Special Thanks
+#
+# Thanks to Rich Kilmer and bytes.rb which inspired this library.
+#
+# == Author(s)
+#
+# * Thomas Sawyer
+
+# Author::    Thomas Sawyer
+# Copyright:: Copyright (c) 2005 Thomas Sawyer
+# License::   Ruby License
+
+# = Multipliers
 #
 # Adds methods to Numeric to make working with
 # magnitudes (kilo, mega, giga, milli, micro, etc.)

data/lib/facets/more/multiton.rb

@@ -1,26 +1,26 @@
-#--
-# Multiton
-# Copyright (c) 2005 Florian Frank, Thomas Sawyer
+# = multiton.rb
 #
-# Ruby License
+# == Copyright (c) 2005 Florian Frank, Thomas Sawyer
 #
-# This module is free software. You may use, modify, and/or redistribute this
-# software under the same terms as Ruby.
+#   Ruby License
 #
-# 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 module is free software. You may use, modify, and/or redistribute this
+#   software under the same terms as Ruby.
 #
-# ==========================================================================
-# Revision Notes
-# --------------------------------------------------------------------------
-#  2005-11-27   trans    * Simplifed variations to one.
-#  2005-08-01   trans    * Minor modifications to documentation.
-#  2005-02-01   trans    * Added New and Semi variations.
-# ==========================================================================
-#++
+#   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)
+#
+# * Florian Frank
+# * Thomas Sawyer
 
-#:title: Multiton
+# Author::    Florian Frank, Thomas Sawyer
+# Copyright:: Copyright (c) 2005 Florian Frank, Thomas Sawyer
+# License::   Ruby License
+
+# = Multiton
 #
 # Multiton module that ensures only one object to be allocated for a given
 # argument list.
@@ -87,12 +87,6 @@
 #
 # Which should return a hash key used to identify the object being
 # constructed as (not) unique.
-#
-# == Author(s)
-#
-# * Florian Frank
-# * Thomas Sawyer
-#
 
 module Multiton
 

data/lib/facets/more/nackclass.rb

@@ -1,31 +1,31 @@
-#--
-# NackClass
+# = nackclass.rb
 #
-# Copyright (c) 2005 Thomas Sawyer
+# == Copyright (c) 2005 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)
+#
+# * Thomas Sawyer
 #
-# ==========================================================================
-# Revision History ::
-# --------------------------------------------------------------------------
-#  04.09.10  Trans   * Making progress. Just usable to some degree now.
-# ==========================================================================
+# == Developer Notes
 #
 # TODO I beleive this class has even more potential yet.
 #      It would be interesting to see if a catch/try correction
 #      facility could be built into it too.
-#
-#++
 
-#:title: NackClass
+# Author::    Thomas Sawyer
+# Copyright:: Copyright (c) 2005 Thomas Sawyer
+# License::   Ruby License
+
+# = NackClass
 #
 # The NackClass is is like the NilClass except one step down.
 # Nack is never used to to mean nothingness or emptiness.
@@ -49,10 +49,6 @@
 #   a = nail scaler( 1 )       #=> 1
 #   b = nail scaler( [1,2] )   #=> ArgumentError
 #
-# == Author(s)
-#
-# * Thomas Sawyer
-#
 
 class InvalidNackError < ArgumentError
 end

data/lib/facets/more/nilcomparable.rb

@@ -1,26 +1,30 @@
-#--
-# NilComparable
+# = nilcomparable.rb
 #
-# Copyright (c) 2005 Thomas Sawyer
+# == Copyright (c) 2005 Thomas Sawyer, 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 ::
-# --------------------------------------------------------------------------
-#  2005-4   trans     * Documentation.
-# ==========================================================================
-#++
+# Based on library from Paul Brannan's Ruby Treasures.
+#
+# == Author(s)
+#
+# * Thomas Sawyer
+# * Paul Brannan
+
+# Author::    Thomas Sawyer, Paul Brannan
+# Copyright:: Copyright (c) 2005 Thomas Sawyer, Paul Brannan
+# License::   Ruby License
 
-#:title: NilComparable
+# = NilComparable
 #
 # This microframework simply makes nil comparable, such that
 # all things (except itself) are greater than it.
@@ -47,7 +51,7 @@
 #     end
 #
 #   end
-#  
+#
 # To do so for a pre-existing class with a pre-existing #<=> method, you'll 
 # need to overide the method. As an example let's make Numeric comparable to nil.
 #
@@ -72,19 +76,13 @@
 #
 # == Note
 #
-#   NilCompariable _was_ a module that could automatically make
-#   a class comparable to nil. But it only worked if the #<=> was
-#   previous defined, which isn't ideal. Since it is easy enough
-#   to use the above examples, we decided to deprecate the module
-#   and leave this as an explicit task for the end-programmer.
-#   Changing this behavior for built-in classes is not something
-#   to be done lightly anyway.
-#
-# == Author(s)
-#
-# * Paul Brannan
-# * Thomas Sawyer
-#
+# NilCompariable _was_ a module that could automatically make
+# a class comparable to nil. But it only worked if the #<=> was
+# previous defined, which isn't ideal. Since it is easy enough
+# to use the above examples, we decided to deprecate the module
+# and leave this as an explicit task for the end-programmer.
+# Changing this behavior for built-in classes is not something
+# to be done lightly anyway.
 
 class NilClass
 

data/lib/facets/more/nullclass.rb

@@ -1,24 +1,25 @@
-#--
-# NullClass
+# = nullclass.rb
 #
-# Copyright (c) 2005 Thomas Sawyer
+# == Copyright (c) 2005 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.
 #
-# ==========================================================================
-# Revision History ::
-# --------------------------------------------------------------------------
-#  2005.10.28  trans     * Created.
-# ==========================================================================
+# == Author(s)
+#
+# * Thomas Sawyer
+
+# Author::    Thomas Sawyer
+# Copyright:: Copyright (c) 2005 Thomas Sawyer
+# License::   Ruby License
 
-# :title: NullClass
+# = NullClass
 #
 # NullClass is essentially NilClass but it differs in one
 # important way. When a method is called against it that it