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: <tt>\@nodeset</tt>
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: <tt>\@edgeset</tt>
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 <em>labeled (distinguished) nodes</em> 
alpar@2216: (i.e. nodes having a special
alpar@2216: label on them). The section starts with
alpar@2216: 
alpar@2216: <tt> \@nodes </tt>
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 <em>labeled (distinguished) edges</em>
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 <em> reading and writing
alpar@2216: commands</em>. 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<ListGraph> 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<ListGraph, Node> 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<ListGraph, Edge, ListGraph::EdgeMap<int> > 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<ListGraph> 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<QuotedStringReader>("label", labelMap);
alpar@2216: reader.skipNodeMap<QuotedStringReader>("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: }