IN: graphs
USING: help ;

HELP: add-vertex "( vertex edges graph -- )"
{ $values { "vertex" "an object" } { "edges" "a quotation with stack effect " { $snippet "( vertex -- seq )" } } { "graph" "a hashtable mapping vertices to sequences of edges" } }
{ $description "Adds a vertex to a directed graph, using the " { $snippet "edges" } " quotation to generate a sequence of edges leaving the vertex." }
{ $side-effects "graph" } ;

HELP: build-graph "( seq edges graph -- )"
{ $values { "seq" "a sequence" } { "edges" "a quotation with stack effect " { $snippet "( vertex -- seq )" } } { "graph" "a hashtable mapping vertices to sequences of edges" } }
{ $description "Removes all vertices from the graph, then reconstructs it using the given sequence of vertices and quotation to generate a sequence of edges leaving each vertex." }
{ $side-effects "graph" } ;

HELP: remove-vertex "( vertex edges graph -- )"
{ $values { "vertex" "an object" } { "edges" "a quotation with stack effect " { $snippet "( vertex -- seq )" } } { "graph" "a hashtable mapping vertices to sequences of edges" } }
{ $description "Removes a vertex from a graph, using the quotation to generate a sequence of edges leaving the vertex." } 
{ $notes "The " { $snippet "edges" } " quotation must produce the same return value as it did when " { $link add-vertex } " was called, otherwise some vertices of the graph may continue to refer to the removed vertex." }
{ $side-effects "graph" } ;

HELP: in-edges "( vertex graph -- seq )"
{ $values { "vertex" "an object" } { "graph" "a hashtable mapping vertices to sequences of edges" } { "seq" "a sequence of vertices" } }
{ $description "Outputs a sequence of vertices incident to an edge entering the given vertex." } ;

HELP: closure "( vertex graph -- seq )"
{ $values { "vertex" "an object" } { "graph" "a hashtable mapping vertices to sequences of edges" } { "seq" "a sequence of vertices" } }
{ $description "Outputs a sequence of vertices which can reach " { $snippet "vertex" } " by some path terminating at " { $snippet "vertex" } "." }
{ $notes "This is the transitive closure of the " { $link in-edges } " operation." } ;