stream 0.5

data/README

@@ -0,0 +1,174 @@
+= Extended External Iterators (forward and backward)
+
+== Description
+
+Module Stream defines an interface for external iterators. A stream can be
+seen as an iterator on a sequence of objects x1,...,xn. The state of the
+stream is uniquely determined by the following methods:
+
+* at_beginning?
+* at_end?
+* current
+* peek
+
+State changes are done with the following operations:
+
+* set_to_begin
+* set_to_end
+* forward
+* backward
+
+With the help of the method current_edge the state of a stream s can be
+exactly defined
+
+ s.current_edge == [s.current, s.peek]
+
+If s a stream on [x1,...,xn]. Consider the edges [xi,xi+1] i=1,...,n and
+[x0,x1] and [xn,xn+1] (x0 and xn are helper elements to define the boundary
+conditions). Then if s is non empty, the following conditions must be true:
+
+ s.at_beginning? <=> s.current_edge == [x0,x1]
+ s.at_end? <=> s.current_edge == [xn,xn+1]
+ s.isEmpty? <=> s.at_beginning? && s.at_end? <=> s.current_edge == [x0,x1] <=> n = 0
+ s.set_to_end => s.at_end?
+ s.set_to_begin => s.at_beginning?
+
+If 0 <= i < n and s.current_edge == [xi, xi+1] , then:
+
+ [s.forward, s.current_edge] == [xi+1, [xi+1, xi+2]]
+
+If 1 <= i < n and s.current_edge == [xi, xi+1] , then:
+
+ [s.backward, s.current_edge] == [xi, [xi-1, xi]]
+
+The result of peek is the same as of forward without changing state. The result of
+current is the same as of backward without changing state.
+
+Module Stream includes Enumerable implementing #each in the obvious way.
+
+Not every stream needs to implement #backward and #at_beginning? thus being
+not reversable. If they are reversable peek can easily be implemented using
+forward and backward, as is done in module Stream. If a stream is not
+reversable all derived streams provided by the stream module (filter,
+mapping, concatenation) can be used anyway. Explicit or implicit (via peek or
+current) uses of backward would throw a NotImplementedError.
+
+Classes implementing the stream interface must implement the following methods:
+
+* basic_forward
+* basic_backward
+
+* at_end?
+* at_beginning?
+
+The methods set_to_end and set_to_begin are by default implemented as:
+
+ set_to_end   :  until at_end?; do basic_forward end
+ set_to_begin :  until at_beginning?; do basic_backward end
+
+The methods forward and backward are by default implemented as:
+
+ forward:	   raise EndOfStreamException if at_end?; basic_forward.
+ backward:   raise EndOfStreamException if at_beginning?; basic_backward
+
+Thus subclasses must only implement *four* methods. Efficiency sometimes
+demands better implementations.
+
+There are several concrete classes implementing the stream interface:
+
+* Stream::EmptyStream (boring)
+* Stream::CollectionStream created by the method Array#create_stream
+* Stream::FilteredStream created by the method Stream#filtered
+* Stream::ReversedStream created by the method Stream#reverse
+* Stream::ConcatenatedStream created by the method Stream#concatenate
+* Stream::ImplicitStream using closures for the basic methods to implement
+
+== Download
+
+The latest version of stream.rb can be found at
+
+* http://rubyforge.org/frs/?group_id=110
+
+== Installation
+
+=== Normal Installation
+
+You can install stream with the following command.
+
+  % ruby install.rb
+
+from its distribution directory.
+
+=== GEM Installation
+
+Download the GEM file and install it with ..
+
+   gem -i stream-VERSION.gem
+
+Use the correct version number for VERSION (e.g. 0.5).  You may need
+root privileges to install.
+
+== See also
+
+* Streams in Smalltalk: http://wiki.cs.uiuc.edu/PatternStories/FunWithStreams
+* Simon Strandgaards iterator.rb[http://aeditor.rubyforge.org/iterator/files/iterator_rb.html]
+* IterationStyles: http://www.rubygarden.org/ruby?IterationStyles
+
+== Examples
+
+  g = ('a'..'f').create_stream
+  h = (1..10).create_stream
+  i = (10..20).create_stream
+
+  until g.at_end? || h.at_end? || i.at_end?
+    p [g.forward, h.forward, i.forward]
+  end
+
+  def filestream fname
+    Stream::ImplicitStream.new { |s|
+      f = open(fname)
+      s.at_end_proc = proc {f.eof?}
+      s.forward_proc = proc {f.readline}
+      # Need not implement backward moving to use the framework
+    }
+  end
+
+  (filestream("/etc/passwd") + ('a'..'f').create_stream + filestream("/etc/group")).each do |l|
+    puts l
+  end
+
+  puts "\nTwo filtered collection streams concatenated and reversed:\n\n"
+
+  def newstream; (1..6).create_stream; end
+  s = newstream.filtered { |x| x % 2 == 0 } + newstream.filtered { |x| x % 2 != 0 }
+  s = s.reverse
+  puts "Contents      : #{s.to_a.join ' '}"
+  puts "At end?       : #{s.at_end?}"
+  puts "At beginning? : #{s.at_beginning?}"
+  puts "2xBackwards   : #{s.backward} #{s.backward}"
+  puts "Forward       : #{s.forward}"
+  puts "Peek          : #{s.peek}"
+  puts "Current       : #{s.current}"
+  puts "set_to_begin    : Peek=#{s.set_to_begin;s.peek}"
+
+  # an infinite stream (do not use set_to_end!)
+  def randomStream
+    Stream::ImplicitStream.new { |s|
+      s.set_to_begin_proc = proc {srand 1234}
+      s.at_end_proc = proc {false}
+      s.forward_proc = proc {rand}
+    }
+  end
+  s = randomStream.filtered { |x| x >= 0.5 }.collect { |x| sprintf("%5.2f ",x*100) }
+  puts "5 random numbers: #{(1..5).collect {|x| s.forward}}\n" # =>
+
+    5 random numbers: 74.05 94.80 87.87 86.07 83.70
+
+== Other Stuff
+
+$Revision: 1.1.1.1 $
+$Date: 2004/05/13 23:30:03 $
+
+Author:: Horst Duchene <hd.at.clr@hduchene.de>
+License:: Copyright (c) 2001, 2004 Horst Duchene
+Released under the same license as Ruby

data/Rakefile

@@ -0,0 +1,161 @@
+# Rakefile for         -*- ruby -*-
+
+begin
+  require 'rubygems'
+rescue Exception
+  nil
+end
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+# Determine the current version of the software
+
+if `ruby -Ilib -rstream -e'puts STREAM_VERSION'` =~ /\S+$/
+  PKG_VERSION = $&
+else
+  PKG_VERSION = "0.0.0"
+end
+
+SRC_RB = FileList['lib/*.rb']
+
+# The default task is run if rake is given no explicit arguments.
+
+desc "Default Task"
+task :default => :test
+
+# Define a test task.
+
+Rake::TestTask.new { |t|
+  #t.libs << "tests"
+  #t.pattern = 'tests/Test*.rb'
+  t.verbose = true
+}
+
+task :test
+
+# Define a test that will run all the test targets.
+desc "Run all test targets"
+task :testall => [:test ]
+
+# Install stream using the standard install.rb script.
+
+desc "Install the application"
+task :install do
+  ruby "install.rb"
+end
+
+# Create a task to build the RDOC documentation tree.
+
+rd = Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = 'html'
+#  rdoc.template = 'kilmer'
+#  rdoc.template = 'css2'
+  rdoc.title    = "Stream - Extended External Iterators"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/*.rb', 'doc/**/*.rdoc')
+}
+
+# ====================================================================
+# Create a task that will package the stream software into distributable
+# tar, zip and gem files.
+
+PKG_FILES = FileList[
+  'install.rb',
+  '[A-Z]*',
+  'lib/**/*.rb', 
+  'test/**/*.rb',
+  'examples/**/*'
+]
+
+if ! defined?(Gem)
+  puts "Package Target requires RubyGEMs"
+else
+  spec = Gem::Specification.new do |s|
+    
+    #### Basic information.
+
+    s.name = 'stream'
+    s.version = PKG_VERSION
+    s.summary = "Stream - Extended External Iterators"
+    s.description = <<-EOF
+      Module Stream defines an interface for external iterators.
+    EOF
+
+    #### Dependencies and requirements.
+
+    #s.add_dependency('log4r', '> 1.0.4')
+    #s.requirements << ""
+
+    #### Which files are to be included in this gem?  Everything!  (Except CVS directories.)
+
+    s.files = PKG_FILES.to_a
+
+    #### C code extensions.
+
+    #s.extensions << "ext/rmagic/extconf.rb"
+
+    #### Load-time details: library and application (you will need one or both).
+
+    s.require_path = 'lib'                         # Use these for libraries.
+    s.autorequire = 'stream'
+
+    #### Documentation and testing.
+
+    s.has_rdoc = true
+    #s.test_suite_file = "test/rmagic-tests.rb"
+
+    #### Author and project details.
+    s.author = "Horst Duchene"
+    s.email = "hd.at.clr@hduchene.de"
+    s.homepage = "http://rgl.rubyforge.org"
+    s.rubyforge_project = "rgl"
+  end
+
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar = true
+  end
+end
+
+# Misc tasks =========================================================
+
+def count_lines(filename)
+  lines = 0
+  codelines = 0
+  open(filename) { |f|
+    f.each do |line|
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+  }
+  [lines, codelines]
+end
+
+def show_line(msg, lines, loc)
+  printf "%6s %6s   %s\n", lines.to_s, loc.to_s, msg
+end
+
+desc "Count lines in the main files"
+task :lines do
+  total_lines = 0
+  total_code = 0
+  show_line("File Name", "LINES", "LOC")
+  SRC_RB.each do |fn|
+    lines, codelines = count_lines(fn)
+    show_line(fn, lines, codelines)
+    total_lines += lines
+    total_code  += codelines
+  end
+  show_line("TOTAL", total_lines, total_code)
+end
+
+ARCHIVEDIR = '/mnt/flash'
+
+task :archive => [:package] do
+  cp FileList["pkg/*.tgz", "pkg/*.zip", "pkg/*.gem"], ARCHIVEDIR
+end

data/examples/examples.rb

@@ -0,0 +1,51 @@
+require 'stream'
+
+# Example from knu's Generator.rb
+g = ('a'..'f').create_stream
+h = (1..10).create_stream
+i = (10..20).create_stream
+
+until g.at_end? || h.at_end? || i.at_end?
+  p [g.forward, h.forward, i.forward]
+end
+
+puts "Concatenate Filestreams and collection stream:\n"
+
+def fs fname
+  Stream::ImplicitStream.new { |s|
+	f = open(fname)
+	s.at_end_proc = proc {f.eof?}
+	s.forward_proc = proc {f.readline}
+	# Need not implement backward moving to use the framework
+  }
+end
+
+(fs("/etc/passwd") + ('a'..'f').create_stream + fs("/etc/group")).each do |l|
+	puts l
+end
+
+puts "\nTwo filtered collection streams concatenated and reversed:\n\n"
+
+def newstream; (1..6).create_stream; end
+s = newstream.filtered { |x| x % 2 == 0 } \
+		+ newstream.filtered { |x| x % 2 != 0 }
+s = s.reverse
+puts "Contents      : #{s.to_a.join ' '}"
+puts "At end?       : #{s.at_end?}"
+puts "At beginning? : #{s.at_beginning?}"
+puts "2xBackwards   : #{s.backward} #{s.backward}"
+puts "Forward       : #{s.forward}"
+puts "Peek          : #{s.peek}"
+puts "Current       : #{s.current}"
+puts "set_to_begin    : Peek=#{s.set_to_begin;s.peek}"
+
+# an infinite stream (do not use set_to_end!)
+def randomStream
+  Stream::ImplicitStream.new { |s|
+	  s.set_to_begin_proc = proc {srand 1234}
+	  s.at_end_proc = proc {false}
+	  s.forward_proc = proc {rand}
+	}
+end
+s = randomStream.filtered { |x| x >= 0.5 }.collect { |x| sprintf("%5.2f ",x*100) }
+puts "5 random numbers: #{(1..5).collect {|x| s.forward}}\n"

data/examples/streamtester.rb

@@ -0,0 +1,59 @@
+#
+# Simple stream test interface based on Ruby-FLTK
+# See: (http://ruby-fltk.sourceforge.net/)
+#
+require 'fltk'
+require 'stream'
+
+class StreamTester < Fltk::Window
+  include Stream
+  def initialize (s)
+	super(200,200)
+	@stream = s
+
+	pack = Fltk::Pack.new(200,200) {
+	  %w{set_to_begin set_to_end forward backward at_end? at_beginning? current_edge entries inspect}.each { |m|
+		Fltk::Button.new(50,20,m) {|w,data|
+		  @output.value(sendMsg(m))
+		  puts sendMsg(m)
+		}
+	  }
+	  @output= Fltk::Input.new(200, 20)
+	  @output.deactivate
+	}
+	pack.packtype = Fltk::VERTICAL
+	self.add(pack)
+	self.show
+  end
+
+  def sendMsg(m)
+	begin
+	  @stream.send(m).inspect
+	rescue EndOfStreamException => msg
+	  msg
+	end
+  end
+end
+
+module Stream
+  def openTester
+	StreamTester.new(self)
+	Fltk::run()
+  end
+end
+
+if $0 == __FILE__
+  def newstream; (1..6).create_stream; end
+  s = newstream.filtered { |x| x % 2 == 0 } \
+		+ newstream.filtered { |x| x % 2 != 0 }
+  s.reverse.openTester
+
+  # an infinite stream (do not use set_to_end!)
+  randomStream =
+	Stream::ImplicitStream.new { |s|
+	s.set_to_begin_proc = proc {srand 1234}
+	s.at_end_proc = proc {false}
+	s.forward_proc = proc {rand}
+  }
+  randomStream.filtered { |x| x >= 0.5 }.collect { |x| x*100 }.openTester
+end

data/install.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+require 'rbconfig'
+require 'ftools'
+require 'find'
+
+SRC_BASE = 'lib'
+INSTDIR = File.join Config::CONFIG['sitedir']
+
+def install
+  begin
+    pwd = Dir.pwd
+    Dir.chdir(SRC_BASE)
+	Dir['*.rb'].each do |file|
+      dst = File.join( INSTDIR, file )
+      File.install(file, dst, 0644, true)
+    end
+    Dir.chdir(pwd)
+  rescue
+    puts $!
+  end
+end
+
+install