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