carats 0.3.0

data/ChangeLog

@@ -0,0 +1,2 @@
+2005-01-26:
+  * Improved attr.rb so that #attr is now backward compatible.

data/LICENSE

@@ -0,0 +1,5 @@
+OPEN SOURCE COLLECTION
+
+A variery of open-source licenses are used.
+
+See the license directory for all the specific licenses.

data/README

@@ -0,0 +1,67 @@
+= Ruby Carats, the Ruby Toolchest
+
+== Introduction
+
+Ruby Carats is an extensive, 100% pure Ruby, general purposed library collection
+of classes amd modules. It is an open repository for useful 
+general puroposed and well tested classes, modules, mixins.
+
+== Installation
+
+To do a manual install untar and use the included setup.rb script.
+  
+  > tar -xvzf carats-x.y.z.tar.gz
+  > cd carats-x.y.z
+  > sudo ruby setup.rb
+
+== Usage
+
+Umm... that might require a book. You should look at the API docs.
+To date, not everything in documented. But it's getting there.
+You are welcome to help out. The basic require is:
+
+  require 'carat/<file>'
+
+== Authorship
+
+This collection was put together by, and largely written by Thomas Sawyer
+(aka T. Onoma). He can be reached via email at transami at runbox.com.
+
+This package is a collection of work by many persons. 
+If it matters, the collection per collection is licensed:
+
+  Ruby Carats
+  Copyright (c) 2004-2005 Thomas Sawyer
+  Ruby License
+
+But the actual code on is licensed according to the original authors
+desires, being one of the following: Ruby, GPL, LGPL, MIT, or Artistic.
+Copies of these licenses should accompany this document. Any piece of code
+not specifically laballed shall fall under the Ruby License.
+   
+[Please Note: I am working to make sure everything is labeled appropriately.
+Please forgive me if I have not done so in a particular place --just let 
+me know and I will fix.]
+
+Also, I would like to ask all those authors, whose code is collected here,
+to consider moving to the Ruby license, so one license can serve for all.
+
+=== Attributed Authors
+
+* Thomas Sawyer
+* Paul Brannan
+* Renald Buter
+* Hal Fulton
+* Gavin Sinclair
+* Michael Granger
+* Michael Neumann
+* Florian Frank
+* Mohammad Khan
+* Derek Lewis
+* Thomas-Ivo Heinen
+* Jan Molic
+
+
+== Pitch
+
+  ALL YOUR BASE ARE BELONG TO RUBY

data/Reapfile

@@ -0,0 +1,72 @@
+--- %YAML:1.0
+
+TITLE: &title Ruby Carats
+NAME: &pkg carats
+VERSION: '0.3.0'
+AUTHOR: Trans Onoma
+EMAIL: transfire@gmail.com
+HOMEPAGE: "http://calibre.rubyforge.org"
+
+SUMMARY: Collection of classes, modules, and mixins. 
+
+DESCRIPTION: >
+  Ruby Carats is a large collection of additions for
+  the Ruby programming language. Carats is broard in it
+  coverage and draws heavily on many works by many
+  authors. Ruby Carats is a subproject of Ruby Calibre.
+
+RUBYFORGE:
+  PROJECT: 'calibre'
+  USERNAME: transami
+
+TEST:
+  FILES:
+    - 'test/**/tc_*.rb'
+  OPTIONS: ~
+
+RDOC:
+  TITLE: *title
+  DIR: 'doc'
+  TEMPLATE: html #ruby-red
+  OPTIONS: ['--merge', '--inline-source', --'all']
+  MAIN: README
+  INCLUDE:
+    - 'README'
+    - 'LICEN*'
+    - 'lib/carat/**/*.rb'
+  EXCLUDE: []
+
+PACKAGE:
+  DIR: pkg
+  INCLUDE:
+    - 'lib/**/*'
+    - 'bench/**/*'
+    - 'test/**/*'
+    - 'rdoc/**/*'
+    - 'doc/**/*'
+    - 'pub/**/*'
+    - 'demo/**/*'
+    - 'samples/**/*'
+    - 'examples/**/*'
+    - 'setup.rb'
+    - '[A-Z]*'
+  EXCLUDE:
+    - InstalledFiles
+  ZIP: true
+  GZIP: true
+  BZIP2: true
+  GEM: true
+  
+ANNOUNCE:
+  TO: tranfire@gmail.com
+  FROM: transfire@gmail.com
+  DOMAIN: jupiterzeus.net
+  SERVER: gmail.com
+  PORT: 25
+  ACCOUNT: transfire@gmail.com
+  AUTHTYPE: plain #cram_md5
+  FILE: ANN
+  SLOGAN: ALL YOUR BASE ARE BELONG TO RUBY!
+  INFO:
+    - http://calibre.rubyforge.org
+

data/ToDo

@@ -0,0 +1,24 @@
+
+- Minor:
+  - ordered-hash, would like an improved version.
+  - nil-comparable, works but I think could done better.
+  - lisp, there may be other places where #pair! is needed.
+  - interval, add infinity as possible sentinal.
+  - duckhunter (might be able to use Functor as decoy/probe)
+
+- Carat-dev:
+  - interface
+  - detach
+
+- Tests:
+  - binaryreader
+  - binding_of_caller
+  - coroutine, currently just checks for no error raised
+  - heap
+  - io-reactor
+  - io-redirect
+  - semaphore
+  - tracepoint
+  - 1st, needs some sort of refinement
+  - lisp, needs to be vastly expanded 
+  - lisp_format, code use a few more tests

data/bench/b_harray.rb

@@ -0,0 +1,49 @@
+=begin
+
+Some speed comparisions between standard Array and HArray.
+
+=end
+
+require 'trix/harray'
+require 'benchmark'
+
+$n = 50000
+
+# standard array
+
+def sarray_make
+  $n.times do
+    $sa = [1,'a',nil]
+  end
+end
+
+def sarray_slice
+  $n.times do
+    $sa[1..2]
+  end
+end
+
+# hash array
+
+def harray_make
+  $n.times do
+    $ha = HArray.new_h({0=>1,1=>'a',2=>nil})
+  end
+end
+
+def harray_slice
+  $n.times do
+    $ha[1..2]
+  end
+end
+
+
+### --- bench ---
+
+puts "\nCURRENT"
+Benchmark.bm(15) do |b|
+  b.report("HAarry#new:") { harray_make }
+  b.report("HArray#slice:") { harray_slice }
+  b.report("Array#new:") { sarray_make }
+  b.report("Array#slice:") { sarray_slice }
+end

data/bench/b_range.rb

@@ -0,0 +1,64 @@
+
+require 'benchmark'
+
+# member?
+
+$n = 50000
+
+def range_nan
+  $n.times { ('a'..'k').member?('f') }
+  $n.times { ('a'..'k').member?('r') }
+end
+
+def range_small
+  $n.times { (0..6).member?(3) }
+  $n.times { (0..6).member?(7) }
+end
+
+def range_med
+  $n.times { (0..1000).member?(500) }
+  $n.times { (0..1000).member?(1001) }
+end
+
+# index
+
+$a = [ 'x' ] * 100
+$m = 500000
+
+def range_index
+  i = 1
+  $m.times { $a[1..i]; i += 1 }
+end
+
+def length_index
+  i = 1
+  $m.times { $a[1,i]; i += 1 }
+end
+
+### --- bench ---
+
+puts "\nINDEXING"
+Benchmark.bm(15) do |b|
+  b.report("range_index:") { range_index }
+  b.report("length_index:") { length_index }
+end
+
+puts "\n\nNew vs. Old\n"
+
+puts "\nCURRENT"
+Benchmark.bm(15) do |b|
+  b.report("range_nan:") { range_nan }
+  b.report("range_samll:") { range_small }
+  b.report("range_med:") { range_med }
+end
+
+puts "\nNEW"
+require 'trix-dev/range/range'
+Benchmark.bm(15) do |b|
+  b.report("range_nan:") { range_nan }
+  b.report("range_samll:") { range_small }
+  b.report("range_med:") { range_med }
+end
+
+puts
+

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."
+