1.1 --- a/doc/graph_io.dox Mon Jul 04 13:10:34 2005 +0000
1.2 +++ b/doc/graph_io.dox Mon Jul 04 15:03:25 2005 +0000
1.3 @@ -9,12 +9,13 @@
1.4
1.5 \section format The general file format
1.6
1.7 -The file contains at most four sections in the following order:
1.8 +The file contains sections in the following order:
1.9
1.10 \li nodeset
1.11 \li edgeset
1.12 \li nodes
1.13 \li edges
1.14 +\li attributes
1.15
1.16 The nodeset section starts with the following line:
1.17
1.18 @@ -78,6 +79,22 @@
1.19 The file may contain empty lines and comment lines. The comment lines
1.20 start with an \c # character.
1.21
1.22 +The attributes section can handle some information about the graph. It
1.23 +contains in each line an key and the mapped value to key. The key should
1.24 +be a string without whitespace, the value can be from various type.
1.25 +
1.26 +\code
1.27 +@attributes
1.28 +title "Four colored plan graph"
1.29 +author "Balazs DEZSO"
1.30 +copyright "Lemon Library"
1.31 +version 12
1.32 +\endcode
1.33 +
1.34 +\code
1.35 +@end
1.36 +\endcode
1.37 +=======
1.38 The file ends with the
1.39
1.40 <tt> \@end </tt>
1.41 @@ -141,6 +158,13 @@
1.42 writer.writeEdge("observed", edge);
1.43 \endcode
1.44
1.45 +With \c writeAttribute() function you can write an attribute to the file.
1.46 +
1.47 +\code
1.48 +writer.writeAttribute("author", "Balazs DEZSO");
1.49 +writer.writeAttribute("version", 12);
1.50 +\endcode
1.51 +
1.52 After you give all write commands you must call the \c run() member
1.53 function, which executes all the writing commands.
1.54
1.55 @@ -199,6 +223,15 @@
1.56 reader.readEdge("observed", edge);
1.57 \endcode
1.58
1.59 +With \c readAttribute() function you can read an attribute from the file.
1.60 +
1.61 +\code
1.62 +std::string author;
1.63 +writer.readAttribute("author", author);
1.64 +int version;
1.65 +writer.writeAttribute("version", version);
1.66 +\endcode
1.67 +
1.68 After you give all read commands you must call the \c run() member
1.69 function, which executes all the commands.
1.70
1.71 @@ -256,6 +289,151 @@
1.72
1.73 The specialization of writing should be very similar to that of reading.
1.74
1.75 +\section undir Undir graphs
1.76 +
1.77 +In the undir graph format there is an \c undiredgeset section instead of
1.78 +the \c edgeset section. The first line of the section describes the
1.79 +undirected egdes' names and all next lines describes one undirected edge
1.80 +with the the incident nodes and the values of the map.
1.81 +
1.82 +The format handles the directed edge maps as a syntactical sugar, if there
1.83 +is two map which names are the same with a \c '+' and a \c '-' prefix
1.84 +then it can be read as an directed map.
1.85 +
1.86 +\code
1.87 +@undiredgeset
1.88 + id capacity +flow -flow
1.89 +32 2 1 4.3 2.0 0.0
1.90 +21 21 5 2.6 0.0 2.6
1.91 +21 12 8 3.4 0.0 0.0
1.92 +\endcode
1.93 +
1.94 +The \c edges section changed to \c undiredges section. This section
1.95 +describes labeled edges and undirected edges. The directed edge label
1.96 +should start with a \c '+' and a \c '-' prefix what decide the direction
1.97 +of the edge.
1.98 +
1.99 +\code
1.100 +@undiredges
1.101 +undiredge 1
1.102 ++edge 5
1.103 +-back 5
1.104 +\endcode
1.105 +
1.106 +There are similar classes to the \c GraphReader ans \c GraphWriter
1.107 +which handle the undirected graphs. These classes are the
1.108 +\c UndirGraphReader and \UndirGraphWriter.
1.109 +
1.110 +The \c readUndirMap() function reads an undirected map and the
1.111 +\c readUndirEdge() reads an undirected edge from the file,
1.112 +
1.113 +\code
1.114 +reader.readUndirEdgeMap("capacity", capacityMap);
1.115 +reader.readEdgeMap("flow", flowMap);
1.116 +...
1.117 +reader.readUndirEdge("undir_edge", undir_edge);
1.118 +reader.readEdge("edge", edge);
1.119 +\endcode
1.120 +
1.121 +\section advanced Advanced features
1.122 +
1.123 +The graph reader and writer classes gives an easy way to read and write
1.124 +graphs. But sometimes we want more advanced features. This way we can
1.125 +use the more general lemon reader and writer interface.
1.126 +
1.127 +The lemon format is an section oriented file format. It contains one or
1.128 +more section, each starts with a line with \c \@ first character.
1.129 +The content of the section this way cannot contain line with \c \@ first
1.130 +character. The file may contains comment lines with \c # first character.
1.131 +
1.132 +The \c LemonReader and \c LemonWriter gives a framework to read and
1.133 +write sections. There are various section reader and section writer
1.134 +classes which can be attached to a \c LemonReader or a \c LemonWriter.
1.135 +
1.136 +There are default section readers and writers for reading and writing
1.137 +item sets, and labeled items in the graph. These reads and writes
1.138 +the format described above. Other type of data can be handled with own
1.139 +section reader and writer classes which are inherited from the
1.140 +\c LemonReader::SectionReader or the \c LemonWriter::SectionWriter classes.
1.141 +
1.142 +The next example defines a special section reader which reads the
1.143 +\c \@description sections into a string:
1.144 +
1.145 +\code
1.146 +class DescriptionReader : LemonReader::SectionReader {
1.147 +protected:
1.148 + virtual bool header(const std::string& line) {
1.149 + std::istringstream ls(line);
1.150 + std::string head;
1.151 + ls >> head;
1.152 + return head == "@description";
1.153 + }
1.154 +
1.155 + virtual void read(std::istream& is) {
1.156 + std::string line;
1.157 + while (getline(is, line)) {
1.158 + desc += line;
1.159 + }
1.160 + }
1.161 +public:
1.162 +
1.163 + typedef LemonReader::SectionReader Parent;
1.164 +
1.165 + DescriptionReader(LemonReader& reader) : Parent(reader) {}
1.166 +
1.167 + const std::string& description() const {
1.168 + return description;
1.169 + }
1.170 +
1.171 +private:
1.172 + std::string desc;
1.173 +};
1.174 +\endcode
1.175 +
1.176 +The other advanced stuff of the generalized file format is that
1.177 +multiple edgesets can be stored to the same nodeset. It can be used
1.178 +by example as a network traffic matrix.
1.179 +
1.180 +In example there is a network with symmetric links and there are assymetric
1.181 +traffic request on the network. This construction can be stored in an
1.182 +undirected graph and in an directed NewEdgeSetAdaptor class. The example
1.183 +shows the input with the LemonReader class:
1.184 +
1.185 +\code
1.186 +UndirListGraph network;
1.187 +UndirListGraph::UndirEdgeSet<double> capacity;
1.188 +NewEdgeSetAdaptor<UndirListGraph> traffic(network);
1.189 +NewEdgeSetAdaptor<UndirListGraph>::EdgeSet<double> request(network);
1.190 +
1.191 +LemonReader reader(std::cin);
1.192 +NodeSetReader nodesetReader(reader, network);
1.193 +UndirEdgeSetReader undirEdgesetReader(reader, network, nodesetReader);
1.194 +undirEdgesetReader.readEdgeMap("capacity", capacity);
1.195 +EdgeSetReader edgesetReader(reader, traffic, nodesetReader);
1.196 +edgesetReader.readEdgeMap("request", request);
1.197 +
1.198 +reader.run();
1.199 +\endcode
1.200 +
1.201 +Because the GraphReader and the UndirGraphReader can be converted
1.202 +to LemonReader and it can resolve the ID's of the items, the previous
1.203 +result can be achived with the UndirGraphReader class also.
1.204 +
1.205 +
1.206 +\code
1.207 +UndirListGraph network;
1.208 +UndirListGraph::UndirEdgeSet<double> capacity;
1.209 +NewEdgeSetAdaptor<UndirListGraph> traffic(network);
1.210 +NewEdgeSetAdaptor<UndirListGraph>::EdgeSet<double> request(network);
1.211 +
1.212 +UndirGraphReader reader(std::cin, network);
1.213 +reader.readEdgeMap("capacity", capacity);
1.214 +EdgeSetReader edgesetReader(reader, traffic, reader);
1.215 +edgesetReader.readEdgeMap("request", request);
1.216 +
1.217 +reader.run();
1.218 +\endcode
1.219 +
1.220 \author Balazs Dezso
1.221 */
1.222 }