Boost Graph Library: write graphviz

# `write_graphviz`

    (1)
    template < typename VertexListGraph >
    void
    write_graphviz(std::ostream& out, const VertexListGraph& g);

    (2)
    template < typename VertexListGraph, typename VertexPropertyWriter >
    void
    write_graphviz(std::ostream& out, const VertexListGraph& g,
                   VertexPropertyWriter vpw);

    (3)
    template < typename VertexListGraph, typename VertexPropertyWriter,
               typename EdgePropertyWriter >
    void
    write_graphviz(std::ostream& out, const VertexListGraph& g,
                   VertexPropertyWriter vpw, EdgePropertyWriter epw);

    (4)
    template < typename VertexListGraph, typename VertexPropertyWriter,
               typename EdgePropertyWriter, typename GraphPropertyWriter >
    void
    write_graphviz(std::ostream& out, const VertexListGraph& g,
                   VertexPropertyWriter vpw, EdgePropertyWriter epw,
                   GraphPropertyWriter gpw);

This is to write a BGL graph object into a output stream in graphviz dot format so that users can make use of AT&T graphviz to draw a picture with nice layout.

The first version with two parameters will write graph into an `std::ostream` where vertex is represented by numerical vertex IDs. If users have either interior or exterior properties for each vertex in the graph, the second version above provides a way to print those properties into the gaphviz format file. For example, if each vertex in the graph has its label through property map object `name`, users can use the second version:

      write_graph(out, g, make_label_writer(name));

The utility function `make_label_writer` returns a predefined PropertyWriter for vertex label. Similarly, the third version and fourth version require edge PropertyWriter, edge PropertyWriter and graph PropertyWriter, respectively.

### Where Defined

`boost/graph/graphviz.hpp`

### `PropertyWriter`

PropertyWriter is used in the `write_graphviz` function to print properties of vertex, edge or graph. There are two types of PropertyWriter. One is for a vertex or edge. The other is for a graph. Thus, users could easily extend the `write_graphviz` function by creating their own PropertyWriter only.

A PropertyWriter for vertices or edges is a functor which can be called with two parameters: `std::ostream` and either vertex or edge descriptor. It should output a pair of brackets with a series of assigments "name=value" inside. Each assignment should be separated either with space, with comma, or with semicolon. The following functor, provided by BGL, is the example of PropertyWriter for vertices or edges. It is used to print the label of each vertex or edge.

      template < class Name >
      class label_writer {
      public:
        label_writer(Name _name) : name(_name) {}
        template
        void operator()(std::ostream& out, const VertexOrEdge& v) const {
          out << "[label=\"" << name[v] << "\"]";
        }
      private:
        Name name;
      };

A function to conveniently create this writer is provided:

    template < class Name >
    label_writer<Name>
    make_label_writer(Name n);

A PropertyWriter for graph is a functor which is called with one parameter, of type `std::ostream` and should print a series of graph properties. The following code excerpt is an example of a PropertyWriter for a graph.

      struct sample_graph_writer {
        void operator()(std::ostream& out) const {
          out << "graph [bgcolor=lightgrey]" << std::endl;
          out << "node [shape=circle color=white]" << std::endl;
          out << "edge [style=dashed]" << std::endl;
        }
      };
    }

There exists a class `default_writer`, which can be used as both vertex/edge and graph property write, and does nothing. It comes handy when only edge properties must be written, but function interface requries to pass vertex property writer as well.

### Parameters

For version 1:

OUT: `std::ostream& out`

> A standard `std::ostream` object.

IN: `VertexListGraph& g`

> A directed or undirected graph. The graph's type must be a model of VertexListGraph. Also the graph must have an internal `vertex_index` property map.

For version 2:

OUT: `std::ostream& out`

> A standard `std::ostream` object.

IN: `VertexListGraph& g`

> A directed or undirected graph. The graph's type must be a model of VertexListGraph. Also the graph must have an internal `vertex_index` property map.

IN: `VertexPropertyWriter vpw`

> A functor that models PropertyWriter concept to print properties of a vertex.

For version 3:

OUT: `std::ostream& out`

> A standard `std::ostream` object.

IN: `VertexListGraph& g`

> A directed or undirected graph. The graph's type must be a model of VertexListGraph. Also the graph must have an internal `vertex_index` property map.

IN: `VertexPropertyWriter vpw`

> A functor that models PropertyWriter concept to print properties of a vertex.

IN: `EdgePropertyWriter epw`

> A functor that models PropertyWriter concept to print properties of an edge.

For version 4:

OUT: `std::ostream& out`

> A standard `std::ostream` object.

IN: `VertexListGraph& g`

> A directed or undirected graph. The graph's type must be a model of VertexListGraph. Also the graph must have an internal `vertex_index` property map.

IN: `VertexPropertyWriter vpw`

> A functor that models PropertyWriter concept to print properties of a vertex.

IN: `EdgePropertyWriter epw`

> A functor that models PropertyWriter concept to print properties of an edge.

IN: `GeaphPropertyWriter epw`

> A functor that models PropertyWriter concept to print properties of a graph.

### Example

This example demonstrates using BGL-graphviz interface to write a BGL graph into a graphviz format file.

    enum files_e { dax_h, yow_h, boz_h, zow_h, foo_cpp,
                   foo_o, bar_cpp, bar_o, libfoobar_a,
                   zig_cpp, zig_o, zag_cpp, zag_o,
                     libzigzag_a, killerapp, N };
    const char* name[] = { "dax.h", "yow.h", "boz.h", "zow.h", "foo.cpp",
                           "foo.o", "bar.cpp", "bar.o", "libfoobar.a",
                           "zig.cpp", "zig.o", "zag.cpp", "zag.o",
                           "libzigzag.a", "killerapp" };

    int main(int,char*[])
    {

      typedef pair<int,int> Edge;
      Edge used_by[] = {
        Edge(dax_h, foo_cpp), Edge(dax_h, bar_cpp), Edge(dax_h, yow_h),
        Edge(yow_h, bar_cpp), Edge(yow_h, zag_cpp),
        Edge(boz_h, bar_cpp), Edge(boz_h, zig_cpp), Edge(boz_h, zag_cpp),
        Edge(zow_h, foo_cpp),
        Edge(foo_cpp, foo_o),
        Edge(foo_o, libfoobar_a),
        Edge(bar_cpp, bar_o),
        Edge(bar_o, libfoobar_a),
        Edge(libfoobar_a, libzigzag_a),
        Edge(zig_cpp, zig_o),
        Edge(zig_o, libzigzag_a),
        Edge(zag_cpp, zag_o),
        Edge(zag_o, libzigzag_a),
        Edge(libzigzag_a, killerapp)
      };
      const int nedges = sizeof(used_by)/sizeof(Edge);
      int weights[nedges];
      fill(weights, weights + nedges, 1);

      typedef adjacency_list< vecS, vecS, directedS,
          property< vertex_color_t, default_color_type >,
          property< edge_weight_t, int >
        > Graph;
      Graph g(N, used_by, used_by + nedges, weights);

      write_graphviz(std::cout, g, make_label_writer(name));
    }

The output will be:

    digraph G {
    0 -> 4;
    0 -> 6;
    0 -> 1;
    0 [label="dax.h"];
    1 -> 6;
    1 -> 11;
    1 [label="yow.h"];
    2 -> 6;
    2 -> 9;
    2 -> 11;
    2 [label="boz.h"];
    3 -> 4;
    3 [label="zow.h"];
    4 -> 5;
    4 [label="foo.cpp"];
    5 -> 8;
    5 [label="foo.o"];
    6 -> 7;
    6 [label="bar.cpp"];
    7 -> 8;
    7 [label="bar.o"];
    8 -> 13;
    8 [label="libfoobar.a"];
    9 -> 10;
    9 [label="zig.cpp"];
    10 -> 13;
    10 [label="zig.o"];
    11 -> 12;
    11 [label="zag.cpp"];
    12 -> 13;
    12 [label="zag.o"];
    13 -> 14;
    13 [label="libzigzag.a"];
    14;
    14 [label="killerapp"];
    edge[style="dotted"];
    6 -> 0;
    }

### See Also

`read_graphviz`

### Notes

Note that you can use Graphviz dot file write facilities without the library `libbglviz.a`.

Copyright © 2000-2001 | Lie-Quan Lee, Indiana University (llee@cs.indiana.edu) Jeremy Siek, Indiana University (jsiek@osl.iu.edu)