rgl 0.5.1 → 0.5.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b92e64e8461dc9a3f9f471e68c9a2876e93a44f5b858e0a40a30b6933e5136a8
+  data.tar.gz: f820274113a375f61620272c1eb6a11127562867e8fe9af8bc20cf075aca5fc6
+SHA512:
+  metadata.gz: 8e887b25cc41ead029b67a58a21ce02536baf92a44912d8ff2208b04477ffd9556fde68dd0c4663caa9341cecd58b8102bfafe7df7512b5cbc7285764d0952e2
+  data.tar.gz: a610a0225a9c63fb83a841053377b07ee0d59dabf12a4379c30a1f8c27c5618e245f9d10f5f3f5c2aef08ddb323c3e4d357ad432d0c24be49701f8fe336340ef

data/ChangeLog

@@ -1,41 +1,97 @@
+2019-01 Release 0.5.7
+
+Horst Duchene
+ * Fully automate dev setup with Gitpod (41dd00)
+ * Add Dockerfile to install graphviz (2bd738)
+ * Examples do not call dotty (6bba96)
+ * Add ruby license file (a21aa5)
+ujihisa <ujihisa@users.noreply.github.com>
+ * Test against Ruby 2.6 and 2.7 as well (50ac7c)
+ * Fix dead links (9184f3)
+Harry Lascelles <hlascelles@users.noreply.github.com>
+ * Update .travis.yml (45b9a2)
+ * Make the links more explicit (95dc3b)
+Harry Lascelles
+ * Add explicit license to gemspec (de3647)
+
+2019-01 Release 0.5.6
+
+Artemy Kirienko
+ * PR #42 Add method Graph#path?(u, v) to check if a path exists between two vertices
+Horst Duchene
+ * Fix #47 set_to_begin for graph iterator (881aa8)
+
+2019-01 Release 0.5.4
+
+Lia Skalkos
+ * Enable options to be passed to #write_to_graphic_file (4ca972). For details see PR #41
+Horst Duchene
+ * Fix travis-ci errors
+ * Add new ruby versions
+ * Fix gemspec errors
+ * Fix lint warnings
+ * Use version stream 0.5.2
+
+2017-04 Release 0.5.3
+
+Horst Duchene
+ * Issue #38: Add error handling or dot functions. (719e38, 5a3423)
+Thomas Orozco
+ * Remove Enumerable Extension (fde8a5)
+ * Update to codeclimate-test-reporter 1.x (25fdb5)
+Mario Daskalov
+ * Clarify that you need graphviz in the README (35a4b4)
+
+2016-05 Release 0.5.2
+
+Horst Duchene
+ * Issue #21: Use new method vertex_id instead of object_id to identify vertices in dot export. (fa7592)
+ * Integrate Code Climate's test coverage reporting (0ab722)
+ * Clarify traversal order of DFS search (see #20). (afa788)
+Chase Gilliam
+ * drop 1.9.3 add newer jruby and rubinius (fad333)
+Matías Battocchia
+ * Switched to a different heap implementation. (bd7c13)
+gorn
+ * Adding failing test for issue #24 (1f6204)
+
 2015-12 Release 0.5.1
 
-Horst Duchene <monora@gmail.com>
+Horst Duchene
  * Changed edge sequence to match example picture (daa88e)
 
-Chase <chase.gilliam@gmail.com>
+Chase
  * updated algorithms to 6.1 and added test unit to support newer rubies (fbd874)
 
-Louis Rose <louismrose@gmail.com>
+Louis Rose
  * Fix #15. Use object IDs rather than labels to identify vertexs in DOT graph
    to ensure that distinct nodes that share a label are shown. (33206f, 4fc455)
 
 2014-12 Release 0.5.0
 
-Horst Duchene <monora@gmail.com>
+Horst Duchene
   * Changed edge sequence to match example picture (daa88e)
   * Fixed comment (6a6c93)
   * Fixed spelling (7ca281)
-Horst Duchêne <monora@gmail.com>
-Chase <chase.gilliam@gmail.com>
+Horst Duchêne
+Chase
   * updated algorithms to 6.1 and added test unit to support newer rubies (fbd874)
-Louis Rose <louismrose@gmail.com>
+Louis Rose
   * Fix #15. Use object IDs rather than labels to identify vertexs in DOT graph to ensure that distinct nodes that share a label are shown. (33206f)
-	* Issue #15. Fix tests. (4fc455)
-
+  * Issue #15. Fix tests. (4fc455)
 
 2014-12 Release 0.5.0
-Horst Duchene <monora@gmail.com>
+Horst Duchene
   * Changed edge sequence to match example picture (daa88e)
   * Fixed comment (6a6c93)
   * Fixed spelling (7ca281)
-Horst Duchêne <monora@gmail.com>
-Chase <chase.gilliam@gmail.com>
+Chase
   * updated algorithms to 6.1 and added test unit to support newer rubies (fbd874)
-Louis Rose <louismrose@gmail.com>
-  * Fix #15. Use object IDs rather than labels to identify vertexs in DOT graph to ensure that distinct nodes that share a label are shown. (33206f)
-	* Issue #15. Fix tests. (4fc455)
-
+Louis Rose
+  * Fix #15. Use object IDs rather than labels to identify vertexs
+	in DOT graph to ensure that distinct nodes that share a label are
+	shown. (33206f)
+  * Issue #15. Fix tests. (4fc455)
 
 2014-12 Release 0.5.0
 

data/Gemfile

@@ -2,6 +2,7 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'rake'
-gem 'yard'
-gem 'asciidoctor'
+group :test do
+  gem "simplecov"
+  gem "codeclimate-test-reporter", "~> 1.0.0"
+end

data/README.md

@@ -0,0 +1,267 @@
+# 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) [<img src="https://codeclimate.com/github/monora/rgl/badges/coverage.svg" />](https://codeclimate.com/github/monora/rgl/coverage) [<img src="https://badge.fury.io/rb/rgl.svg" alt="Version"/>](https://badge.fury.io/rb/rgl)[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/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++. 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 graph section
+of the *Dictionary of Algorithms and Data Structures* at
+http://www.nist.gov/dads/HTML/graph.html or
+[Wikipedia](https://en.wikipedia.org/wiki/Graph_%28discrete_mathematics%29).
+
+## Documentation
+
+*   RGL's [API Reference](http://www.rubydoc.info/github/monora/rgl) at
+    http://rubydoc.info
+
+
+## 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 {RGL::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](http://www.rubydoc.info/github/monora/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.
+
+If you are going to use the drawing functionalities install [Graphviz](http://www.graphviz.org/).
+
+## 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
+
+## Example irb session with RGL
+
+    % irb -Ilib
+
+    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:
+
+![Example](https://github.com/monora/rgl/raw/master/images/example.jpg)
+
+You can control the graph layout by passing layout parameters to `write_to_graphic_file`. See
+`TestDot::test_to_dot_digraph_with_options` for an example using a feature implemented by Lia
+Skalkos (see [PR #41](https://github.com/monora/rgl/pull/41)).
+
+    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
+
+Check whether a path exists between vertices 1 and 5
+
+    irb> require 'rgl/path'
+    irb> dg.path?(1, 5)
+    true
+
+*Topological sort* 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 *implicit graphs*:
+
+    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:
+
+![Module graph](https://github.com/monora/rgl/raw/master/images/module_graph.jpg)
+
+This graph shows all loaded RGL modules:
+
+![RGL Modules](https://github.com/monora/rgl/raw/master/images/rgl_modules.png)
+
+Look for more in
+[examples](https://github.com/monora/rgl/tree/master/examples) directory.
+
+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.graphviz.org) 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](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,2019,2020 by Horst
+Duchene. It is free software, and may be redistributed under the [Ruby
+license](https://en.wikipedia.org/wiki/Ruby_License) and terms specified in
+the LICENSE file.

data/Rakefile

@@ -6,16 +6,16 @@ require 'bundler/setup'
 require 'rubygems/package_task'
 
 require 'rake/testtask'
+require 'rake/clean'
 require 'yard'
 
 $:.unshift File.join(File.dirname(__FILE__), 'lib')
 require 'rgl/base' # require base module to get RGL_VERSION
 
-SUMMARY = "Ruby Graph Library"
 SOURCES = FileList['lib/**/*.rb']
 
 # The default task is run if rake is given no explicit arguments.
-desc "Default Task"
+desc 'Default Task'
 task :default => :test
 
 # Define a test task.
@@ -26,23 +26,9 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
-begin
-  require 'rcov/rcovtask'
-
-  desc "Calculate code coverage with rcov"
-  Rcov::RcovTask.new(:rcov) do |t|
-    t.libs << 'test'
-    t.pattern = 'test/*_test.rb'
-    t.verbose = true
-    t.rcov_opts += ['--exclude', 'test/,gems/']
-  end
-rescue LoadError
-  nil # rcov is available only on Ruby 1.8
-end
-
 # Git tagging
 
-desc "Commit all changes as a new version commit. Tag the commit with v<version> tag"
+desc 'Commit all changes as a new version commit. Tag the commit with v<version> tag'
 task :tag do
   puts "Committing and tagging version #{RGL_VERSION}"
   `git commit -am 'Version #{RGL_VERSION}'`
@@ -58,13 +44,13 @@ Bundler::GemHelper.install_tasks
 # TAGS ---------------------------------------------------------------
 
 file 'tags' => SOURCES do
-  print "Running ctags..."
-  sh %{ctags #{SOURCES.join(' ')}}             # vi tags
-  puts "done."
+  print 'Running ctags...'
+  sh %(ctags #{SOURCES.join(' ')}) # vi tags
+  puts 'done.'
 end
 
 file 'TAGS' => SOURCES do
-  sh %{etags #{SOURCES.join(' ')}}          # emacs TAGS
+  sh %(etags #{SOURCES.join(' ')}) # emacs TAGS
 end
 
 # Misc tasks =========================================================
@@ -87,36 +73,35 @@ 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"
+desc 'Count lines in the main files'
 task :lines do
   total_lines = 0
   total_code = 0
-  show_line("File Name", "LINES", "LOC")
+  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
+    total_code += codelines
   end
-  show_line("TOTAL", total_lines, total_code)
+  show_line('TOTAL', total_lines, total_code)
 end
 
 # simple rake task to output a changelog between two commits, tags ...
 # output is formatted simply, commits are grouped under each author name
 #
-desc "generate changelog with nice clean output"
-task :changelog, :since_c, :until_c do |t,args|
+desc 'generate changelog with nice clean output'
+task :changelog, :since_c, :until_c do |t, args|
   since_c = args[:since_c] || `git tag | tail -1`.chomp
   until_c = args[:until_c]
-  cmd=`git log --pretty='format:%ci::%an <%ae>::%s::%H' #{since_c}..#{until_c}`
+  cmd = `git log --pretty='format:%ci::%an <%ae>::%s::%H' #{since_c}..#{until_c}`
 
   entries = Hash.new
   changelog_content = String.new
 
   cmd.split("\n").each do |entry|
-    date, author, subject, hash = entry.chomp.split("::")
+    _, author, subject, hash = entry.chomp.split('::')
     entries[author] = Array.new unless entries[author]
-    day = date.split(" ").first
     entries[author] << "#{subject} (#{hash[0..5]})" unless subject =~ /Merge/
   end