Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/graph/doc/read_graphviz.html @ 14

Last change on this file since 14 was 12, checked in by landauf, 17 years ago

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