Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/graph/doc/read_graphviz.html @ 45

Last change on this file since 45 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 12.0 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3<!--
4  -- Copyright (c) 2005 Trustees of Indiana University
5  --
6  -- Distributed under the Boost Software License, Version 1.0.
7  -- (See accompanying file LICENSE_1_0.txt or copy at
8  -- http://www.boost.org/LICENSE_1_0.txt)
9  -->
10<head>
11<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
12<meta name="generator" content="Docutils 0.3.3: http://docutils.sourceforge.net/" />
13<title>Boost read_graphviz</title>
14<link rel="stylesheet" href="default.css" type="text/css" />
15</head>
16<body>
17<h1 class="title"><a class="reference" href="../../../index.htm"><img align="middle" alt="Boost" src="../../../boost.png" /></a> <tt class="literal"><span class="pre">read_graphviz</span></tt></h1>
18<div class="document" id="logo-read-graphviz">
19<pre class="literal-block">
20template &lt;typename MutableGraph&gt;
21bool read_graphviz(std::istream&amp; in, MutableGraph&amp; graph,
22                   dynamic_properties&amp; dp,
23                   const std::string&amp; node_id = &quot;node_id&quot;);
24
25// Only available if BOOST_GRAPH_READ_GRAPHVIZ_ITERATORS is defined
26template &lt;typename MultiPassIterator, typename MutableGraph&gt;
27bool read_graphviz(MultiPassIterator begin, MultiPassIterator end,
28                   MutableGraph&amp; graph, dynamic_properties&amp; dp,
29                   const std::string&amp; node_id = &quot;node_id&quot;);
30
31// Deprecated GraphViz readers
32void read_graphviz(const std::string&amp; file, GraphvizDigraph&amp; g);
33void read_graphviz(FILE* file, GraphvizDigraph&amp; g);
34void read_graphviz(const std::string&amp; file, GraphvizGraph&amp; g);
35void read_graphviz(FILE* file, GraphvizGraph&amp; g);
36</pre>
37<p>The <tt class="literal"><span class="pre">read_graphviz</span></tt> function interprets a graph described using the
38<a class="reference" href="http://graphviz.org/">GraphViz</a> DOT language and builds a BGL graph that captures that
39description.  Using this function, you can initialize a graph using
40data stored as text. To use the iterator version of <tt class="literal"><span class="pre">read_graphviz</span></tt>,
41you will need to define the macro BOOST_GRAPH_READ_GRAPHVIZ_ITERATORS
42before including the header <tt class="literal"><span class="pre">&lt;boost/graph/graphviz.hpp&gt;</span></tt>. Doing so
43may greatly increase the amount of time required to compile the
44GraphViz reader.</p>
45<p>The DOT language can specify both directed and undirected graphs, and
46<tt class="literal"><span class="pre">read_graphviz</span></tt> differentiates between the two. One must pass
47<tt class="literal"><span class="pre">read_graphviz</span></tt> an undirected graph when reading an undirected graph;
48the same is true for directed graphs. Furthermore, <tt class="literal"><span class="pre">read_graphviz</span></tt>
49will throw an exception if it encounters parallel edges and cannot add
50them to the graph.</p>
51<p>To handle properties expressed in the DOT language, <tt class="literal"><span class="pre">read_graphviz</span></tt>
52takes a <a class="reference" href="../../property_map/doc/dynamic_property_map.html">dynamic_properties</a> object and operates on its collection of
53property maps.  The reader passes all the properties encountered to
54this object, using the GraphViz string keys as the property keys.
55Furthermore, <tt class="literal"><span class="pre">read_graphviz</span></tt> stores node identifier names under the
56vertex property map named node_id.</p>
57<dl>
58<dt>Requirements:</dt>
59<dd><ul class="first last simple">
60<li>The type of the graph must model the <a class="reference" href="MutableGraph.html">Mutable Graph</a> concept.</li>
61<li>The type of the iterator must model the <a class="reference" href="../../iterator/index.html">Multi-Pass Iterator</a>
62concept.</li>
63<li>The property map value types must be default-constructible.</li>
64</ul>
65</dd>
66</dl>
67<div class="contents topic" id="contents">
68<p class="topic-title first"><a name="contents">Contents</a></p>
69<ul class="simple">
70<li><a class="reference" href="#where-defined" id="id2" name="id2">Where Defined</a></li>
71<li><a class="reference" href="#exceptions" id="id3" name="id3">Exceptions</a></li>
72<li><a class="reference" href="#building-the-graphviz-readers" id="id4" name="id4">Building the GraphViz Readers</a></li>
73<li><a class="reference" href="#deprecated-readers" id="id5" name="id5">Deprecated Readers</a></li>
74<li><a class="reference" href="#notes" id="id6" name="id6">Notes</a></li>
75<li><a class="reference" href="#see-also" id="id7" name="id7">See Also</a></li>
76<li><a class="reference" href="#future-work" id="id8" name="id8">Future Work</a></li>
77</ul>
78</div>
79<div class="section" id="where-defined">
80<h1><a class="toc-backref" href="#id2" name="where-defined">Where Defined</a></h1>
81<p><tt class="literal"><span class="pre">&lt;boost/graph/graphviz.hpp&gt;</span></tt></p>
82</div>
83<div class="section" id="exceptions">
84<h1><a class="toc-backref" href="#id3" name="exceptions">Exceptions</a></h1>
85<pre class="literal-block">
86struct graph_exception : public std::exception {
87  virtual ~graph_exception() throw();
88  virtual const char* what() const throw() = 0;
89};
90
91struct bad_parallel_edge : public graph_exception {
92  std::string from;
93  std::string to;
94
95  bad_parallel_edge(const std::string&amp;, const std::string&amp;);
96  virtual ~bad_parallel_edge() throw();
97  const char* what() const throw();
98};
99
100struct directed_graph_error : public graph_exception {
101  virtual ~directed_graph_error() throw();
102  virtual const char* what() const throw();
103};
104
105struct undirected_graph_error : public graph_exception {
106  virtual ~undirected_graph_error() throw();
107  virtual const char* what() const throw();
108};
109</pre>
110<p>Under certain circumstances, <tt class="literal"><span class="pre">read_graphviz</span></tt> will throw one of the
111above exceptions.  The three concrete exceptions can all be caught
112using the general <tt class="literal"><span class="pre">graph_exception</span></tt> moniker when greater precision
113is not needed.  In addition, all of the above exceptions derive from
114the standard <tt class="literal"><span class="pre">std::exception</span></tt> for even more generalized error
115handling.</p>
116<p>The <tt class="literal"><span class="pre">bad_parallel_edge</span></tt> exception is thrown when an attempt to add a
117parallel edge to the supplied MutableGraph fails.  The DOT language
118supports parallel edges, but some BGL-compatible graph types do not.
119One example of such a graph is <tt class="literal"><span class="pre">boost::adjacency_list&lt;setS,vecS&gt;</span></tt>,
120which allows at most one edge between any two vertices.</p>
121<p>The <tt class="literal"><span class="pre">directed_graph_error</span></tt> exception occurs when an undirected graph
122type is passed to <tt class="literal"><span class="pre">read_graph</span></tt> but the textual representation of the
123graph is directed, as indicated by the <tt class="literal"><span class="pre">digraph</span></tt> keyword in the DOT
124language.</p>
125<p>The <tt class="literal"><span class="pre">undirected_graph_error</span></tt> exception occurs when a directed graph
126type is passed to <tt class="literal"><span class="pre">read_graph</span></tt> but the textual representation of the
127graph is undirected, as indicated by the <tt class="literal"><span class="pre">graph</span></tt> keyword in the DOT
128language.</p>
129</div>
130<div class="section" id="building-the-graphviz-readers">
131<h1><a class="toc-backref" href="#id4" name="building-the-graphviz-readers">Building the GraphViz Readers</a></h1>
132<p>To use the GraphViz readers, you will need to build and link against
133the &quot;boost_graph&quot; library. The library can be built by following the
134<a class="reference" href="../../../more/getting_started.html#Build_Install">Boost Jam Build Instructions</a> for the subdirectory <tt class="literal"><span class="pre">libs/graph/build</span></tt>.</p>
135</div>
136<div class="section" id="deprecated-readers">
137<h1><a class="toc-backref" href="#id5" name="deprecated-readers">Deprecated Readers</a></h1>
138<p>The deprecated readers do not provide exceptions on error (they
139abort), they require the use of one of the predefined graph types
140(<tt class="literal"><span class="pre">GraphvizDigraph</span></tt> or <tt class="literal"><span class="pre">GraphvizGraph</span></tt>), and they do not support
141arbitrary properties. They will be removed in a future Boost version.</p>
142</div>
143<div class="section" id="notes">
144<h1><a class="toc-backref" href="#id6" name="notes">Notes</a></h1>
145<blockquote>
146<ul class="simple">
147<li>The <tt class="literal"><span class="pre">read_graphviz</span></tt> function does not use any code from the
148GraphViz distribution to interpret the DOT Language.  Rather, the
149implementation was based on documentation found on the GraphViz web
150site, as well as experiments run using the dot application.  The
151resulting interpretation may be subtly different from dot for some
152corner cases that are not well specified.</li>
153<li><tt class="literal"><span class="pre">read_graphviz</span></tt> treats subgraphs as syntactic sugar.  It does not
154reflect subgraphs as actual entities in the BGL.  Rather, they are
155used to shorten some edge definitions as well as to give a subset
156of all nodes or edges certain properties. For example, the
157DOT graphs <tt class="literal"><span class="pre">digraph</span> <span class="pre">{</span> <span class="pre">a</span> <span class="pre">-&gt;</span> <span class="pre">subgraph</span> <span class="pre">{b</span> <span class="pre">-&gt;</span> <span class="pre">c}</span> <span class="pre">-&gt;</span> <span class="pre">e</span> <span class="pre">}</span></tt> and
158<tt class="literal"><span class="pre">digraph</span> <span class="pre">{</span> <span class="pre">a</span> <span class="pre">-&gt;</span> <span class="pre">b</span> <span class="pre">-&gt;</span> <span class="pre">e</span> <span class="pre">;</span> <span class="pre">a</span> <span class="pre">-&gt;</span> <span class="pre">c</span> <span class="pre">-&gt;</span> <span class="pre">e</span> <span class="pre">;</span> <span class="pre">b</span> <span class="pre">-&gt;</span> <span class="pre">c}</span></tt> are equivalent.</li>
159<li>Subgraph IDs refer to subgraphs defined earlier in the graph
160description.  Undefined subgraphs behave as empty subgraphs
161(<tt class="literal"><span class="pre">{}</span></tt>).</li>
162<li>On successful reading of a graph, every vertex and edge will have
163an associated value for every respective edge and vertex property
164encountered while interpreting the graph.  These values will be set
165using the <tt class="literal"><span class="pre">dynamic_properties</span></tt> object.  Some properties may be
166<tt class="literal"><span class="pre">put</span></tt> multiple times during the course of reading in order to
167ensure the same semantics as the GraphViz tools.  Those edges and
168vertices that are not explicitly given a value for a property (and that
169property has no default) will be
170given the default constructed value of the value type.  <strong>Be sure
171that property map value types are default constructible.</strong></li>
172</ul>
173</blockquote>
174</div>
175<div class="section" id="see-also">
176<h1><a class="toc-backref" href="#id7" name="see-also">See Also</a></h1>
177<p><a class="reference" href="write-graphviz.html">write_graphviz</a></p>
178</div>
179<div class="section" id="future-work">
180<h1><a class="toc-backref" href="#id8" name="future-work">Future Work</a></h1>
181<blockquote>
182<ul class="simple">
183<li>Currently the parser relies upon lowercase language keywords
184(i.e. &quot;graph&quot;, &quot;edge&quot;, etc.).  The DOT Language specifies that they
185are case-insensitive.  This change should be easy given the proper
186understanding of Spirit and some free time (hint hint!)</li>
187<li>The parser currently does not handle continuation lines as defined
188in the DOT Language.  Some more sophisticated parsing of identifiers
189(so-called &quot;ID&quot; in the source) is required to support this.</li>
190</ul>
191</blockquote>
192</div>
193</div>
194<hr class="footer" />
195<div class="footer">
196Generated on: 2005-03-23 18:37 UTC.
197</div>
198</body>
199</html>
Note: See TracBrowser for help on using the repository browser.