facets 1.3.3 → 1.4.0

data/lib/facets/more/ansicode.rb

@@ -1,122 +1,111 @@
-#--
-# ANSICode
+# = ansicode.rb
 #
-# Copyright (c) Thomsa Sawyer
+# == Copyright (c) 2004 Florian Frank, 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-04-28  Trans  * Modifications to documentation.
+# == Authors & Contributors
 #
-#  2004-11-30  Trans  * Ported to Facets/More collection
-#
-#  2004-09-28  FF     * First release on Rubyforge
-#                     * Supports Rubygems now
-#
-#  2003-10-09  FF     * Added uncolored method as suggested by
-#                       Thomas Husterer <Thomas.Husterer@heidelberg.com>
-#                     * Added attribute methods with string arguments
-#                     * Deleted now unused files
-#
-#  2002-07-27  FF     * Minor Code Cleanup
-#                     * Added cdiff.rb
+# * Florian Frank
+# * Thomas Sawyer
 #
-#  2002-06-12  FF     * Initial Release
-# ==========================================================================
+# == Speical Thanks
 #
-# THANKS Florian Frank. ANSICode is a partial adaptation of
-#        ANSIColor, Copyright (c) 2002-2005 Florian Frank, LGPL.
+# Special thanks to Florian Frank. ANSICode is a partial adaptation
+# of ANSIColor, Copyright (c) 2002 Florian Frank, LGPL.
 #
-# TODO Need to add rest of ANSI codes. Include modes?
+# == Developer Notes
 #
-# TODO Re-evaluate how color/yielding methods are defined.
+#   TODO Need to add rest of ANSI codes. Include modes?
 #
-# TODO Maybe up, down, right, left should have yielding
-#      versions too?
+#   TODO Re-evaluate how color/yielding methods are defined.
 #
-#++
+#   TODO Maybe up, down, right, left should have yielding
+#        methods too?
 
-# :title: ANSICode
-#
-# Module which makes it very easy to use ANSI codes.
-# These are esspecially nice for beautifying shell output.
-#
-# == Synopsis
-#
-#   include Console::ANSICode
-#
-#   p red, "Hello", blue, "World"   
-#   => "\e[31mHello\e[34mWorld"
-#
-#   p red { "Hello" } + blue { "World" }
-#   => "\e[31mHello\e[0m\e[34mWorld\e[0m"
-#
-# == Supported ANSI Commands
-#
-#     save
-#     restore
-#     clear_screen
-#     cls             # synonym for :clear_screen
-#     clear_line
-#     clr             # synonym for :clear_line
-#     move
-#     up
-#     down
-#     left
-#     right
-#     display
-#
-#     clear
-#     reset           # synonym for :clear
-#     bold
-#     dark
-#     italic          # not widely implemented
-#     underline
-#     underscore      # synonym for :underline
-#     blink
-#     rapid_blink     # not widely implemented
-#     negative        # no reverse because of String#reverse
-#     concealed
-#     strikethrough   # not widely implemented
-#
-#     black
-#     red
-#     green
-#     yellow
-#     blue
-#     magenta
-#     cyan
-#     white
-#
-#     on_black
-#     on_red
-#     on_green
-#     on_yellow
-#     on_blue
-#     on_magenta
-#     on_cyan
-#     on_white
-#
-# == Author(s)
-#
-# * Thomas Sawyer
-# * Florian Frank
-#
+# Author::    Florian Frank, Thomas Sawyer
+# Copyright:: Copyright (c) 2006 Florian Frank, Thomas Sawyer
+# License::   Ruby License
+
+# = Console ANSICode
 #
+# Module provide methods for inserting ansicodes into strings.
 
 module Console
 
+  # = ANSICode
+  #
+  # Module which makes it very easy to use ANSI codes.
+  # These are esspecially nice for beautifying shell output.
+  #
+  # == Synopsis
+  #
+  #   include Console::ANSICode
+  #
+  #   p red, "Hello", blue, "World"
+  #   => "\e[31mHello\e[34mWorld"
+  #
+  #   p red { "Hello" } + blue { "World" }
+  #   => "\e[31mHello\e[0m\e[34mWorld\e[0m"
+  #
+  # == Supported ANSI Commands
+  #
+  #     save
+  #     restore
+  #     clear_screen
+  #     cls             # synonym for :clear_screen
+  #     clear_line
+  #     clr             # synonym for :clear_line
+  #     move
+  #     up
+  #     down
+  #     left
+  #     right
+  #     display
+  #
+  #     clear
+  #     reset           # synonym for :clear
+  #     bold
+  #     dark
+  #     italic          # not widely implemented
+  #     underline
+  #     underscore      # synonym for :underline
+  #     blink
+  #     rapid_blink     # not widely implemented
+  #     negative        # no reverse because of String#reverse
+  #     concealed
+  #     strikethrough   # not widely implemented
+  #
+  #     black
+  #     red
+  #     green
+  #     yellow
+  #     blue
+  #     magenta
+  #     cyan
+  #     white
+  #
+  #     on_black
+  #     on_red
+  #     on_green
+  #     on_yellow
+  #     on_blue
+  #     on_magenta
+  #     on_cyan
+  #     on_white
+  #
+
   module ANSICode
 
+    extend self
+
     # Save current cursor positon.
 
     def save

data/lib/facets/more/aspects.rb

@@ -1,6 +1,34 @@
+# = aspects.rb
+#
+# == Copyright (c) 2005 George Moschovitis
+#
+#   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.
+#
+# == Authors and Contributors
+#
+# * George Moschovitis
+
+# Author::    George Moschovitis
+# Copyright:: Copyright (c) 2005 George Moschovitis
+# License::   Ruby License
+
 require 'facet/inheritor'
 
+# = Aspect
+#
 # An Aspect is a class that defines advices.
+#
+# == Usage
+#
+# George, please do!
+#
 
 class Aspect
   class << self

data/lib/facets/more/association.rb

@@ -1,47 +1,63 @@
-#--
-# Association
+# = association.rb
 #
-# Copyright (c) 2005 Thmas 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-25  Trans     * Initial Release
-# ==========================================================================
-#++
+# == Authors and Contributors
+#
+# * Thomas Sawyer
 
-#:title: Association
+# Author::    Thomas Sawyer
+# Copyright:: Copyright (c) 2005 Thomas Sawyer
+# License::   Ruby License
+
+# = Association
 #
-# Gerenal binary association, useful for creating ordered hashes,
-# or mixed collections.
+# Gerenal binary association allows one object to be
+# associated with another. It has a variety of uses,
+# link-lists, simple ordered maps and mixed collections,
+# among them.
 #
-# The method :>> is used to construct the association. It is an uncommon
-# method, but wehere is has been used prior a suitable alias has been
-# made, #rshift. For Date class it has ben named #months_later.
+# == Usage
 #
-# == Synopsis
+# Associations can be used to draw simple relationships.
 #
-#   c = [ :a >> 1, :b >> 2 ]
+#   :Apple >> :Fruit
+#   :Apple >> :Red
+#
+#   :Apple.associations #=> [ :Fruit, :Red ]
+#
+# It can also be used for simple lists of ordered pairs.
 #
+#   c = [ :a >> 1, :b >> 2 ]
 #   c.each { |k,v| puts "#{k} associated with #{v} }
 #
-# _produces_
+# produces
 #
 #   a associated with 1
 #   b associated with 2
 #
-# == Author(s)
+# == Limitations
 #
-# * Thomas Sawyer
+# The method :>> is used to construct the association.
+# It is a rarely used method so it is generally available.
+# But you can't use an Association while extending the
+# any of the following classes becuase they use #>> for
+# other things.
+#
+#   Bignum
+#   Fixnum
+#   Date
+#   IPAddr
+#   Process::Status
 #
 
 class Association
@@ -85,42 +101,62 @@ class Association
 
 end
 
-# Setup the >> method, aliasing where already used.
 
-class Bignum
-  alias_method( :rshift, :>>) if method_defined?(:>>)
-end
+module Kernel
 
-class Fixnum
-  alias_method( :rshift, :>>) if method_defined?(:>>)
-end
-
-class Date
-  alias_method( :months_later, :>>) if method_defined?(:>>)
-end
+  ASSOCIATIONS = Hash.new{ |h,k,v| h[k]=[] }
 
-class IPAddr
-  alias_method( :rshift, :>>) if method_defined?(:>>)
-end
-
-class Process::Status
-  alias_method( :rshift, :>>) if method_defined?(:>>)
-end
-
-class Object
+  # Define an association with +self+.
   def >>(to)
+    ASSOCIATIONS[self] << to
     Association.new(self, to)
   end
+
+  def associations
+    ASSOCIATIONS[self]
+  end
+
 end
 
 
+#--
+# Setup the >> method in classes that use it  already.
+#
+# This is a bad idea b/c it can cause backward compability issues.
+#
+# class Bignum
+#   alias_method( :rshift, :>>) if method_defined?(:>>)
+#   remove_method :>>
+# end
+#
+# class Fixnum
+#   alias_method( :rshift, :>>) if method_defined?(:>>)
+#   remove_method :>>
+# end
+#
+# class Date
+#   alias_method( :months_later, :>>) if method_defined?(:>>)
+#   remove_method :>>
+# end
+#
+# class IPAddr
+#   alias_method( :rshift, :>>) if method_defined?(:>>)
+#   remove_method :>>
+# end
+#
+# class Process::Status
+#   alias_method( :rshift, :>>) if method_defined?(:>>)
+#   remove_method :>>
+# end
+#++
+
+
 #  _____         _
 # |_   _|__  ___| |_
 #   | |/ _ \/ __| __|
 #   | |  __/\__ \ |_
 #   |_|\___||___/\__|
 #
-
 =begin test
 
   require 'test/unit'
@@ -151,6 +187,11 @@ end
       assert_equal( 'Drop Menu', complex[0].index )
     end
 
+    def test_associations
+      complex = [ :a >> :b, :a >> :c ]
+      assert_equal( [ :b, :c ], :a.associations )
+    end
+
   end
 
 =end

data/lib/facets/more/basicobject.rb

@@ -1,41 +1,38 @@
-#--
-# BasicObject
+# = basicobject.rb
 #
-# Copyright (c) 2005 Thomas Sawyer
-# based on BlankSlate, Copyright (c) 2004 by Jim Weirich
+# == Copyright (c) 2005 Thomas Sawyer, Jim Weirich
 #
-# 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
-# ==========================================================================
-#  2006.04.03  trans
-#  * Got rid of ^object_ exclusion.
+# == Authors and Contributors
 #
-#  2005.10.26  trans
-#  * Preserved a few addtional methods --everyhting ending in ?, dup and
-#    object_id.
-#  * Changed name from BlankSlate to BasicObject
+# * Jim Weirich
+# * Thomas Sawyer
 #
-#  2005.04.28  trans
-#  * Ported from BlankSlate and added __class__.
-# ==========================================================================
+# == Special Thanks
 #
-# TODO Might be nice it there were a factory method to alter which methods
-#      were excluded. But probably too dangerous.
+# Thanks to Jim Weirich for BlankSlate Copyright (c) 2004 by Jim Weirich,
+# on which BasicObject is based.
 #
-#++
+# == Developer Notes
+#
+#   TODO Might be nice it there were a factory method to alter which methods
+#        were excluded. But probably too dangerous.
+
+# Author::    Thomas Sawyer, Jim Weirich
+# Copyright:: Copyright (c) 2005 Thomas Sawyer
+# License::   Ruby License
 
 require 'facets/core/kernel/__class__'
 
-# :title: BasicObject
+# = BasicObject
 #
 # BasicObject provides an abstract base class with no predefined
 # methods, except for <tt>respond_to?</tt>, any method starting in
@@ -75,24 +72,45 @@ class BasicObject
   # method to the current object for the current call.
 
   class Self < self
+    def initialize( as=Object )
+      @as = as
+    end
     def method_missing(meth, *args, &blk)
-      Object.instance_method(meth).bind(self).call(*args, &blk)
+      @as.instance_method(meth).bind(self).call(*args, &blk)
     end
   end
 
   # Returns the Self functor class, which can then be used to
   # call Kernel/Object methods on the current object.
-
-  def __self__
+  #--
+  # May deprecate __self__ altogether.
+  #++
+  def object
     @__self__ ||= Self.new
   end
+  alias_method :__object__, :object
+  alias_method :__self__, :object
+
+  # This method is like #object, but allows any ancestor
+  # to act on behalf of self, not just Object.
+  def as(ancestor)
+    Self.new(ancestor)
+  end
 
-  # Shodow some important methods.
+  # Shadow some other important methods.
   alias_method :__method__, :method
 
-  # Methods not to get rid of. They are too important.
-  #EXCLUDE = /^(__|instance_eval$)/
-  EXCLUDE = /(^__|^instance_|^initialize$|^initialize_copy$|^null$|^inspect$|^dup$|^clone$|\?$)/
+  # Methods not to get rid of as they are either too important, or
+  # they are not likely to get in the way (such as methods ending in '?').
+  #--
+  # TODO In the furture it might be nice to allow some selectability
+  # in these via a factory method.
+  #
+  # NOTE The absolute bare minimum is EXCLUDE = /^(__|instance_eval$)/.
+  # But in most cases you'll want a few extra methods like #dup too.
+  #++
+
+  EXCLUDE = /(^__|^instance|^object|^initialize$|^initialize_copy$|^null$|^inspect$|^dup$|^clone$|^as$|\?$)/
 
   def self.hide(name)
     #if instance_methods.include?(name.to_s) and name !~ EXCLUDE #/^(#{EXCLUDE.join('|')})/