1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/doc/lemon_file_format.dox Thu Sep 14 19:11:24 2006 +0000
1.3 @@ -0,0 +1,270 @@
1.4 +namespace lemon {
1.5 +/*!
1.6 +
1.7 +
1.8 +\page lemon_file_format LEMON Graph File Format
1.9 +
1.10 +The standard graph IO enables one to store graphs and additional maps
1.11 +(i.e. functions on the nodes or edges) in a flexible and efficient way.
1.12 +Before you read this page you should be familiar with LEMON
1.13 +\ref graphs "graphs" and \ref maps-page "maps".
1.14 +
1.15 +\section format The general file format
1.16 +
1.17 +The file contains sections in the following order:
1.18 +
1.19 +\li nodeset
1.20 +\li edgeset
1.21 +\li nodes
1.22 +\li edges
1.23 +\li attributes
1.24 +
1.25 +Some of these sections can be omitted, but you will basicly need the nodeset
1.26 +section (unless your graph has no nodes at all) and the edgeset section
1.27 +(unless your graph has no edges at all).
1.28 +
1.29 +The nodeset section describes the nodes of your graph: it identifies the nodes
1.30 +and gives the maps defined on them, if any. It starts with the
1.31 +following line:
1.32 +
1.33 +<tt>\@nodeset</tt>
1.34 +
1.35 +The next line contains the names of the nodemaps, separated by whitespaces. Each
1.36 +following line describes a node in the graph: it contains the values of the
1.37 +maps in the right order. The map named "label" should contain unique values
1.38 +because it is regarded as a label map. These labels need not be numbers but they
1.39 +must identify the nodes uniquely for later reference. For example:
1.40 +
1.41 +\code
1.42 +@nodeset
1.43 +label x-coord y-coord color
1.44 +3 1.0 4.0 blue
1.45 +5 2.3 5.7 red
1.46 +12 7.8 2.3 green
1.47 +\endcode
1.48 +
1.49 +The edgeset section is very similar to the nodeset section, it has
1.50 +the same coloumn oriented structure. It starts with the line
1.51 +
1.52 +<tt>\@edgeset</tt>
1.53 +
1.54 +The next line contains the whitespace separated list of names of the edge
1.55 +maps. Each of the next lines describes one edge. The first two elements in
1.56 +the line are the labels of the source and target (or tail and head) nodes of the
1.57 +edge as they occur in the label node map of the nodeset section. You can also
1.58 +have an optional label map on the edges for later reference (which has to be
1.59 +unique in this case).
1.60 +
1.61 +\code
1.62 +@edgeset
1.63 + label weight note
1.64 +3 5 a 4.3 a-edge
1.65 +5 12 c 2.6 c-edge
1.66 +3 12 g 3.4 g-edge
1.67 +\endcode
1.68 +
1.69 +The \e nodes section contains <em>labeled (distinguished) nodes</em>
1.70 +(i.e. nodes having a special
1.71 +label on them). The section starts with
1.72 +
1.73 +<tt> \@nodes </tt>
1.74 +
1.75 +Each of the next lines contains a label for a node in the graph
1.76 +and then the label as described in the \e nodeset section.
1.77 +
1.78 +\code
1.79 +@nodes
1.80 +source 3
1.81 +target 12
1.82 +\endcode
1.83 +
1.84 +The last section describes the <em>labeled (distinguished) edges</em>
1.85 +(i.e. edges having a special label on them). It starts with \c \@edges
1.86 +and then each line contains the name of the edge and the label.
1.87 +
1.88 +\code
1.89 +@edges
1.90 +observed c
1.91 +\endcode
1.92 +
1.93 +
1.94 +The file may contain empty lines and comment lines. The comment lines
1.95 +start with an \c # character.
1.96 +
1.97 +The attributes section can handle some information about the graph. It
1.98 +contains key-value pairs in each line (a key and the mapped value to key). The
1.99 +key should be a string without whitespaces, the value can be of various types.
1.100 +
1.101 +\code
1.102 +@attributes
1.103 +title "Four colored planar graph"
1.104 +author "Balazs DEZSO"
1.105 +copyright "Lemon Library"
1.106 +version 12
1.107 +\endcode
1.108 +
1.109 +Finally, the file should be closed with \c \@end line.
1.110 +
1.111 +
1.112 +\section use Using graph input-output
1.113 +
1.114 +
1.115 +The graph input and output is based on <em> reading and writing
1.116 +commands</em>. The user gives reading and writing commands to the reader or
1.117 +writer class, then he calls the \c run() method that executes all the given
1.118 +commands.
1.119 +
1.120 +\subsection write Writing a graph
1.121 +
1.122 +The \ref lemon::GraphWriter "GraphWriter" template class
1.123 +provides the graph output. To write a graph
1.124 +you should first give writing commands to the writer. You can declare
1.125 +writing command as \c NodeMap or \c EdgeMap writing and labeled Node and
1.126 +Edge writing.
1.127 +
1.128 +\code
1.129 +GraphWriter<ListGraph> writer(std::cout, graph);
1.130 +\endcode
1.131 +
1.132 +The \ref lemon::GraphWriter::writeNodeMap() "writeNodeMap()"
1.133 +function declares a \c NodeMap writing command in the
1.134 +\ref lemon::GraphWriter "GraphWriter".
1.135 +You should give a name to the map and the map
1.136 +object as parameters. The NodeMap writing command with name "label" should write a
1.137 +unique map because it will be regarded as a label map.
1.138 +
1.139 +\see IdMap, DescriptorMap
1.140 +
1.141 +\code
1.142 +IdMap<ListGraph, Node> nodeLabelMap;
1.143 +writer.writeNodeMap("label", nodeLabelMap);
1.144 +
1.145 +writer.writeNodeMap("x-coord", xCoordMap);
1.146 +writer.writeNodeMap("y-coord", yCoordMap);
1.147 +writer.writeNodeMap("color", colorMap);
1.148 +\endcode
1.149 +
1.150 +With the \ref lemon::GraphWriter::writeEdgeMap() "writeEdgeMap()"
1.151 +member function you can give an edge map
1.152 +writing command similar to the NodeMaps.
1.153 +
1.154 +\see IdMap, DescriptorMap
1.155 +
1.156 +\code
1.157 +DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
1.158 +writer.writeEdgeMap("descriptor", edgeDescMap);
1.159 +
1.160 +writer.writeEdgeMap("weight", weightMap);
1.161 +writer.writeEdgeMap("note", noteMap);
1.162 +\endcode
1.163 +
1.164 +With \ref lemon::GraphWriter::writeNode() "writeNode()"
1.165 +and \ref lemon::GraphWriter::writeEdge() "writeEdge()"
1.166 +functions you can designate Nodes and
1.167 +Edges in the graph. For example, you can write out the source and target node
1.168 +of a maximum flow instance.
1.169 +
1.170 +\code
1.171 +writer.writeNode("source", sourceNode);
1.172 +writer.writeNode("target", targetNode);
1.173 +
1.174 +writer.writeEdge("observed", edge);
1.175 +\endcode
1.176 +
1.177 +With \ref lemon::GraphWriter::writeAttribute() "writeAttribute()"
1.178 +function you can write an attribute to the file.
1.179 +
1.180 +\code
1.181 +writer.writeAttribute("author", "Balazs DEZSO");
1.182 +writer.writeAttribute("version", 12);
1.183 +\endcode
1.184 +
1.185 +After you give all write commands you must call the
1.186 +\ref lemon::GraphWriter::run() "run()" member
1.187 +function, which executes all the writing commands.
1.188 +
1.189 +\code
1.190 +writer.run();
1.191 +\endcode
1.192 +
1.193 +\subsection reading Reading a graph
1.194 +
1.195 +The file to be read may contain several maps and labeled nodes or edges.
1.196 +If you read a graph you need not read all the maps and items just those
1.197 +that you need. The interface of the \ref lemon::GraphReader "GraphReader"
1.198 +is very similar to
1.199 +the \ref lemon::GraphWriter "GraphWriter"
1.200 +but the reading method does not depend on the order of the
1.201 +given commands.
1.202 +
1.203 +The reader object assumes that each not read value does not contain
1.204 +whitespaces, therefore it has some extra possibilities to control how
1.205 +it should skip the values when the string representation contains spaces.
1.206 +
1.207 +\code
1.208 +GraphReader<ListGraph> reader(std::cin, graph);
1.209 +\endcode
1.210 +
1.211 +The \ref lemon::GraphReader::readNodeMap() "readNodeMap()"
1.212 +function reads a map from the \c nodeset section.
1.213 +If there is a map that you do not want to read from the file and there are
1.214 +whitespaces in the string represenation of the values then you should
1.215 +call the \ref lemon::GraphReader::skipNodeMap() "skipNodeMap()"
1.216 +template member function with proper parameters.
1.217 +
1.218 +\see QuotedStringReader
1.219 +
1.220 +\code
1.221 +reader.readNodeMap("x-coord", xCoordMap);
1.222 +reader.readNodeMap("y-coord", yCoordMap);
1.223 +
1.224 +reader.readNodeMap<QuotedStringReader>("label", labelMap);
1.225 +reader.skipNodeMap<QuotedStringReader>("description");
1.226 +
1.227 +reader.readNodeMap("color", colorMap);
1.228 +\endcode
1.229 +
1.230 +With the \ref lemon::GraphReader::readEdgeMap() "readEdgeMap()"
1.231 +member function you can give an edge map
1.232 +reading command similar to the NodeMaps.
1.233 +
1.234 +\code
1.235 +reader.readEdgeMap("weight", weightMap);
1.236 +reader.readEdgeMap("label", labelMap);
1.237 +\endcode
1.238 +
1.239 +With \ref lemon::GraphReader::readNode() "readNode()"
1.240 +and \ref lemon::GraphReader::readEdge() "readEdge()"
1.241 +functions you can read labeled Nodes and
1.242 +Edges.
1.243 +
1.244 +\code
1.245 +reader.readNode("source", sourceNode);
1.246 +reader.readNode("target", targetNode);
1.247 +
1.248 +reader.readEdge("observed", edge);
1.249 +\endcode
1.250 +
1.251 +With \ref lemon::GraphReader::readAttribute() "readAttribute()"
1.252 +function you can read an attribute from the file.
1.253 +
1.254 +\code
1.255 +std::string author;
1.256 +writer.readAttribute("author", author);
1.257 +int version;
1.258 +writer.writeAttribute("version", version);
1.259 +\endcode
1.260 +
1.261 +After you give all read commands you must call the
1.262 +\ref lemon::GraphReader::run() "run()" member
1.263 +function, which executes all the commands.
1.264 +
1.265 +\code
1.266 +reader.run();
1.267 +\endcode
1.268 +
1.269 +If you want to lear more, read the \ref read_write_bg "background technics".
1.270 +
1.271 +\author Balazs Dezso
1.272 +*/
1.273 +}