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