rgl 0.5.1 → 0.5.7

data/README.rdoc

@@ -1,248 +0,0 @@
-= Ruby Graph Library (RGL) {<img src="https://secure.travis-ci.org/monora/rgl.png?branch=master" alt="Build Status" />}[https://travis-ci.org/monora/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
-{http://www.rubydoc.info/github/monora/stream 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
-
-RGL current 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}
-* Dijkstras Shortest Path Algorithm {RGL::DijkstraAlgorithm}
-* Bellman Ford Algorithm {RGL::BellmanFordAlgorithm}
-
-=== 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
-
-  % gem install rgl
-
-or download the latest sources from the git repository http://github.com/monora/rgl.
-
-== Running tests
-
-Checkout RGL git repository and go to the project directory. First, install RGL
-dependencies with bundler:
-
- % bundle install
-
-After that you can run the tests:
-
- % rake test
-
-To see tests coverage run rcov[http://github.com/relevance/rcov] rake task:
-
- % rake rcov
-
-This command will generate tests coverage report in coverage/ directory.
-
-<em>Node: rcov is not compatible with Ruby >= 1.9, so this rake task is
-available only on Ruby 1.8.</em>
-
-== 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:images/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 implemented as an iterator:
-
-  require 'rgl/topsort'
-  irb> dg.topsort_iterator.to_a
-  [1, 2, 3, 6, 4, 5]
-
-A more elaborated example showing <em>implicit graphs</em>:
-
-  require 'rgl/implicit'
-  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}:
-
-  require 'rgl/traversal'
-  tree = g.bfs_search_tree_from(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}
-  g.write_to_graphic_file('jpg')
-
-creates the following graph image with DOT:
-
-link:images/module_graph.jpg
-
-This graph shows all loaded RGL modules:
-
-link:images/rgl_modules.png
-
-Look for more in _examples_ directory (i.e. {file:examples/examples.rb}).
-
-== My del.icio.us links concerning RGL
-
-I collect some links to stuff around RGL at http://del.icio.us/monora/rgl.
-
-== 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.
-
-Robert kindly allowed to integrate his work on graphr, which I did not yet
-succeed. Especially his work to output graphs for
-GraphViz[http://www.research.att.com/sw/tools/graphviz/download.html] is much
-more elaborated than the minimal support in dot.rb.
-
-Jeremy Siek one of the authors of the nice book "The Boost Graph Library (BGL)"
-(http://www.boost.org/libs/graph/doc) 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).
-
-Jeremy Bopp, John Carter, Sascha Doerdelmann, Shawn Garbett, Andreas Schörk
-and Kirill Lashuk for contributing additions, test cases and bugfixes.
-
-Kirill Lashuk who started to take over further development in November 2012.
-
-See also http://github.com/monora/rgl/contributors.
-
-== Copying
-
-RGL is Copyright (c) 2002,2004,2005,2008,2013,2015 by Horst Duchene. It is free software,
-and may be redistributed under the terms specified in the README file of the
-Ruby distribution.
-

data/lib/rgl/enumerable_ext.rb

@@ -1,16 +0,0 @@
-module Enumerable
-
-  # Fixnum()
-  #
-  # Return the number of elements of the Enumerable. Same as _size_ but not all
-  # Enumerables implement size.
-  #--
-  # Should we call the methods _size_?
-  #
-  def length
-    inject(0) do |sum, v|
-      sum + 1
-    end
-  end
-
-end