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