Merge pull request #46 from Encapsule/chrisrus/develop

Chrisrus/develop taking fixes for issues #41 #42 #43 and #47 + a few small doc updates as v0.6.1 release.

Author: ChrisRus

README.md

@@ -2,15 +2,48 @@
 
 ## About jsgraph
 
-_Graphs are mathematical abstractions that are useful for solving many types of problems in computer science. Consequently, these abstractions must also be represented in computer programs._ - [J. Siek](http://ecee.colorado.edu/~siek/resume.pdf)
+_"... At the other end of the spectrum is, for example, graph theory, where the basic object, a graph, can be immediately comprehended. One will not get anywhere in graph theory by sitting in an armchair and trying to understand graphs better. Neither is it particularly necessary to read much of the literature before tackling a problem: it is of course helpful to be aware of some of the most important techniques, but the interesting problems tend to be open precisely because the established techniques cannot easily be applied."_ - [W.T. Gowers](https://en.wikipedia.org/wiki/Timothy_Gowers)
 
-Encapsule/jsgraph is a framework for working with directed graph data models using an in-memory storage container abstraction, and a small but growing collection of powerfully-extensible graph coloring algorithms implemented using the [visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern). The library is specifically designed for efficient embedding in complex Node.js / HTML 5 applications that require clean separation of concerns, and a high-degree of extensibility and control.
+### Status
 
-jsgraph is based on the API design and architectural separaton of concerns for graph algorithms invented by the authors of the [Boost C++ Graph Library](http://www.boost.org/doc/libs/1_56_0/libs/graph/doc/index.html) (BGL). The port is logically close enough that the BGL documentation should be considered as an advanced resource.
+[![Build Status](https://travis-ci.org/Encapsule/jsgraph.svg?branch=master)](https://travis-ci.org/Encapsule/jsgraph)
 
-I encourage you to take some time and experiment with the library as it's truly powerful once you get over the initial learning curve.
+Ich danke Ihnen sehr [Travis CI](https://travis-ci.org/Encapsule/jsgraph.svg?branch=master)
 
-_"... At the other end of the spectrum is, for example, graph theory, where the basic object, a graph, can be immediately comprehended. One will not get anywhere in graph theory by sitting in an armchair and trying to understand graphs better. Neither is it particularly necessary to read much of the literature before tackling a problem: it is of course helpful to be aware of some of the most important techniques, but the interesting problems tend to be open precisely because the established techniques cannot easily be applied."_ - [W.T. Gowers](https://en.wikipedia.org/wiki/Timothy_Gowers)
+### Summary
+
+`Encapsule/jsgraph` implements a framework for storing and processing in-memory directed graph data sets that is inspired by the research of [Jeremy Siek](http://wphomes.soic.indiana.edu/jsiek/) and his work on the [Boost C++ Graph Library](http://www.boost.org/doc/libs/1_59_0/libs/graph/doc/table_of_contents.html).
+
+The library provides and normalizes the following operations independent of graph topology and semantics:
+
+- Generic, multi-dimensional container abstraction for storing directed graphs in memory.
+  - JSON/native JavaScript data object import/export API's.
+  - Vertex and edge CRUD API's.
+  - Application-defined vertex and edge property API's.
+  - Vertex and edge enumeration API's.
+  - Root/leaf vertex set enumeration API's.
+- Generic transposition algorithm.
+- Developer-extensible breadth-first visit and search algorithm.
+- Developer-extensible depth-first visit and search algorithm.
+
+### Audience
+
+jsgraph is a framework for building next-generation frameworks on Node.js and HTML 5.
+
+- Use instead of in-memory object hierarchies linked by reference:
+  - Serializable to JSON (even when cyclic).
+  - Edges can be labeled with properties. References can't.
+  - Much simpler to debug and test.
+  - Promotes code consistency and readability.
+  - Less refactoring due to data structure udpates.
+- Implement business logic and process as generic graph algorithms:
+  - Considerably reduce lines of code/test.
+  - Make the architecture of the design manifest in code.
+  - Re-use investment on other and new data types without code modification.
+
+### Training and Support
+
+If you're considering using jsgraph in a commerical product, please get in touch with [Encapsule.io](https://encapsule.io) - we can save you time, and help you get the most out of your investment.
 
 ### Programming
 
@@ -26,7 +59,7 @@ _"... At the other end of the spectrum is, for example, graph theory, where the
 In your project, install via npm.
 
         $ npm install jsgraph --save
-        jsgraph@0.5.xx node_modules/jsgraph
+        jsgraph@0.6.xx node_modules/jsgraph
 
 ### Sources
 
@@ -51,7 +84,7 @@ See also: [Encapsule/jsgraph on GitHub](https://github.com/Encapsule/jsgraph)
 
 ## Example
 
-The following short example constructs a `DirectedGraph` container using a v0.5 jsgraph digraph data object, and derives a simple rank assignment algorithm from jsgraph's bundled `breadthFirstTraverse` algorithm. Note that the BFT visitor interface callback functions leverage the `DirectedGraph` API to get/set the data property value of each visited vertex to its rank.
+The following short example constructs a `DirectedGraph` container using a v0.6 jsgraph digraph data object, and derives a simple rank assignment algorithm from jsgraph's bundled `breadthFirstTraverse` algorithm. Note that the BFT visitor interface callback functions leverage the `DirectedGraph` API to get/set the data property value of each visited vertex to its rank.
 ```javascript
 // Encapsule/jsgraph/examples/bft-vertex-ranking.js
 var jsgraph = require('jsgraph');
@@ -98,7 +131,7 @@ console.log("BFT traversal: '" +
 ```
 ... produces the following output with each vertex's property value set to its rank (edge hops away from a root vertex in this example).
 
-```javascript
+```
 DirectedGraph: '{
     "vlist": [
         {
@@ -153,6 +186,13 @@ BFT traversal: '{
 
 ## Release
 
+**v0.6 is a bug fix release that's API-compatible with v0.5**
+
+- DFT algorithm bug fixes impacting order and identity of client visitor callbacks.
+- Better error handling on bad developer-supplied visitor interfaces.
+- Better error handling for BFT/DFT algorithm empty start vector case.
+- You can now set `name` and `description` string properties on a `DirectedGraph`:
+
 **v0.5 is a breaking upgrade for users of v0.4**
 
 - Stylistic changes are required to v0.4 clients to upgrade.
@@ -165,7 +205,7 @@ BFT traversal: '{
 
 ## API
 
-v0.5 jsgraph has the following public export object:
+v0.6 jsgraph has the following public export object:
 
 ```javascript
 var jsgraph = require('jsgraph');
@@ -235,6 +275,8 @@ The `DirectedGraph` container object created by this process models "a graph" ge
 
 #### DirectedGraph container methods
 
+- `get/setGraphName()` - get/set the name of the graph
+- `get/setGraphDescription()` - set/set the description of the graph
 - `verticesCount()` - obtain the count of vertices in the container
 - `getVertices()` - retrieve an array of ID strings for all vertices in the container
 - `edgesCount()` - obtain the count of edges in the container
@@ -303,16 +345,6 @@ Supported visitor interface callbacks for depth-first traversal: `initializeVert
 
 A depth-first traversal concludes when all reacable vertices have been visited, or when the client signals termination by returning Boolean **false** back to the algorithm from one of its visitor interface callback functions.
 
-## More examples
-
-The best public examples of how to use jsgraph v0.5 are embedded in the module's test suite. Take a look at the ./test directory scripts.
-
-## Support
-
-I'm happy to answer questions and help you get going with jsgraph in your project.
-
-Ping me on Twitter ([@AlpineLakes](https://twitter.com/AlpineLakes)) or file [Issues](https://github.com/Encapsule/jsgraph/issues) tagged with the 'question' label.
-
 <hr>
 
 Copyright &copy; 2014-2015 [Christopher D. Russell](https://github.com/ChrisRus)

docs/begin-at-the-beginning.jpg

@@ -1,6 +1,6 @@
 {
   "name": "jsgraph",
-  "version": "0.5.14",
+  "version": "0.6.1",
   "description": "Generic directed graph container, and visitor algorithms based on a port of the Boost C++ Graph Library API.",
   "main": "index.js",
   "scripts": {

package.json

@@ -54,7 +54,7 @@
   }
 */
 
-var helperFunctions = require('./helper-functions');
+var algorithmName = "BFT"; // constant string used in error messages
 var colors = require('./digraph-algorithm-common-colors');
 var visitorCallback = require('./digraph-algorithm-common-visit');
 var normalizeRequest = require('./digraph-algorithm-common-request');
@@ -83,7 +83,7 @@ module.exports = function (request_) {
         // initializeVertex visitor callback.
         if (nrequest.options.traverseContext.searchStatus === 'pending') {
             for (vertexId in nrequest.options.traverseContext.colorMap) {
-                innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'initializeVertex', request: { u: vertexId, g: nrequest.digraph }});
+                innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'initializeVertex', request: { u: vertexId, g: nrequest.digraph }});
                 if (innerResponse.error) {
                     errors.unshift(innerResponse.error);
                     break;
@@ -119,7 +119,7 @@ module.exports = function (request_) {
 
             // startVertex visitor callback.
             if (nrequest.options.signalStart) {
-                innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'startVertex', request: { u: startingVertexId, g: nrequest.digraph }});
+                innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'startVertex', request: { u: startingVertexId, g: nrequest.digraph }});
                 if (innerResponse.error) {
                     errors.unshift(innerResponse.error);
                     break;
@@ -133,7 +133,7 @@ module.exports = function (request_) {
             }
 
             // discoverVertex visitor callback.
-            innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'discoverVertex', request: { u: startingVertexId, g: nrequest.digraph }});
+            innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'discoverVertex', request: { u: startingVertexId, g: nrequest.digraph }});
             if (innerResponse.error) {
                 errors.unshift(innerResponse.error);
                 break;
@@ -165,7 +165,7 @@ module.exports = function (request_) {
             nrequest.options.traverseContext.colorMap[vertexId] = colors.black;
 
             // examineVertex visitor callback.
-            innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'examineVertex', request: { u: vertexId, g: nrequest.digraph }});
+            innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'examineVertex', request: { u: vertexId, g: nrequest.digraph }});
             if (innerResponse.error) {
                 errors.unshift(innerResponse.error);
                 break;
@@ -182,7 +182,7 @@ module.exports = function (request_) {
                 var outEdge = outEdges[index];
 
                 // examineEdge visitor callback.
-                innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'examineEdge', request: { e: outEdge, g: nrequest.digraph }});
+                innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'examineEdge', request: { e: outEdge, g: nrequest.digraph }});
                 if (innerResponse.error) {
                     errors.unshift(innerResponse.error);
                     break;
@@ -197,7 +197,7 @@ module.exports = function (request_) {
 
                 case colors.white:
                     // discoverVertex visitor callback.
-                    innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'discoverVertex', request: { u: outEdge.v, g: nrequest.digraph }});
+                    innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'discoverVertex', request: { u: outEdge.v, g: nrequest.digraph }});
                     if (innerResponse.error) {
                         errors.unshift(innerResponse.error);
                         break;
@@ -208,7 +208,7 @@ module.exports = function (request_) {
                         break;
                     }
                     // treeEdge visitor callback.
-                    innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'treeEdge', request: { e: outEdge, g: nrequest.digraph }});
+                    innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'treeEdge', request: { e: outEdge, g: nrequest.digraph }});
                     if (innerResponse.error) {
                         errors.unshift(innerResponse.error);
                         break;
@@ -220,15 +220,15 @@ module.exports = function (request_) {
 
                 case colors.gray:
                     // nonTreeEdge visitor callback.
-                    innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'nonTreeEdge', request: { e: outEdge, g: nrequest.digraph }});
+                    innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'nonTreeEdge', request: { e: outEdge, g: nrequest.digraph }});
                     if (innerResponse.error) {
                         errors.unshift(innerResponse.error);
                         break;
                     }
                     continueSearch = innerResponse.result;
                     if (continueSearch) {
                         // grayTarget visitor callback.
-                        innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'grayTarget', request: { e: outEdge, g: nrequest.digraph }});
+                        innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'grayTarget', request: { e: outEdge, g: nrequest.digraph }});
                         if (innerResponse.error) {
                             errors.unshift(innerResponse.error);
                             break;
@@ -239,15 +239,15 @@ module.exports = function (request_) {
 
                 case colors.black:
                     // nonTreeEdge visitor callback.
-                    innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'nonTreeEdge', request: { e: outEdge, g: nrequest.digraph }});
+                    innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'nonTreeEdge', request: { e: outEdge, g: nrequest.digraph }});
                     if (innerResponse.error) {
                         errors.unshift(innerResponse.error);
                         break;
                     }
                     continueSearch = innerResponse.result;
                     if (continueSearch) {
                         // blackTarget visitor callback.
-                        innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'blackTarget', request: { e: outEdge, g: nrequest.digraph }});
+                        innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'blackTarget', request: { e: outEdge, g: nrequest.digraph }});
                         if (innerResponse.error) {
                             errors.unshift(innerResponse.error);
                             break;
@@ -273,7 +273,7 @@ module.exports = function (request_) {
             }
 
             // finishVertex visitor callback.
-            innerResponse = visitorCallback({ visitor: nrequest.visitor, method: 'finishVertex', request: { u: vertexId, g: nrequest.digraph }});
+            innerResponse = visitorCallback({ algorithm: algorithmName, visitor: nrequest.visitor, method: 'finishVertex', request: { u: vertexId, g: nrequest.digraph }});
             if (innerResponse.error) {
                 errors.unshift(innerResponse.error);
                 break;

src/digraph-algorithm-bft.js

@@ -11,7 +11,7 @@
 */
 
 var helperFunctions = require('./helper-functions');
-var createBreadthFirstTraverseContext = require('./digraph-algorithm-common-context');
+var TRAVERSE_CONTEXT = require('./digraph-algorithm-common-context');
 
 /*
   request = {
@@ -46,7 +46,7 @@ module.exports = function (request_) {
     var inBreakScope = false;
 
     var createTraverseContext = function() {
-        var response = createBreadthFirstTraverseContext({ digraph: nrequest.digraph });
+        var response = TRAVERSE_CONTEXT({ digraph: nrequest.digraph });
         var result = null;
         if (response.error) {
             errors.unshift(response.error);
@@ -146,7 +146,7 @@ module.exports = function (request_) {
 
         // Ensure that the starting vertex set is not empty (unless allowed).
         if (!nrequest.options.startVector.length && !nrequest.options.allowEmptyStartVector) {
-            errors.unshift("You have specified an empty starting vertex set for this traversal. This is allowed only if you set request.options.allowEmptyStartVector === true.");
+            errors.unshift("Traversal aborted because we don't know which vertex to start on. Specify a graph that has at least one root vertex, explicity specify the start vertex (or vertices) via `request.options.startVector` array, or suppress this error by setting `request.options.allowEmptyStartVector` to Boolean true.");
             break;
         }
 

src/digraph-algorithm-common-request.js

@@ -17,6 +17,7 @@ var helperFunctions = require('./helper-functions');
 /*
   request = {
       visitor: interface object reference
+      algorithm: string name of the algorithm for error messages
       method: string name of the visitor method to call
       request: request object to pass to the visitor method
   },
@@ -37,13 +38,17 @@ module.exports = function (request_) {
         var jstype = helperFunctions.JSType(visitorCallback);
         // If the visitor function is not defined on the visitor object, return true to continue the search.
         if (jstype !== '[object Function]') {
+            if (jstype !== '[object Undefined]') {
+                errors.unshift(request_.algorithm + " visitor interface method '" + request_.method + "' is type '" + jstype + "' instead of '[object Function]' as expected.");
+                break;
+            }
             response.result = true;
             break;
         }
         var continueSearch = visitorCallback(request_.request);
         jstype = helperFunctions.JSType(continueSearch);
         if (jstype !== '[object Boolean]') {
-            errors.unshift("BFS visitor." + request_.method + " returned type '" + jstype + "' instead of expected '[object Boolean]'.");
+            errors.unshift(request_.algorithm + " visitor interface error in callback function '" + request_.method + "'. Function returned type '" + jstype + "' instead of expected '[object Boolean]'.");
             break;
         }
         response.result = continueSearch;