doc/graph_io.dox
author alpar
Wed, 29 Jun 2005 12:52:20 +0000
changeset 1523 144ab0e4b09c
parent 1394 f0c48d7fa73d
child 1526 8c14aa8f27a2
permissions -rw-r--r--
Hmmm...
     1 namespace lemon {
     2 /*!
     3 
     4 
     5 \page graph-io-page Graph Input-Output
     6 
     7 The standard graph IO enables to store graphs and additional maps
     8 in a flexible and efficient way. 
     9 
    10 \section format The general file format
    11 
    12 The file contains at most four sections in the following order:
    13 
    14 \li nodeset
    15 \li edgeset
    16 \li nodes
    17 \li edges
    18 
    19 The nodeset section starts with the following line:
    20 
    21 <tt>\@nodeset</tt>
    22 
    23 The next line contains the names of the nodemaps, separated by whitespaces.  Each
    24 following line describes a node in the graph: it contains the values of the
    25 maps in the right order. The map named "id" should contain unique values
    26 because it is regarded as an ID-map. For example:
    27 
    28 \code
    29 @nodeset
    30 id  x-coord  y-coord  color
    31 3   1.0      4.0      blue
    32 5   2.3      5.7      red
    33 12  7.8      2.3      green
    34 \endcode
    35 
    36 The edgeset section is very similar to the nodeset section, it has
    37 the same coloumn oriented structure. It starts with the line 
    38 
    39 <tt>\@edgeset</tt>
    40 
    41 The next line contains the whitespace separated list of names of the maps.
    42 Each of the next lines describes one edge. The first two elements in the line
    43 are the IDs of the source and target (or tail and head) node of the edge as they occur in the ID node
    44 map. You can also have an optional ID map on the edges for later reference.
    45 
    46 \code
    47 @edgeset
    48              id    weight   label
    49 3   5        a     4.3      a-edge
    50 5   12       c     2.6      c-edge
    51 3   12       g     3.4      g-edge
    52 \endcode
    53 
    54 The next section contains <em>labeled nodes</em> (i.e. nodes having a special
    55 label on them). The section starts with
    56 
    57 <tt> \@nodes </tt>
    58 
    59 Each of the next lines contains a label for a node in the graph 
    60 and then the ID described in the nodeset section.
    61 
    62 \code
    63 @nodes 
    64 source 3
    65 target 12
    66 \endcode
    67 
    68 The last section describes the <em>labeled edges</em>
    69 (i.e. edges having a special label on them). It starts with \c \@edges
    70 and then each line contains the name of the edge and the ID.
    71 
    72 \code
    73 @nodes 
    74 observed c
    75 \endcode
    76 
    77 
    78 The file may contain empty lines and comment lines. The comment lines
    79 start with an \c # character.
    80 
    81 The file ends with the 
    82 
    83 <tt> \@end </tt>
    84 
    85 line.
    86 
    87 
    88 \section use Using graph input-output
    89 The graph input and output is based on reading and writing  commands. The user
    90 adds reading and writing commands to the reader or writer class, then he
    91 calls the \c run() method that executes all the given commands.
    92 
    93 \subsection write Writing a graph
    94 
    95 The \c GraphWriter class provides the graph output. To write a graph
    96 you should first give writing commands for the writer. You can declare
    97 write command as \c NodeMap or \c EdgeMap writing and labeled Node and
    98 Edge writing.
    99 
   100 \code
   101 GraphWriter<ListGraph> writer(std::cout, graph);
   102 \endcode
   103 
   104 The \c writeNodeMap() function declares a \c NodeMap writing command in the
   105 \c GraphWriter. You should give a name of the map and the map
   106 object as parameters. The NodeMap writing command with name "id" should write a 
   107 unique map because it is regarded as ID map.
   108 
   109 \see IdMap, DescriptorMap  
   110 
   111 \code
   112 IdMap<ListGraph, Node> nodeIdMap;
   113 writer.writeNodeMap("id", nodeIdMap);
   114 
   115 writer.writeNodeMap("x-coord", xCoordMap);
   116 writer.writeNodeMap("y-coord", yCoordMap);
   117 writer.writeNodeMap("color", colorMap);
   118 \endcode
   119 
   120 With the \c writeEdgeMap() member function you can give an edge map
   121 writing command similar to the NodeMaps.
   122 
   123 \see IdMap, DescriptorMap  
   124 
   125 \code
   126 DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
   127 writer.writeEdgeMap("descriptor", edgeDescMap);
   128 
   129 writer.writeEdgeMap("weight", weightMap);
   130 writer.writeEdgeMap("label", labelMap);
   131 \endcode
   132 
   133 With \c writeNode() and \c writeEdge() functions you can designate Nodes and
   134 Edges in the graph. For example, you can write out the source and target node
   135 of a maximum flow instance.
   136 
   137 \code
   138 writer.writeNode("source", sourceNode);
   139 writer.writeNode("target", targetNode);
   140 
   141 writer.writeEdge("observed", edge);
   142 \endcode
   143 
   144 After you give all write commands you must call the \c run() member
   145 function, which executes all the writing commands.
   146 
   147 \code
   148 writer.run();
   149 \endcode
   150 
   151 \subsection reading Reading a graph
   152 
   153 The given file format may contain several maps and labeled nodes or edges.
   154 If you read a graph you need not read all the maps and items just those
   155 that you need. The interface of the \c GraphReader is very similar to
   156 the GraphWriter but the reading method does not depend on the order of the
   157 given commands.
   158 
   159 The reader object assumes that each not readed value does not contain 
   160 whitespaces, therefore it has some extra possibilities to control how
   161 it should skip the values when the string representation contains spaces.
   162 
   163 \code
   164 GraphReader<ListGraph> reader(std::cin, graph);
   165 \endcode
   166 
   167 The \c readNodeMap() function reads a map from the \c \@nodeset section.
   168 If there is a map that you do not want to read from the file and there are
   169 whitespaces in the string represenation of the values then you should
   170 call the \c skipNodeMap() template member function with proper parameters.
   171 
   172 \see QuotedStringReader
   173 
   174 \code
   175 reader.readNodeMap("x-coord", xCoordMap);
   176 reader.readNodeMap("y-coord", yCoordMap);
   177 
   178 reader.readNodeMap<QuotedStringReader>("label", labelMap);
   179 reader.skipNodeMap<QuotedStringReader>("description");
   180 
   181 reader.readNodeMap("color", colorMap);
   182 \endcode
   183 
   184 With the \c readEdgeMap() member function you can give an edge map
   185 reading command similar to the NodeMaps. 
   186 
   187 \code
   188 reader.readEdgeMap("weight", weightMap);
   189 reader.readEdgeMap("label", labelMap);
   190 \endcode
   191 
   192 With \c readNode() and \c readEdge() functions you can read labeled Nodes and
   193 Edges.
   194 
   195 \code
   196 reader.readNode("source", sourceNode);
   197 reader.readNode("target", targetNode);
   198 
   199 reader.readEdge("observed", edge);
   200 \endcode
   201 
   202 After you give all read commands you must call the \c run() member
   203 function, which executes all the commands.
   204 
   205 \code
   206 reader.run();
   207 \endcode
   208 
   209 \section types The background of Reading and Writing
   210 The \c GraphReader should know how to read a Value from the given map.
   211 By the default implementation the input operator reads a value from
   212 the stream and the type of the readed value is the value type of the given map.
   213 When the reader should skip a value in the stream, because you do not
   214 want to store it in map, the reader skips a character sequence without 
   215 whitespace. 
   216 
   217 If you want to change the functionality of the reader, you can use
   218 template parameters to specialize it. When you give a reading
   219 command for a map you can give a Reader type as template parameter.
   220 With this template parameter you can control how the Reader reads
   221 a value from the stream.
   222 
   223 The reader has the next structure: 
   224 \code
   225 struct TypeReader {
   226   typedef TypeName Value;
   227 
   228   void read(std::istream& is, Value& value);
   229 };
   230 \endcode
   231 
   232 By example, the \c "strings" nodemap contains strings and you do not need
   233 the value of the string just the length. Then you can implement own Reader
   234 struct.
   235 
   236 \code
   237 struct LengthReader {
   238   typedef int Value;
   239 
   240   void read(std::istream& is, Value& value) {
   241     std::string tmp;
   242     is >> tmp;
   243     value = tmp.length();
   244   }
   245 };
   246 ...
   247 reader.readNodeMap<LengthReader>("strings", lengthMap);
   248 \endcode  
   249 
   250 The global functionality of the reader class can be changed by giving a
   251 special template parameter for the GraphReader class. By default, the
   252 template parameter is \c DefaultReaderTraits. A reader traits class 
   253 should provide an inner template class Reader for each type, and an 
   254 DefaultReader for skipping a value.
   255 
   256 The specialization of the writing should be very similar to the reading.
   257 
   258 \author Balazs Dezso
   259 */
   260 }