core/graphs/graphs-docs.factor

   1 IN: graphs
   2 USING: help.markup help.syntax kernel assocs hashtables ;
   3
   4 ARTICLE: "graphs" "Directed graph utilities"
   5 "Words for treating associative mappings as directed graphs can be found in the " { $vocab-link "graphs" } " vocabulary. A directed graph is represented as an assoc mapping each vertex to a set of edges entering that vertex, where the set is itself an assoc, with equal keys and values."
   6 $nl
   7 "To create a new graph, just create an assoc, for example by calling " { $link <hashtable> } ". To add vertices and edges to a graph:"
   8 { $subsection add-vertex }
   9 "To remove vertices from the graph:"
  10 { $subsection remove-vertex }
  11 "Since graphs are represented as assocs, they can be cleared out by calling " { $link clear-assoc } "."
  12 $nl
  13 "You can perform queries on the graph:"
  14 { $subsection closure }
  15 "Directed graphs are used to maintain cross-referencing information for " { $link "definitions" } "." ;
  16
  17 ABOUT: "graphs"
  18
  19 HELP: graph
  20 { $var-description "Temporary variable used by various graph words." } ;
  21
  22 HELP: add-vertex
  23 { $values { "vertex" object } { "edges" "a sequence" } { "graph" "an assoc mapping vertices to sequences of edges" } }
  24 { $description "Adds a vertex to a directed graph, with " { $snippet "edges" } "  as the outward edges from the vertex." }
  25 { $side-effects "graph" } ;
  26
  27 HELP: remove-vertex
  28 { $values { "vertex" object } { "edges" "a sequence" } { "graph" "an assoc mapping vertices to sequences of edges" } }
  29 { $description "Removes a vertex from a graph, using the given edges sequence." }
  30 { $notes "The " { $snippet "edges" } " sequence must equal the value passed to " { $link add-vertex } ", otherwise some vertices of the graph may continue to refer to the removed vertex." }
  31 { $side-effects "graph" } ;
  32
  33 HELP: closure
  34 { $values { "obj" object } { "quot" "a a quotation with stack effect " { $snippet "( obj -- assoc )" } } { "assoc" "a new assoc" } }
  35 { $description "Outputs a set of all vertices reachable from " { $snippet "vertex" } " via edges given by the quotation. The set always includes " { $snippet "vertex" } "." } ;