rgl 0.2.2

data/ChangeLog

@@ -0,0 +1,74 @@
+2002-11-10  monora  <monora@HDDESKTOP>
+
+	* lib/set.rb, lib/rgl/adjacency.rb, lib/utils.rb:
+	Use knus compatibility library for Ruby 1.8 esp. for set.rb and inject.
+
+2002-09-22  monora  <monora@HDDESKTOP>
+
+	* lib/rgl/dot.rb:
+	to_dot_graph now also outputs vertices.
+
+	* lib/rgl/adjacency.rb: cosmetic.
+
+2002-09-17  monora  <monora@HDDESKTOP>
+
+	* Makefile: Added releasedoc target.
+
+	* lib/rgl/base.rb, lib/rgl/implicit.rb:
+	Fixed typo.
+
+2002-08-29  monora  <monora@HDDESKTOP>
+
+	* ChangeLog, lib/rgl/adjacency.rb, lib/rgl/base.rb, tests/TestDirectedGraph.rb, tests/TestUnDirectedGraph.rb:
+	Changed NameError to NoVertexError.
+
+2002-09-22  monora  <monora@HDDESKTOP>
+
+	* lib/rgl/dot.rb:
+	to_dot_graph now also outputs vertices.
+
+	* lib/rgl/adjacency.rb: cosmetic.
+
+2002-09-17  monora  <monora@HDDESKTOP>
+
+	* Makefile: Added releasedoc target.
+
+	* lib/rgl/base.rb, lib/rgl/implicit.rb:
+	Fixed typo.
+
+2002-08-29  monora  <monora@HDDESKTOP>
+
+	* ChangeLog, lib/rgl/adjacency.rb, lib/rgl/base.rb, tests/TestDirectedGraph.rb, tests/TestUnDirectedGraph.rb:
+	Changed NameError to NoVertexError.
+
+2002-08-29  monora  <monora@hddesktop>
+
+	* TestDirectedGraph.rb, TestUnDirectedGraph.rb:
+	* adjacency.rb, base.rb: Changed NameError to NoVertexError. Fixed Bug Nr. 599872.
+
+2002-08-23  monora  <monora@hddesktop>
+
+	* base.rb, dot.rb, rdot.rb:
+	canvas.rb added. Collision with rdoc/dot.rb removed.
+
+2002-08-19  monora  <monora@hddesktop>
+
+	* traversal.rb: New file.
+
+	* traversal.rb: started at sf
+
+	* adjacency.rb, base.rb, connected_components.rb, dot.rb, graphxml.rb, implicit.rb, mutable.rb, topsort.rb, transitiv_closure.rb:
+	New file.
+
+	* adjacency.rb, base.rb, connected_components.rb, dot.rb, graphxml.rb, implicit.rb, mutable.rb, topsort.rb, transitiv_closure.rb:
+	started at sf
+
+2002-06-10  Horst Duchene  <horst@hduchene.de>
+
+	* lib/rgl/graphxml.rb: added + tests + examples from graphviz catalog
+
+2002-03-21  Horst Duchene  <horst@hduchene.de>
+
+	* Ported tests to Test::Unit
+	* transitive_closure.rb
+

data/Makefile

@@ -0,0 +1,72 @@
+# 
+#  make test   - run the tests
+#  make clean  - tidy up
+#
+
+LIB=./lib
+RGL=rgl-$(VERSION)
+BOOST_DOC=http://www.boost.org/libs/graph/doc
+#BOOST_DOC=file://D:/Programme/bgl/boost_1_25_1/libs/graph/doc
+
+default: test
+test:
+	cd tests && ruby -I../lib runtests.rb
+
+# Release must have VERSION variable set
+#
+#    make VERSION=0.2 release
+#
+
+release: doc stamp clean tar
+
+ftpput: ${RGL}.tgz
+	ftpput.rb $<
+
+releasedoc: doc
+	rm -f htdocs
+	ln -fs doc htdocs
+	tar --dereference --exclude='*.bak' -czf htdocs.tgz htdocs
+	rm htdocs
+	scp htdocs.tgz monora@rgl.sf.net:/home/groups/r/rg/rgl
+
+stamp:
+		ruby -i.bak -pe 'sub!(/V\d+(\.\d+)+/, "V$(VERSION)") if /_VERSION =/' ${LIB}/rgl/base.rb
+		rm ${LIB}/rgl/base.rb.bak
+		cvs commit
+		cvs rtag `echo V$(VERSION) | sed s/\\\\./_/g` rgl
+
+doc: ${LIB}/rgl/*.rb README
+#	cd ${LIB} && rdoc --diagram --fileboxes --title RGL --main rgl/base.rb --op ../doc
+	cd ${LIB} && rdoc.bat --title RGL --main rgl/base.rb --op ../doc
+	cp examples/*.jpg doc
+	find doc -name \*.html -print | xargs	ruby -i.bak -pe 'sub!(/BOOST_DOC.(.*.html)/,"<a href=${BOOST_DOC}/\\1>\\1<a>")'
+
+install:
+	ruby install.rb
+
+tags:
+	 rtags `find ${LIB} -name  '*.rb'`
+
+tar: test
+		ln -fs rgl ../${RGL}
+		tar --directory=..			\
+			--create			\
+			--dereference			\
+			--file=${RGL}.tgz 	\
+			--gzip 			\
+			--exclude='CVS' 		\
+			--exclude='cvs' 		\
+			--exclude='misc' 		\
+			--exclude='doc' 		\
+			--exclude='homepage' 		\
+			--exclude='*.tgz' 		\
+			--exclude='*/.*'		\
+			${RGL}
+		rm ../${RGL}
+
+clean:
+		rm -rf rgl*.tgz graph.dot TAGS examples/*/*.dot
+		find . -name \*~ -print | xargs rm -f
+		find . -name \*.bak -print | xargs rm -f
+		find . -name core -print | xargs rm -f
+

data/README

@@ -0,0 +1,240 @@
+= Ruby Graph Library (RGL)
+
+RGL is a framework for graph data structures and algorithms.
+
+The design of the library is much influenced by the Boost Graph Library (BGL)
+which is written in C++ heavily using its template mechanism. Refer to
+http://www.boost.org/libs/graph/doc for further links and documentation on graph
+data structures and algorithms and the design rationales of BGL.
+
+A comprehensive summary of graph terminology can be found in the the graph
+section of the <em>Dictionary of Algorithms and Data Structures</em> at
+http://www.nist.gov/dads/HTML/graph.html.
+
+== Design principles
+
+This document concentrates on the special issues of the implementation in
+Ruby. The main design goals directly taken from the BGL design are:
+
+* An interface for how the structure of a graph can be accessed using a generic
+  interface that hides the details of the graph data structure
+  implementation. This interface is defined by the module Graph, which should be
+  included in concrete classes.
+
+* A standardized generic interface for traversing graphs (RGL::GraphIterator)
+
+RGL provides some general purpose graph classes that conform to this interface,
+but they are not meant to be the *only* graph classes. As in BGL I believe that
+the main contribution of the RGL is the formulation of this interface.
+
+The BGL graph interface and graph components are generic in the sense of the C++
+Standard Template Library (STL). In Ruby other techniques are available to
+express the generic character of the algorithms and data structures mainly using
+mixins and iterators. The BGL documentation mentions three means to achieve
+genericity:
+
+* Algorithm/Data-Structure Interoperability
+* Extension through Function Objects and Visitors
+* Element Type Parameterization
+* Vertex and Edge Property Multi-Parameterization
+
+The first is easily achieved in RGL using mixins, which of course is not as
+efficient than C++ templates (but much more readable :-). The second one is even
+more easily implemented using standard iterators with blocks or using the
+Stream module. The third one is no issue since Ruby is dynamically typed: Each
+object can be a graph vertex. There is no need for a vertex (or even edge
+type). In the current version of RGL properties of vertices are simply attached
+using hashes. At first there seems to be not much need for the graph property
+machinery.
+
+=== Algorithms
+
+The first version of RGL only contains a core set of algorithm patterns:
+
+* Breadth First Search (RGL::BFSIterator)
+* Depth First Search (RGL::DFSIterator)
+
+The algorithm patterns by themselves do not compute any meaningful quantities
+over graphs, they are merely building blocks for constructing graph
+algorithms. The graph algorithms in RGL currently include:
+
+* Topological Sort (RGL::TopsortIterator)
+* Connected Components (RGL::Graph#each_connected_component)
+* Strongly Connected Components (RGL::Graph#strongly_connected_components)
+* Transitive Closure (RGL::Graph#transitive_closure)
+
+=== Data Structures
+
+RGL currently provides two graph classes that implement a generalized adjacency
+list and an edge list adaptor.
+
+* RGL::AdjacencyGraph
+* RGL::ImplicitGraph
+
+The AdjacencyGraph class is the general purpose *swiss army knife* of graph
+classes. It is highly parameterized so that it can be optimized for different
+situations: the graph is directed or undirected, allow or disallow parallel
+edges, efficient access to just the out-edges, fast vertex insertion and removal
+at the cost of extra space overhead, etc.
+
+=== Differences to BGL
+
+The concepts of IncidenceGraph, AdjacencyGraph and VertexListGraph (see
+http://www.boost.org/libs/graph/doc/IncidenceGraph.html) are here bundled in the
+base graph module. Most methods of IncidenceGraph should be standard in the base
+module Graph. The complexity guarantees can not necessarily provided.  See
+http://www.boost.org/libs/graph/doc/graph_concepts.html
+
+== Installation
+
+RGL is depended on the _stream_ library which can also be downloaded from
+http://rubyforge.org/frs/?group_id=110.
+
+=== GEM Installation
+
+Download the GEM file and install it with ..
+
+   gem install rgl-VERSION.gem
+
+or directly with 
+
+   gem install rgl
+
+Use the correct version number for VERSION (e.g. 0.2.2).  You may need root
+privileges to install.
+
+=== Normal Installation
+
+You have to install stream library before. You can than install RGL with the
+following command:
+
+  % ruby install.rb
+
+from its distribution directory.
+
+== Example irb session with RGL
+
+  irb> require 'rgl/adjacency'
+  irb> dg=RGL::DirectedAdjacencyGraph[1,2 ,2,3 ,2,4, 4,5, 6,4, 1,6]
+  # Use DOT to visualize this graph:
+  irb> require 'rgl/dot'
+  irb> dg.write_to_graphic_file('jpg')
+  "graph.jpg"
+  
+The result: link:../examples/example.jpg  
+  
+  irb> dg.directed?
+  true
+  irb> dg.vertices
+  [5, 6, 1, 2, 3, 4]
+  irb> dg.has_vertex? 4
+  true
+
+Every object could be a vertex (there is no class Vertex), even the class object
+_Object_:
+
+  irb> dg.has_vertex? Object
+  false
+  irb> dg.edges.sort.to_s
+  "(1-2)(1-6)(2-3)(2-4)(4-5)(6-4)"
+  irb> dg.to_undirected.edges.sort.to_s
+  "(1=2)(1=6)(2=3)(2=4)(5=4)(6=4)"
+
+Add inverse edge (4-2) to directed graph:
+
+  irb> dg.add_edge 4,2
+
+(4-2) == (2-4) in the undirected graph:
+
+  irb> dg.to_undirected.edges.sort.to_s
+  "(1=2)(1=6)(2=3)(2=4)(5=4)(6=4)"
+
+(4-2) != (2-4) in directed graphs:
+
+  irb> dg.edges.sort.to_s
+  "(1-2)(1-6)(2-3)(2-4)(4-2)(4-5)(6-4)"
+  irb> dg.remove_edge 4,2
+  true
+
+<em>Topological sort</em> is realized with as iterator:
+
+  require 'graph/traversal'
+  irb> dg.topsort_iterator.to_a
+  [1, 2, 3, 6, 4, 5]
+
+A more elaborated example showing <em>implicit graphs</em>:
+
+  def module_graph
+	RGL::ImplicitGraph.new { |g|
+	  g.vertex_iterator { |b|
+		ObjectSpace.each_object(Module, &b) 
+	  }
+	  g.adjacent_iterator { |x, b|
+		x.ancestors.each { |y|
+		  b.call(y) unless x == y || y == Kernel || y == Object
+		}
+	  }
+	  g.directed = true
+	}
+  end
+
+This function creates a directed graph with vertices being all loaded modules:
+
+  g = module_graph
+
+We only want to see the ancestors of RGL::AdjacencyGraph:
+
+  tree = bfs_search_tree_from(g,RGL::AdjacencyGraph)
+
+Now we want to visualize this component of g with DOT. We therefore create a
+subgraph of the original graph using a filtered graph:
+
+  g = g.vertices_filtered_by {|v| tree.has_vertex? v}
+
+Create the graphics with DOT:
+
+  g.write_to_graphic_file
+
+produces module_graph.jpg: link:../examples/module_graph.jpg
+
+Look for more in the examples directory (i.e.
+examples.rb[link:files/examples/examples_rb.html]).
+
+== Credits
+
+Many thanks to Robert Feldt which also worked on a graph library
+(http://rockit.sf.net/subprojects/graphr) who pointed me to BGL and many other
+graph resources. Manuel Simoni found a subtle bug in a preliminary version
+announced at http://rubygarden.com/ruby?RubyAlgorithmPackage/Graph.
+
+Robert kindly allowed to integrate his work on graphr, which I did not yet
+succeed. Especially his work to output graphs for GraphViz (see
+http://www.research.att.com/sw/tools/graphviz/download.html) is much more
+elaborated than the minimal support in dot.rb.
+
+Jason Voegele for set.rb implementing sets using hashes. These are used in the
+implementation of adjacency lists in AdjacencyGraph.
+
+Jeremy Siek one of the authors of the nice book "The Boost Graph Library (BGL)"
+(http://cseng.awl.com/book/0,3828,0201729148,00.html) kindly allowed to use the
+BGL documentation as a _cheap_ reference for RGL. He and Robert also gave
+feedback and many ideas for RGL.
+
+Dave Thomas for RDoc (http://rdoc.sourceforge.net) which generated what you read
+and matz for Ruby. Dave included in the latest version of RDoc (alpha9) the
+module dot/dot.rb which I use instead of Roberts module to visualize graphs (see
+rgl/dot.rb).
+
+== Copying
+
+RGL is Copyright (c) 2002,2004 by Horst Duchene.  It is free software, and may be
+redistributed under the terms specified in the README file of the Ruby
+distribution.
+
+== Support
+
+Please contact me at mailto:monora@users.sourceforge.net with bug reports
+suggestions, and other comments. If you send patches, it would help if
+they were in-line (not attachments) and generated using "diff -u".
+
+

data/Rakefile

@@ -0,0 +1,210 @@
+# Rakefile for RGL        -*- ruby -*-
+
+begin
+  require 'rubygems'
+  require 'rake/gempackagetask'
+rescue Exception
+  nil
+end
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+# Determine the current version of the software
+
+if `ruby -Ilib -rrgl/base -e'puts RGL_VERSION'` =~ /\S+$/
+  PKG_VERSION = $&
+else
+  PKG_VERSION = "0.0.0"
+end
+
+SUMMARY = "Ruby Graph Library"
+SOURCES = FileList['lib/**/*.rb']
+RDOC_DIR = './rgl'
+
+# 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 rgl using the standard install.rb script.
+
+desc "Install the application"
+task :install do
+  ruby "install.rb"
+end
+
+# CVS Tasks ----------------------------------------------------------
+
+desc "Tag all the CVS files with the latest release number (TAG=x)"
+task :tag do
+  rel = "REL_" + PKG_VERSION.gsub(/\./, '_')
+  rel << ENV['TAG'] if ENV['TAG']
+  puts rel
+  sh %{cvs commit -m 'pre-tag commit'}
+  sh %{cvs tag #{rel}}
+end
+
+# Create a task to build the RDOC documentation tree.
+
+rd = Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = RDOC_DIR
+#  rdoc.template = 'kilmer'
+#  rdoc.template = 'css2'
+  rdoc.title    = SUMMARY
+  rdoc.options << '--line-numbers' << '--inline-source' <<
+     '--main' << 'README'
+  rdoc.rdoc_files.include(SOURCES, 'README', 'examples/examples.rb')
+}
+
+# ====================================================================
+# Create a task that will package the rgl software into distributable
+# tar, zip and gem files.
+
+PKG_FILES = FileList[
+  'install.rb',
+  '[A-Z]*',
+  'tests/**/*.rb',
+  'examples/**/*'
+] + SOURCES
+
+if ! defined?(Gem)
+  puts "Package Target requires RubyGEMs"
+else
+  spec = Gem::Specification.new do |s|
+    
+    #### Basic information.
+
+    s.name = 'rgl'
+    s.version = PKG_VERSION
+    s.summary = SUMMARY
+
+    s.description = <<-EOF
+    RGL is a framework for graph data structures and algorithms.
+
+    The design of the library is much influenced by the Boost Graph Library (BGL)
+    which is written in C++ heavily using its template mechanism.
+
+
+    RGL currently contains a core set of algorithm patterns:
+
+
+     * Breadth First Search 
+     * Depth First Search 
+
+    The algorithm patterns by themselves do not compute any meaningful quantities
+    over graphs, they are merely building blocks for constructing graph
+    algorithms. The graph algorithms in RGL currently include:
+
+     * Topological Sort 
+     * Connected Components 
+     * Strongly Connected Components 
+     * Transitive Closure
+    EOF
+
+    #### Dependencies and requirements.
+
+    s.add_dependency('stream', '>= 0.5')
+    s.requirements << "Stream library, v0.5 or later"
+
+    #### Which files are to be included in this gem?  Everything!  (Except CVS directories.)
+    s.files = PKG_FILES.to_a
+
+    #### Load-time details: library and application (you will need one or both).
+
+    s.require_path = 'lib'                         # Use these for libraries.
+    s.autorequire = 'rgl'
+
+    #### Documentation and testing.
+
+    s.has_rdoc = true
+    s.extra_rdoc_files = ['README']
+    s.rdoc_options <<
+      '--title' <<  'RGL - Ruby Graph Library' <<
+      '--main' << 'README' <<
+      '--line-numbers'
+
+    #### Author and project details.
+    s.author = "Horst Duchene"
+    s.email = "hd.at.clr@hduchene.de"
+    s.homepage = "rgl.rubyforge.org"
+    s.rubyforge_project = "rgl"
+  end
+
+  Rake::GemPackageTask.new(spec) do |pkg|
+    #pkg.need_zip = true
+    pkg.need_tar = true
+  end
+end
+
+# TAGS ---------------------------------------------------------------
+
+file 'tags' => SOURCES do
+  print "Running ctags..."
+  sh %{ctags #{SOURCES.join(' ')}}             # vi tags
+  puts "done."
+end
+
+file 'TAGS' => SOURCES do
+  sh %{ctags -e #{SOURCES.join(' ')}}          # emacs TAGS
+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")
+  SOURCES.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
+
+desc "Copy rdoc html to rubyforge"
+task :rdoc2rf => [:rdoc] do
+  #sh "scp -r #{RDOC_DIR} monora@rubyforge.org:/var/www/gforge-projects/rgl"
+  sh "scp examples/*.jpg monora@rubyforge.org:/var/www/gforge-projects/rgl/examples"
+end