facets 1.3.3 → 1.4.0

data/{doc/AUTHORS → AUTHORS}

@@ -1,5 +1,11 @@
+= Facets Contributing Authors
 
-= Facets' Contributing Authors
+== Main Developers
+
+* Trans (Thomas Sawyer)
+* Florian Gross
+* George Moschovitis
+* Peter Vanbroekhoven
 
 == Rubyists of Distinction
 
@@ -9,13 +15,15 @@
 * Jamis Buck 
 * Renald Buter
 * Shashank Date
+* Robert Feldt
 * Florian Frank
 * Hal Fulton
 * Michael Granger
 * Florian Gross
 * Thomas-Ivo Heinen
-* David H. H.
+* David Heinemeier Hansson
 * Ara T. Howard
+* MenTaLguY
 * Mohammad Khan
 * Derek Lewis
 * Jan Molic
@@ -30,7 +38,8 @@
 * Jim Weirich
 * Jeff Wood
 * Austin Ziegler
-* why_the_lucky_stiff
+* Why The Lucky Stiff
 
 If any names are missing from this list, please let me know
 and I will correct immediately.
+

data/README

@@ -8,9 +8,10 @@
 
 Ruby Facets
 
+Facets is set of two libraries Facets/CORE and Facets/MORE.
+
 Facets/CORE is a vast collection of methods which extend the core
 capabilities of Ruby's built-in classes and modules.
-
 This collection of extension methods is unique by virtue of its atomicity.
 The methods are stored individually so that each can be required
 independently. This gives developers fine-grain control over which 
@@ -18,10 +19,9 @@ extra methods to bring into his or her code. The collection currently
 contains over 400 methods spanning 28 classes and modules.
 
 Facets/MORE is a collection of additioanl classes, modules and microframeworks.
-
 The class, module and microframework additions consitute an ever growing
-and improving source of reusable components. Some very nice adsitions
-have recently been added, from an amazing Units system to an elegant 
+and improving source of reusable components. Some very nice additions
+are available, from an amazing Units system to an elegant
 annotations systems. And of course there are all the more typical goodies
 like Tuple, Functor and Multiton.
 
@@ -29,7 +29,7 @@ like Tuple, Functor and Multiton.
 
 Facets holds to the notion that the more we can reasonably integrate into
 a common foundation directed toward general needs, the better that foundation 
-will be able to serve us. There are a number of advantages here:
+will be able to serve everyone. There are a number of advantages here:
 
     * Better Code-reuse
     * Collaborative Improvements
@@ -39,18 +39,17 @@ will be able to serve us. There are a number of advantages here:
 
 == Status
 
-The current status is quite good. While various parts are still considered
-Beta, everything is relatively usable.
+The current status is quite good. While some parts are still considered
+beta, everything is relatively usable.
 
 
 == Installation
 
-
 The easiest way to install is via RubyGems. On the command line enter:
 
   > gem install facets
 
-To manually install, unpack the .tbz (.tar.bz2) package and use the included
+To manually install, unpack the .tar.bz2 package and use the included
 setup.rb script. For example:
 
   > tar -xvzf facets,YYYY-MM-DD.tbz
@@ -63,24 +62,27 @@ setup.rb script. For example:
 For detailed usage of any given method or module please refer to the
 API RDocs. Most are well documented.
 
-To use a single facet you simply require the method by name, for example:
+To use a single CORE facet you simply require the method by name, for example:
 
   require 'facet/time/stamp'
 
 Techinally this requires a redirection file to the core method itself.
-You can bypass the redirection:
+Redirection can be bypassed. Eg.
 
   require 'facets/core/time/stamp'
 
-Although not at all neccessary, if you are using more then a few facets
-it is recommended that before requiring any of them you first require
-the main facility.
+But this usage is discouraged and should only be used if it is for some
+reason neccessary or you are developing a library for Facets itself.
+
+If you are using more then a few facets it is recommended that before
+requiring any of them you first require the main facility.
 
   require 'facets'
 
-This loads all the core facets considered "base" (a couple dozen basic methods)
-and add the facets library directories to the end of Ruby's load path. This
-allows you to require facets without the 'facet/...' prefix. Eg.
+This loads a set of facets considered "base" --currently a couple dozen
+very basic methods, and adds the facets library directories to the end
+of Ruby's load path. This allows you to require facets without even using
+the 'facet/...' prefix. Eg.
 
   require 'string/blank'
 
@@ -88,14 +90,20 @@ A handful of extension sets are also available. For example,
 
   require 'facet/string_as_array'
 
-adds some methods to Array that make it behave a little more like
-an array of characters. Other useful sets include, 'random' which 
+adds some methods to Array that allow a String to behave more like
+an array of characters. Other useful sets include, 'random' which
 loads every facet method related to randomness and 'inflect' which
 loads a number of methods for manipulating strings in high-level
 ways, like #camelize and #pluralize.
 
-Using a module, class or microframework is essentially the same. 
-You can use the redirection path. Eg.
+It also should be pointed out that class methods are stored under
+the 'self' directory of a class. For example, to load the
+File::read_list method.
+
+  require 'facet/file/self/read_list'
+
+Using a Facets/MORE library of modules, classes or microframeworks
+is essentially the same. You can use the redirection path. Eg.
 
   require 'facet/basicobject'
 
@@ -108,9 +116,9 @@ Again, if you load the main facility, you can eliminate the need for the 'facet/
   require 'facets'
   require 'basicobject'
 
-Understand that on the off chance that anoth library you are using has the same name as 
-one of Facets' everything will still work fine. You will not be able to use the
-prefixless shorcut to require the facet.
+Understand that on the off chance that another library has the same name as
+one of Facets' everything will still work fine. You will just not be able to use the
+prefixless shorcut to require it.
 
 For details pertaining to the functionality of each feature, please see the API Docs.
 
@@ -119,7 +127,7 @@ For details pertaining to the functionality of each feature, please see the API
 
 === Directories
 
-There are presently three two subdirs in Facets: 'core', which stores
+There are two subdirectories in Facets library, 'core', which stores
 the method extensions and 'more' which store the modules, classes and
 micorframeworks.
 
@@ -224,10 +232,8 @@ A copy of both licenses accompany this document (see COPYING).
 
 Credit and Copyrights for particular borrowed code segments are
 given in their respective source. All licenses are either compatible
-with the Ruby lincense (Ruby or GPL) or the original author has given
-permission for inclusion of their code under this lincense.</p>
-
-Any code file not specifically labeled shall fall under the Ruby License.
+with the Ruby license (namely the GPL) or the original author has given
+permission for inclusion of their code under such lincense.</p>
 
 
 == Pitch

data/WARNING

@@ -0,0 +1,56 @@
+
+  # Some caution should be taken when using certain facets.
+  # What follows ois list of such facets and the reasons
+  # these particular facets should given special consideration.
+
+  # Some facets require other files to be loaded first
+  # that are not loaded automatically, like fileutils
+  # (i.e. they are part of the standard lib, not core).
+  # The file include all of the following.
+
+  date/*
+  fileutils/*
+  ostruct/*
+  logger/*
+  gem/*
+
+  # Others effect the system in slightly non-standard ways.
+  # Though such changes are kept to a minumim and intended
+  # to be backward compatible, there still may be edge cases
+  # that could cause another library to misbehave. 
+  # The following is a list known facets that may have 
+  # this potential.
+
+  array/op_fetch.rb
+  array/op_store.rb
+  binding/self/of_caller.rb
+  hash/op_fetch.rb
+  hash/op_store.rb
+  numeric/succ.rb
+  numeric/pred.rb
+  string/succ.rb
+  string/unpack.rb
+  module/attr.rb
+  #module/attr_reader.rb
+  #module/attr_writer.rb
+  #module/attr_accessor.rb
+
+  # There are also some facets that are potentially unsafe b/c
+  # they change Ruby's default behavior in a nonconvential
+  # manner and hence are not designed to be backward compatible.
+  # Using these with a pre-existent program may cause the program
+  # to misbehave. So while they can be useful, be sure to 
+  # understand exactly what they do before putting them to 
+  # serious use.
+
+  hash/each.rb
+  module/methods.rb
+  object/method.rb
+  nilclass/op_fetch.rb
+  nilclass/empty.rb
+  nilclass/include.rb
+  nilclass/size.rb
+  nilclass/length.rb
+  nilclass/method_missing.rb
+
+#

data/demo/annotation/demo_annotation.rb

@@ -0,0 +1,22 @@
+require 'mega/annotation'
+
+module M
+       ann :this, :koko => []
+       ann.this.koko! << 1
+end
+
+class C1
+       include M
+       ann.this.koko! << 2
+       ann.this.koko! << 3
+end
+
+
+class C2
+       include M
+       ann.this.koko! << 4
+end
+
+p M.ann.this.koko # => expected [1]
+p C1.ann.this.koko # => expected [1, 2, 3]
+p C2.ann.this.koko # => expectes [1, 4]

data/demo/ansicolor/cdiff.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+#
+## Little unix filter that colorizes diff output
+#
+
+require 'term/ansicolor'
+
+include Term::ANSIColor
+
+ARGF.each do |line|
+  print(
+    case line
+    when /^\+/ then green { line }
+    when /^-/ then red { line }
+    when /^(@@|diff)/ then blue { line }
+    else line
+    end
+  )
+end
+  # vim: set et sw=2 ts=2:

data/demo/ansicolor/example.rb

@@ -0,0 +1,82 @@
+require 'term/ansicolor'
+
+# Use this trick to work around namespace cluttering that
+# happens if you just include Term::ANSIColor:
+
+class Color
+  class << self
+    include Term::ANSIColor
+  end
+end
+
+print Color.red, Color.bold, "No Namespace cluttering:", Color.clear, "\n"
+print Color.green + "green" + Color.clear, "\n"
+print Color.on_red(Color.green("green")), "\n"
+print Color.yellow { Color.on_black { "yellow on_black" } }, "\n\n"
+
+# Anyway, I don't define any of Term::ANSIColor's methods in this example
+# and I want to keep it short:
+include Term::ANSIColor
+
+print red, bold, "Usage as constants:", reset, "\n"
+print clear, "clear", reset, reset, "reset", reset,
+  bold, "bold", reset, dark, "dark", reset,
+  underscore, "underscore", reset, blink, "blink", reset,
+  negative, "negative", reset, concealed, "concealed", reset, "|\n",
+  black, "black", reset, red, "red", reset, green, "green", reset,
+  yellow, "yellow", reset, blue, "blue", reset, magenta, "magenta", reset,
+  cyan, "cyan", reset, white, "white", reset, "|\n",
+  on_black, "on_black", reset, on_red, "on_red", reset,
+  on_green, "on_green", reset, on_yellow, "on_yellow", reset,
+  on_blue, "on_blue", reset, on_magenta, "on_magenta", reset,
+  on_cyan, "on_cyan", reset, on_white, "on_white", reset, "|\n\n"
+
+print red, bold, "Usage as unary functions:", reset, "\n"
+print clear("clear"), reset("reset"), bold("bold"), dark("dark"),
+  underscore("underscore"), blink("blink"), negative("negative"),
+  concealed("concealed"), "|\n",
+  black("black"), red("red"), green("green"), yellow("yellow"),
+  blue("blue"), magenta("magenta"), cyan("cyan"), white("white"), "|\n",
+  on_black("on_black"), on_red("on_red"), on_green("on_green"),#
+  on_yellow("on_yellow"), on_blue("on_blue"), on_magenta("on_magenta"),
+  on_cyan("on_cyan"), on_white("on_white"), "|\n\n"
+
+print red { bold { "Usage as block forms:" } }, "\n"
+print clear { "clear" }, reset { "reset" }, bold { "bold" },
+  dark { "dark" }, underscore { "underscore" }, blink { "blink" },
+  negative { "negative" }, concealed { "concealed" }, "|\n",
+  black { "black" }, red { "red" }, green { "green" },
+  yellow { "yellow" }, blue { "blue" }, magenta { "magenta" },
+  cyan { "cyan" }, white { "white" }, "|\n",
+  on_black { "on_black" }, on_red { "on_red" }, on_green { "on_green" },
+  on_yellow { "on_yellow" }, on_blue { "on_blue" },
+  on_magenta { "on_magenta" }, on_cyan { "on_cyan" },
+  on_white { "on_white" }, "|\n\n"
+
+# Usage as Mixin into String or its Subclasses
+class String
+  include Term::ANSIColor
+end
+
+print "Usage as String Mixins:".red.bold, "\n"
+print "clear".clear, "reset".reset, "bold".bold, "dark".dark,
+  "underscore".underscore, "blink".blink, "negative".negative,
+  "concealed".concealed, "|\n",
+  "black".black, "red".red, "green".green, "yellow".yellow,
+  "blue".blue, "magenta".magenta, "cyan".cyan, "white".white, "|\n",
+  "on_black".on_black, "on_red".on_red, "on_green".on_green,
+  "on_yellow".on_yellow, "on_blue".on_blue, "on_magenta".on_magenta,
+  "on_cyan".on_cyan, "on_white".on_white, "|\n\n"
+
+symbols = Term::ANSIColor::attributes
+print red { bold { "All supported attributes = " } },
+  blue { symbols.inspect }, "\n\n"
+
+print "Send symbols to strings:".send(:red).send(:bold), "\n"
+print symbols[12, 8].map { |c| c.to_s.send(c) }, "\n\n"
+
+print red { bold { "Make strings monochromatic again:" } }, "\n"
+print [ "red".red, "not red anymore".red.uncolored,
+  uncolored { "not red anymore".red }, uncolored("not red anymore".red)
+    ].map { |x| x + "\n" }
+  # vim: set et sw=2 ts=2:

data/demo/io-reactor/chatserver.rb

@@ -0,0 +1,347 @@
+#!/usr/bin/ruby
+# = chatserver.rb
+# 
+# This is an extremely crude and simple single-threaded multiplexing chat
+# server. It (hopefully) demonstrates how to use a IO::Reactor object to do IO
+# multiplexing with events.
+#
+# == Synopsis
+#
+#   $ chatserver.rb [HOST [PORT [LOOPTIMEOUT]]]
+#
+# [HOST]
+#   The host or IP the server will bind to
+#
+# [PORT]
+#   The port the server will listen on
+#
+# [LOOPTIMEOUT]
+#   The number of floating-point seconds between polls. Specifying -1 (or any
+#   negative number, really) here will make the server's event loop block on the
+#   call to #poll.
+#
+# == Author
+# 
+# Michael Granger <ged@FaerieMUD.org>
+# 
+# Copyright (c) 2002, 2003 The FaerieMUD Consortium. All rights reserved.
+# 
+# This program is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby itself.
+# 
+# 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.
+#
+# == Version
+#
+#  $Id: chatserver.rb,v 1.4 2003/08/04 23:53:32 deveiant Exp $
+# 
+
+require 'io/reactor'
+require 'socket'
+
+module Example
+
+### Chatserver user class -- part of the chatserver example.
+class User
+
+	MTU	 = 4096
+	CR   = "\015"
+	LF   = "\012"
+	EOL  = CR + LF
+	
+	PROMPT = 'chat> '
+
+	### Create and return a user object which will use the specified
+	### <tt>socket</tt> and <tt>pollObj</tt>.
+	def initialize( socket, server )
+		@socket = socket
+		@server = server
+		@obuffer = ''
+		@ibuffer = ''
+		@peerHost = @socket.peeraddr[2]
+		@peerPort = @socket.peeraddr[1]
+		@connected = true
+	end
+
+	# Object attribute
+	attr_reader :socket, :server, :ibuffer, :obuffer
+
+
+	### Return a stringified version of the user
+	def to_s
+		"%s:%d" % [ @peerHost, @peerPort ]
+	end
+
+
+	### Add the specified string to the user's output buffer and turn on
+	### output events.
+	def addOutput( string )
+		@obuffer << string.chomp << EOL
+		@server.reactor.enableEvents( @socket, :write )
+	end
+	alias :<< :addOutput
+
+
+	### Write as much of the output buffer to the socket as possible, and return
+	### the number of bytes remaining to be sent.
+	def writeOutput
+		bytes = @socket.syswrite( @obuffer )
+		@obuffer[ 0, bytes ] = '' if bytes.nonzero?
+		return @obuffer.length
+	end
+
+
+	### Write a prompt to the user
+	def prompt
+		@obuffer << PROMPT
+		@server.reactor.enableEvents( @socket, :write )
+	end
+
+
+	### Read at most MTU bytes from the socket and append them to the input
+	### buffer. Split off any complete lines (one that end with EOL) and return
+	### them as an Array of Strings.
+	def readInput
+		rary = []
+		@ibuffer << @socket.sysread( MTU )
+		$stderr.puts "Input buffer for user #{self} now: #@ibuffer" if $VERBOSE
+		while (( pos = @ibuffer.index EOL ))
+			$stderr.puts "Found terminating EOL. "\
+				"Splitting off 0..#{pos} of the input buffer." if $VERBOSE
+			rary << @ibuffer[ 0, pos ]
+			@ibuffer[ 0, pos + EOL.length ] = ''
+		end
+
+		return rary
+	rescue EOFError
+		@server.disconnectUser( self )
+		return []
+	end
+
+
+	### Handle poll events on the socket
+	def handleIOEvent( io, event )
+		case event
+
+		when :error
+			@server.disconnectUser( self )
+			
+		when :read
+			input = readInput()
+			@server.processInput( self, *input ) unless input.empty?
+
+		when :write
+			bytesLeft = writeOutput()
+			@server.reactor.disableEvents( @socket, :write ) if bytesLeft.zero?
+
+		end
+
+	end
+
+
+	### Disconnect the user
+	def disconnect( msg='' )
+		@connected = false
+		unless msg.empty?
+			@obuffer = ">>> Disconnected: #{msg} <<<" + EOL
+		else
+			@obuffer = ">>> Disconnected <<<" + EOL
+		end
+		writeOutput()
+		@socket.close
+	end
+
+
+	### Returns true if the user is still connected
+	def connected?
+		@connected
+	end
+end # class User
+
+
+### Example chatserver class -- an extremely crude and simple chat server that
+### demonstrates how to use Poll to do multiplexing IO in a single thread.
+class Server
+
+	BANNER = <<-EOF
+	[[ IO::Reactor Example Chatserver ]]
+	Commands: '/quit' to quit, '/shutdown' to shut the server down
+	EOF
+
+	### Instantiate and return a chatserver on the specified host and port
+	def initialize( listenHost="0.0.0.0", listenPort=1138, interval=0.20 )
+		@socket			= TCPServer::new( listenHost, listenPort )
+		@users			= []
+		@reactor		= IO::Reactor::new
+		@pollInterval	= interval
+		@shuttingDown	= false
+
+		@reactor.register @socket, :read, &method(:handlePollEvent)
+	end
+
+	# Server attributes
+	attr_reader :reactor, :users, :socket
+
+
+	### Main server loop
+	def eventLoop
+		trap( "INT" ) { shutdown("Server caught SIGINT") }
+		trap( "TERM" ) { shutdown("Server caught SIGTERM") }
+		trap( "HUP" ) { disconnectAllUsers(">>> Server reset <<<") }
+
+		until @shuttingDown
+			eventCount = @reactor.poll( @pollInterval )
+		end
+
+	rescue StandardError => e
+		$stderr.puts "Error in server: #{e.message}"
+		$stderr.puts "\t" + e.backtrace.join( "\n\t" )
+		shutdown( "Server error: #{e.message}" )
+	rescue SignalException => e
+		shutdown( "Server caught #{e.type.name}" )
+	ensure
+		trap( "INT", "SIG_IGN" )
+		trap( "TERM", "SIG_IGN" )
+		trap( "HUP", "SIG_IGN" )
+
+		$stderr.puts "Server exiting event loop."
+	end
+
+
+	### Handle a poll event specified by <tt>event</tt> on the specified
+	### <tt>socket</tt>
+	def handlePollEvent( socket, event )
+		$stderr.puts "Got #{event.inspect} event for #{socket.inspect}"
+
+		case event
+		when :error
+			$stderr.puts "Socket error on the listener socket."
+			shutdown()
+
+		when :read
+			clSock = socket.accept
+			user = User::new( clSock, self )
+			$stderr.puts "Accepted connection from #{user}"
+			@reactor.register clSock, :read, &user.method(:handleIOEvent)
+			user.addOutput( BANNER )
+			user.prompt
+			broadcastMsg( "[New connection: #{user}]" )
+			@users << user
+
+		end
+	end
+
+
+	### Process the specified input from the specified user
+	def processInput( user, *inputStrings )
+		inputStrings.each {|str|
+			case str
+
+			when %r{^/(\w+)\s*(.*)}
+				handleCommand( user, $1, $2 )
+
+			else
+				user.addOutput( "You>> #{str}" )
+				broadcastMsgFrom( user, str )
+			end
+		}
+
+		user.prompt if user.connected?
+	end
+
+
+	### Handle the specified command from the specified user
+	def handleCommand( user, command, args )
+		case command
+
+		when /quit/
+			disconnectUser( user, 'Quit' )
+			
+		when /shutdown/
+			shutdown()
+
+		when /who/
+			user.addOutput( self.wholist(user) )
+
+		else
+			user.addOutput("Unknown command '#{command}'")
+		end
+	end
+
+
+	### Broadcast the specified message to all connected users
+	def broadcastMsg( msg )
+		@users.each {|cl|
+			cl.addOutput( msg )
+		}
+	end
+
+
+	### Broadcast the specified message from the specified user
+	def broadcastMsgFrom( user, msg )
+		userDesc = user.to_s
+
+		@users.each {|cl|
+			next if cl == user
+			cl.addOutput( "#{userDesc}>> #{msg}" )
+		}
+	end
+
+
+	### Disconnect the specified user
+	def disconnectUser( user, msg='' )
+		@users -= [ user ]
+		@reactor.unregister( user.socket )
+		user.disconnect( msg )
+		broadcastMsg( "#{user.to_s} Disconnected." )
+	end
+
+
+	### Disconnect all connected users
+	def disconnectAllUsers( msg )
+		@users.each {|user|
+			@reactor.unregister( user.socket )
+			user.disconnect( msg )
+		}
+		@users.clear
+	end
+
+
+	### Shut the server down
+	def shutdown( msg="Server shutdown" )
+		$stderr.puts "Shutting down: #{msg}"
+		@shuttingDown = true
+		@reactor.clear
+		begin
+			@socket.shutdown
+		rescue
+		end
+		disconnectAllUsers( msg )
+		begin
+			@socket.close
+		rescue
+		end
+	end
+
+	### Build and return a list of connected users for the specified user.
+	def wholist( user )
+		rval = "[Connected Users]\n" <<
+			"  *#{user}*\n"
+		@users.each {|u|
+			next if u == user
+			rval << "  #{u}\n"
+		}
+
+		return rval
+	end
+
+end # class Server
+end # module Example
+
+srv = Example::Server::new( *ARGV )
+$stderr.puts "Chat server listening on #{srv.socket.addr[2]} port #{srv.socket.addr[1]}"
+srv.eventLoop
+$stderr.puts "Chat server finished."
+