:- module(graphviz).
:- export write_graph / 4.
:- export write_graph_ / 5.
:- export write_graph / 3.
:- export write_graph_ / 4.
:- export write_graph_ / 3.
:- export write_graph / 2.
:- export view_graph / 3.
:- export view_graph_ / 4.
:- export view_graph / 2.
:- export view_graph_ / 3.
:- export view_graph_ / 2.
:- export view_graph / 1.
:- tool(write_graph / 4,write_graph_ / 5).
:- tool(write_graph / 3,write_graph_ / 4).
:- tool(write_graph / 2,write_graph_ / 3).
:- tool(view_graph / 3,view_graph_ / 4).
:- tool(view_graph / 2,view_graph_ / 3).
:- tool(view_graph / 1,view_graph_ / 2).
:- comment(write_graph_ / 5, hidden).
:- comment(write_graph_ / 4, hidden).
:- comment(write_graph_ / 3, hidden).
:- comment(view_graph_ / 4, hidden).
:- comment(view_graph_ / 3, hidden).
:- comment(view_graph_ / 2, hidden).
:- comment(summary, "Interface to Graphviz Graph Drawing Programs from AT&T").
:- comment(author, "Andrew J Sadler and Joachim Schimpf, IC-Parc").
:- comment(date, "$Id: graphviz.ecl,v 1.1.1.1 2006/09/23 01:56:28 snovello Exp $").
:- comment(desc, html("\n    This library provides an interface to the Graphviz Graph Drawing Programs\n    from AT&T. Graphviz is subject to the following notice:\n<P>\n   This  product  contains  certain  software  code or other information\n   (\"AT&T  Software\")  proprietary  to  AT&T  Corp.  (\"AT&T\").  The  AT&T\n   Software  is  provided to you \"AS IS\". YOU ASSUME TOTAL RESPONSIBILITY\n   AND  RISK  FOR  USE  OF  THE  AT&T  SOFTWARE.  AT&T DOES NOT MAKE, AND\n   EXPRESSLY  DISCLAIMS,  ANY  EXPRESS  OR IMPLIED WARRANTIES OF ANY KIND\n   WHATSOEVER,  INCLUDING,  WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF\n   MERCHANTABILITY  OR  FITNESS  FOR  A PARTICULAR PURPOSE, WARRANTIES OF\n   TITLE  OR  NON-INFRINGEMENT  OF  ANY INTELLECTUAL PROPERTY RIGHTS, ANY\n   WARRANTIES  ARISING  BY USAGE OF TRADE, COURSE OF DEALING OR COURSE OF\n   PERFORMANCE, OR ANY WARRANTY THAT THE AT&T SOFTWARE IS \"ERROR FREE\" OR\n   WILL MEET YOUR REQUIREMENTS.\n    ")).
:- comment(view_graph / 1, [summary : "Display a given graph in a window (using default options)", amode : view_graph(+), args : ["Graph" : "A graph structure"], see_also : [view_graph / 2, library(graph_algorithms)], eg : "\n    ?- lib(graph_algorithms), lib(graphviz).\n    Yes (1.17s cpu)\n\n    ?- make_random_graph(10,30,true,true,true,G), view_graph(G).\n    G = graph(...)\n    Yes (0.03s cpu)\n    "]).
:- comment(view_graph / 2, [summary : "Display a given graph in a window", amode : view_graph(+, +), args : ["Graph" : "A graph structure", "Options" : "A list of Option:Value pairs"], see_also : [view_graph / 1, library(graph_algorithms)], desc : html("\n    This predicate takes a graph, applies one of the graphviz layout routines\n    to it, and displays the result in a viewer window.\n    <P>\n    Possible options are:\n    <DL>\n    <DT>graph_attrs</DT>\n\t<DD>a list of Name=Value pairs which specify the graph attributes</DD>\n    <DT>default_edge_attrs</DT>\n\t<DD>a list of Name=Value pairs which specify the default edge attributes</DD>\n    <DT>default_node_attrs</DT>\n\t<DD>a list of Name=Value pairs which specify the default node attributes</DD>\n    <DT>node_attrs_generator</DT>\n\t<DD>a partialpredicate specification pred(ExtraArgs,...) that\n\twill generate node attributes for specific nodes. This\n\tpredicate will be invoked for every node in the graph with the\n\targuments pred(ExtraArgs,...,+Graph, +Node, -AttrList). It is\n\texpected to compute an attribute list for a particular\n\tnode. If it fails, the node will be displayed using the\n\tdefault node attributes.</DD>\n\n    <DT>edge_attrs_generator</DT>\n\t<DD>a partialpredicate specification pred(ExtraArgs,...) that\n\twill generate edge attributes for specific edges. This\n\tpredicate will be invoked for every edge in the graph with the\n\targuments pred(ExtraArgs,...,+Graph, +Edge, -AttrList). It is\n\texpected to compute an attribute list for a particular\n\tedge. If it fails, the edge will be displayed using the\n\tdefault edge attributes.</DD>\n    <DT>layout</DT>\n\t<DD>One of the atoms: none, dot, neato, twopi, force_directed, radial,\n\ttree, top_to_bottom, left_to_right.\n\tAlternatively, a list specifying a layout command (see exec/3).\n    </DL>\n    For the exact definition of graph, node and edge attributes, see the\n    specification of the DOT language in the graphviz documentation.\n    "), eg : "\n    ?- lib(graph_algorithms), lib(graphviz).\n    Yes (1.17s cpu)\n\n    ?- make_random_graph(10, 30, true, true, true, G),\n       view_graph(G, [layout:left_to_right]).\n    G = graph(...)\n    Yes (0.03s cpu)\n\n    ?- make_random_graph(10, 30, true, true, true, G),\n       view_graph(G, [layout:left_to_right]).\n    G = graph(...)\n    Yes (0.03s cpu)\n\n\n% Sample node attribute generator\n\nnode_colour(Graph, Node, Attrs) :-\n\t( Node mod 2 =:= 0 -> Attrs = [color=red] ; Attrs = [color=green] ).\n\n% Sample run\n\n    ?- make_random_graph(10, 30, true, true, true, G),\n       view_graph(G, [node_attrs_generator:node_colour]).\n    G = graph(...)\n    Yes (0.03s cpu)\n    "]).
:- comment(view_graph / 3, [summary : "Display a given graph in an existing window", amode : view_graph(+, +, ?), args : ["Graph" : "A graph structure", "Options" : "A list of Option:Value pairs", "HandleFile" : "String or variable"], see_also : [view_graph / 1, view_graph / 2, library(graph_algorithms)], desc : html("\n    This predicate takes a graph, applies one of the graphviz layout\n    routines to it, and displays the result in a viewer window.  If\n    the HandleFile option is a variable it will be bound the name of\n    the file which the viewer is rendering.  By calling this predicate\n    again with the same file name, the viewer will re-load the file\n    WITHOUT creating a new window.<P>\n\n    This predicate can be very usefull for displaying graph structures\n    which change over time.<P>\n\n    NOTE: This predicate will sleep for one second to give the viewer\n    a chance to notice that the file has changed and to re-read it.\n\n    <P>\n    ")]).
:- comment(write_graph / 2, [summary : "Write a picture of a graph as a postscript file", amode : write_graph(+, +), args : ["Graph" : "A graph structure", "File" : "A file name"], see_also : [write_graph / 3, write_graph / 4, view_graph / 2, library(graph_algorithms)], eg : "\n    ?- lib(graph_algorithms), lib(graphviz).\n    Yes (1.17s cpu)\n\n    % will create a file mygraph.ps\n    ?- make_random_graph(10,30,true,true,true,G),\n       write_graph(G, \"mygraph\").\n    G = graph(...)\n    Yes (0.03s cpu)\n    "]).
:- comment(write_graph / 3, [summary : "Write a picture of a graph as a file of a given format", amode : write_graph(+, +, +), args : ["Graph" : "A graph structure", "File" : "A file name", "Format" : "An atom (ps,dot,png,gif,...)"], see_also : [write_graph / 2, write_graph / 4, view_graph / 2, library(graph_algorithms)], eg : "\n    ?- lib(graph_algorithms), lib(graphviz).\n    Yes (1.17s cpu)\n\n    ?- make_random_graph(10,30,true,true,true,G),\n       write_graph(G, \"mygraph\", png).\n    G = graph(...)\n    Yes (0.03s cpu)\n\n    ?- make_random_graph(10,30,true,true,true,G),\n       write_graph(G, \"mygraph\", dot).\n    G = graph(...)\n    Yes (0.03s cpu)\n    "]).
:- comment(write_graph / 4, [summary : "Write a picture of a graph as a file of a given format", amode : write_graph(+, +, +, +), args : ["Graph" : "A graph structure", "File" : "A file name", "Format" : "An atom (ps,dot,png,gif,...)", "Options" : "A list of Option:Value pairs"], see_also : [write_graph / 2, write_graph / 3, view_graph / 2, library(graph_algorithms)], desc : html("\n    This predicate takes a graph, applies one of the graphviz layout routines\n    to it, and writes the result to a file is a given format.\n    <P>\n    Possible options are as specified in view_graph/2.\n    <P>\n    Some possible formats are: ps, dot, png, gif, ...  See the graphviz\n    documentation for details.\n    "), eg : "\n    ?- lib(graph_algorithms), lib(graphviz).\n    Yes (1.17s cpu)\n\n    ?- make_random_graph(10,30,true,true,true,G),\n       write_graph(G, \"mygraph\", png).\n    G = graph(...)\n    Yes (0.03s cpu)\n\n    ?- make_random_graph(10,30,true,true,true,G),\n       write_graph(G, \"mygraph\", dot).\n    G = graph(...)\n    Yes (0.03s cpu)\n    "]).
