diff -r 83ec156873ab -r 1e45cdeea3cc doc/lemon_file_format.dox --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lemon_file_format.dox Thu Sep 14 19:11:24 2006 +0000 @@ -0,0 +1,270 @@ +namespace lemon { +/*! + + +\page lemon_file_format LEMON Graph File Format + +The standard graph IO enables one to store graphs and additional maps +(i.e. functions on the nodes or edges) in a flexible and efficient way. +Before you read this page you should be familiar with LEMON +\ref graphs "graphs" and \ref maps-page "maps". + +\section format The general file format + +The file contains sections in the following order: + +\li nodeset +\li edgeset +\li nodes +\li edges +\li attributes + +Some of these sections can be omitted, but you will basicly need the nodeset +section (unless your graph has no nodes at all) and the edgeset section +(unless your graph has no edges at all). + +The nodeset section describes the nodes of your graph: it identifies the nodes +and gives the maps defined on them, if any. It starts with the +following line: + +\@nodeset + +The next line contains the names of the nodemaps, separated by whitespaces. Each +following line describes a node in the graph: it contains the values of the +maps in the right order. The map named "label" should contain unique values +because it is regarded as a label map. These labels need not be numbers but they +must identify the nodes uniquely for later reference. For example: + +\code +@nodeset +label x-coord y-coord color +3 1.0 4.0 blue +5 2.3 5.7 red +12 7.8 2.3 green +\endcode + +The edgeset section is very similar to the nodeset section, it has +the same coloumn oriented structure. It starts with the line + +\@edgeset + +The next line contains the whitespace separated list of names of the edge +maps. Each of the next lines describes one edge. The first two elements in +the line are the labels of the source and target (or tail and head) nodes of the +edge as they occur in the label node map of the nodeset section. You can also +have an optional label map on the edges for later reference (which has to be +unique in this case). + +\code +@edgeset + label weight note +3 5 a 4.3 a-edge +5 12 c 2.6 c-edge +3 12 g 3.4 g-edge +\endcode + +The \e nodes section contains labeled (distinguished) nodes +(i.e. nodes having a special +label on them). The section starts with + + \@nodes + +Each of the next lines contains a label for a node in the graph +and then the label as described in the \e nodeset section. + +\code +@nodes +source 3 +target 12 +\endcode + +The last section describes the labeled (distinguished) edges +(i.e. edges having a special label on them). It starts with \c \@edges +and then each line contains the name of the edge and the label. + +\code +@edges +observed c +\endcode + + +The file may contain empty lines and comment lines. The comment lines +start with an \c # character. + +The attributes section can handle some information about the graph. It +contains key-value pairs in each line (a key and the mapped value to key). The +key should be a string without whitespaces, the value can be of various types. + +\code +@attributes +title "Four colored planar graph" +author "Balazs DEZSO" +copyright "Lemon Library" +version 12 +\endcode + +Finally, the file should be closed with \c \@end line. + + +\section use Using graph input-output + + +The graph input and output is based on reading and writing +commands. The user gives reading and writing commands to the reader or +writer class, then he calls the \c run() method that executes all the given +commands. + +\subsection write Writing a graph + +The \ref lemon::GraphWriter "GraphWriter" template class +provides the graph output. To write a graph +you should first give writing commands to the writer. You can declare +writing command as \c NodeMap or \c EdgeMap writing and labeled Node and +Edge writing. + +\code +GraphWriter writer(std::cout, graph); +\endcode + +The \ref lemon::GraphWriter::writeNodeMap() "writeNodeMap()" +function declares a \c NodeMap writing command in the +\ref lemon::GraphWriter "GraphWriter". +You should give a name to the map and the map +object as parameters. The NodeMap writing command with name "label" should write a +unique map because it will be regarded as a label map. + +\see IdMap, DescriptorMap + +\code +IdMap nodeLabelMap; +writer.writeNodeMap("label", nodeLabelMap); + +writer.writeNodeMap("x-coord", xCoordMap); +writer.writeNodeMap("y-coord", yCoordMap); +writer.writeNodeMap("color", colorMap); +\endcode + +With the \ref lemon::GraphWriter::writeEdgeMap() "writeEdgeMap()" +member function you can give an edge map +writing command similar to the NodeMaps. + +\see IdMap, DescriptorMap + +\code +DescriptorMap > edgeDescMap(graph); +writer.writeEdgeMap("descriptor", edgeDescMap); + +writer.writeEdgeMap("weight", weightMap); +writer.writeEdgeMap("note", noteMap); +\endcode + +With \ref lemon::GraphWriter::writeNode() "writeNode()" +and \ref lemon::GraphWriter::writeEdge() "writeEdge()" +functions you can designate Nodes and +Edges in the graph. For example, you can write out the source and target node +of a maximum flow instance. + +\code +writer.writeNode("source", sourceNode); +writer.writeNode("target", targetNode); + +writer.writeEdge("observed", edge); +\endcode + +With \ref lemon::GraphWriter::writeAttribute() "writeAttribute()" +function you can write an attribute to the file. + +\code +writer.writeAttribute("author", "Balazs DEZSO"); +writer.writeAttribute("version", 12); +\endcode + +After you give all write commands you must call the +\ref lemon::GraphWriter::run() "run()" member +function, which executes all the writing commands. + +\code +writer.run(); +\endcode + +\subsection reading Reading a graph + +The file to be read may contain several maps and labeled nodes or edges. +If you read a graph you need not read all the maps and items just those +that you need. The interface of the \ref lemon::GraphReader "GraphReader" +is very similar to +the \ref lemon::GraphWriter "GraphWriter" +but the reading method does not depend on the order of the +given commands. + +The reader object assumes that each not read value does not contain +whitespaces, therefore it has some extra possibilities to control how +it should skip the values when the string representation contains spaces. + +\code +GraphReader reader(std::cin, graph); +\endcode + +The \ref lemon::GraphReader::readNodeMap() "readNodeMap()" +function reads a map from the \c nodeset section. +If there is a map that you do not want to read from the file and there are +whitespaces in the string represenation of the values then you should +call the \ref lemon::GraphReader::skipNodeMap() "skipNodeMap()" +template member function with proper parameters. + +\see QuotedStringReader + +\code +reader.readNodeMap("x-coord", xCoordMap); +reader.readNodeMap("y-coord", yCoordMap); + +reader.readNodeMap("label", labelMap); +reader.skipNodeMap("description"); + +reader.readNodeMap("color", colorMap); +\endcode + +With the \ref lemon::GraphReader::readEdgeMap() "readEdgeMap()" +member function you can give an edge map +reading command similar to the NodeMaps. + +\code +reader.readEdgeMap("weight", weightMap); +reader.readEdgeMap("label", labelMap); +\endcode + +With \ref lemon::GraphReader::readNode() "readNode()" +and \ref lemon::GraphReader::readEdge() "readEdge()" +functions you can read labeled Nodes and +Edges. + +\code +reader.readNode("source", sourceNode); +reader.readNode("target", targetNode); + +reader.readEdge("observed", edge); +\endcode + +With \ref lemon::GraphReader::readAttribute() "readAttribute()" +function you can read an attribute from the file. + +\code +std::string author; +writer.readAttribute("author", author); +int version; +writer.writeAttribute("version", version); +\endcode + +After you give all read commands you must call the +\ref lemon::GraphReader::run() "run()" member +function, which executes all the commands. + +\code +reader.run(); +\endcode + +If you want to lear more, read the \ref read_write_bg "background technics". + +\author Balazs Dezso +*/ +}