Boost read_graphviz

# `read_graphviz`

    namespace boost {

      template <typename MutableGraph>
      bool read_graphviz(std::istream& in, MutableGraph& graph,
                         dynamic_properties& dp,
                         const std::string& node_id = "node_id");

      template <typename MutableGraph>
      bool read_graphviz(std::string& str, MutableGraph& graph,
                         dynamic_properties& dp,
                         const std::string& node_id = "node_id");

      template <typename InputIterator, typename MutableGraph>
      bool read_graphviz(InputIterator begin, InputIterator end,
                         MutableGraph& graph, dynamic_properties& dp,
                         const std::string& node_id = "node_id");

    }

The `read_graphviz` function interprets a graph described using the GraphViz DOT language and builds a BGL graph that captures that description. Using these functions, you can initialize a graph using data stored as text.

The DOT language can specify both directed and undirected graphs, and `read_graphviz` differentiates between the two. One must pass `read_graphviz` an undirected graph when reading an undirected graph; the same is true for directed graphs. Furthermore, `read_graphviz` will throw an exception if it encounters parallel edges and cannot add them to the graph.

To handle properties expressed in the DOT language, `read_graphviz` takes a dynamic_properties object and operates on its collection of property maps. The reader passes all the properties encountered to this object, using the GraphViz string keys as the property keys. Furthermore, `read_graphviz` stores node identifier names under the vertex property map named `node_id`.

Requirements:
  - The type of the graph must model the Mutable Graph concept.
  - The type of the iterator must model the Input Iterator concept.
  - The property map value types must be default-constructible.

Contents

- Where Defined
- Exceptions
- Example
- Building the GraphViz Readers
- Notes
- See Also
- Future Work

# Where Defined

`<boost/graph/graphviz.hpp>`

# Exceptions

    struct graph_exception : public std::exception {
      virtual ~graph_exception() throw();
      virtual const char* what() const throw() = 0;
    };

    struct bad_parallel_edge : public graph_exception {
      std::string from;
      std::string to;

      bad_parallel_edge(const std::string&, const std::string&);
      virtual ~bad_parallel_edge() throw();
      const char* what() const throw();
    };

    struct directed_graph_error : public graph_exception {
      virtual ~directed_graph_error() throw();
      virtual const char* what() const throw();
    };

    struct undirected_graph_error : public graph_exception {
      virtual ~undirected_graph_error() throw();
      virtual const char* what() const throw();
    };

    struct bad_graphviz_syntax: public graph_exception {
      std::string errmsg;

      bad_graphviz_syntax(const std::string&);
      virtual ~bad_graphviz_syntax() throw();
      virtual const char* what() const throw();
    };

Under certain circumstances, `read_graphviz` will throw one of the above exceptions. The three concrete exceptions can all be caught using the general `graph_exception` moniker when greater precision is not needed. In addition, all of the above exceptions derive from the standard `std::exception` for even more generalized error handling.

The `bad_parallel_edge` exception is thrown when an attempt to add a parallel edge to the supplied MutableGraph fails. The DOT language supports parallel edges, but some BGL-compatible graph types do not. One example of such a graph is `boost::adjacency_list<setS,vecS>`, which allows at most one edge can between any two vertices.

The `directed_graph_error` exception occurs when an undirected graph type is passed to `read_graph` but the textual representation of the graph is directed, as indicated by the `digraph` keyword in the DOT language.

The `undirected_graph_error` exception occurs when a directed graph type is passed to `read_graph` but the textual representation of the graph is undirected, as indicated by the `graph` keyword in the DOT language.

The `bad_graphviz_syntax` exception occurs when the graph input is not a valid GraphViz graph.

# Example

The following example illustrates a relatively simple use of the GraphViz reader to populate an `adjacency_list` graph

    // Vertex properties
    typedef property < vertex_name_t, std::string,
              property < vertex_color_t, float > > vertex_p;
    // Edge properties
    typedef property < edge_weight_t, double > edge_p;
    // Graph properties
    typedef property < graph_name_t, std::string > graph_p;
    // adjacency_list-based type
    typedef adjacency_list < vecS, vecS, directedS,
      vertex_p, edge_p, graph_p > graph_t;

    // Construct an empty graph and prepare the dynamic_property_maps.
    graph_t graph(0);
    dynamic_properties dp;

    property_map<graph_t, vertex_name_t>::type name =
      get(vertex_name, graph);
    dp.property("node_id",name);

    property_map<graph_t, vertex_color_t>::type mass =
      get(vertex_color, graph);
    dp.property("mass",mass);

    property_map<graph_t, edge_weight_t>::type weight =
      get(edge_weight, graph);
    dp.property("weight",weight);

    // Use ref_property_map to turn a graph property into a property map
    boost::ref_property_map<graph_t*,std::string>
      gname(get_property(graph,graph_name));
    dp.property("name",gname);

    // Sample graph as an std::istream;
    std::istringstream
      gvgraph("digraph { graph [name=\"graphname\"]  a  c e [mass = 6.66] }");

    bool status = read_graphviz(gvgraph,graph,dp,"node_id");

# Building the GraphViz Readers

To use the GraphViz readers, you will need to build and link against the "boost_graph" library. The library can be built by following the Boost Jam Build Instructions for the subdirectory `libs/graph/build`.

# Notes

> - The `read_graphviz` function does not use any code from the GraphViz distribution to interpret the DOT Language. Rather, the implementation was based on documentation found on the GraphViz web site, as well as experiments run using the dot application. The resulting interpretation may be subtly different from dot for some corner cases that are not well specified.
> - On successful reading of a graph, every vertex and edge will have an associated value for every respective edge and vertex property encountered while interpreting the graph. These values will be set using the `dynamic_properties` object. Those edges and vertices that are not explicitly given a value for a property (and that property has no default) will be given the default constructed value of the value type. Be sure that property map value types are default constructible.
> - `read_graphviz` treats subgraphs as syntactic sugar. It does not reflect subgraphs as actual entities in the BGL. Rather, they are used to shorten some edge definitions as well as to give a subset of all nodes or edges certain properties. For example, the DOT graphs `digraph { a -> subgraph {b -> c} -> e }` and `digraph { a -> b -> e ; a -> c -> e ; b -> c}` are equivalent.
> - Subgraph IDs refer to subgraphs defined earlier in the graph description. Undefined subgraphs behave as empty subgraphs (`{}`). This is the same behavior as GraphViz.

# See Also

write_graphviz

# Future Work

> - Passing port information to BGL.
> - Expanding escape codes in the same way GraphViz does.
> - Support for optional recognition of subgraphs as distinct entities.