1.1 --- a/doc/Doxyfile Tue Feb 01 15:43:14 2005 +0000
1.2 +++ b/doc/Doxyfile Tue Feb 01 15:51:22 2005 +0000
1.3 @@ -454,6 +454,7 @@
1.4 namespaces.dox \
1.5 license.dox \
1.6 developpers_interface.dox \
1.7 + graph_io.dox \
1.8 ../src/lemon \
1.9 ../src/lemon/concept \
1.10 ../src/test/test_tools.h
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/doc/graph_io.dox Tue Feb 01 15:51:22 2005 +0000
2.3 @@ -0,0 +1,244 @@
2.4 +/*!
2.5 +
2.6 +
2.7 +
2.8 +\page graph-io-page Graph Input-Output
2.9 +
2.10 +The standard graph IO makes possible to store graphs and additional maps
2.11 +in flexible and efficient way.
2.12 +
2.13 +\section format The general file format
2.14 +
2.15 +The graph file contains at most four section in the next order:
2.16 +
2.17 +\li nodeset
2.18 +\li edgeset
2.19 +\li nodes
2.20 +\li edges
2.21 +
2.22 +The nodeset section starts with the \c \@nodeset line.
2.23 +The next line contains the names of the maps separated by whitespaces.
2.24 +Each following line describes a node in the graph, it contains
2.25 +in the right order the values of the maps. The first map should contain
2.26 +unique values because it regarded as Id-map.
2.27 +
2.28 +\code
2.29 +@nodeset
2.30 +id x-coord y-coord color
2.31 +3 1.0 4.0 blue
2.32 +5 2.3 5.7 red
2.33 +12 7.8 2.3 green
2.34 +\endcode
2.35 +
2.36 +The edgeset section is very similar to the nodeset section, it has
2.37 +same coloumn oriented structure. It starts with the line \c \@edgeset
2.38 +The next line contains the whitespace separated list of names of the map.
2.39 +Each of the next lines describes one edge. The first two element in the line
2.40 +is the ID of the source and target node as occurs in the first node map.
2.41 +
2.42 +\code
2.43 +@edgeset
2.44 + id weight label
2.45 +3 5 a 4.3 a-edge
2.46 +5 12 c 2.6 c-edge
2.47 +3 12 g 3.4 g-edge
2.48 +\endcode
2.49 +
2.50 +The next section contains outpointed nodes. The section starts with
2.51 +\c \@nodes. Each of the next lines contains a label for a node in the graph
2.52 +and then the ID described in the first column in the nodeset.
2.53 +
2.54 +\code
2.55 +@nodes
2.56 +source 3
2.57 +target 12
2.58 +\endcode
2.59 +
2.60 +The last section describes the outpointed edges. It starts with \c \@edges
2.61 +and then each line contains the name of the edge and the ID.
2.62 +
2.63 +\code
2.64 +@nodes
2.65 +observed c
2.66 +\endcode
2.67 +
2.68 +The file ends with the \c \@end line.
2.69 +
2.70 +The file may contain empty lines and comment lines. The comment lines
2.71 +start with an \c # character.
2.72 +
2.73 +\code
2.74 +@end
2.75 +\endcode
2.76 +
2.77 +\section use Using graph input-output
2.78 +The graph input and output based on writing and reading commands. The user
2.79 +adds writing and reading commands for the reader or writer class, after
2.80 +calls the \c run() method what executes all the given commands.
2.81 +
2.82 +\subsection write Writing a graph
2.83 +
2.84 +The \c GraphWriter class provides the graph output. To write a graph
2.85 +you should first give writing commands for the writer. You can declare
2.86 +write command as \c NodeMap or \c EdgeMap writing and outpointed Node and
2.87 +Edge writing.
2.88 +
2.89 +\code
2.90 +GraphWriter<ListGraph> writer(graph);
2.91 +\endcode
2.92 +
2.93 +The \c addNodeMap() function declares a \c NodeMap writing command in the
2.94 +\c GraphWriter. You should give as parameter the name of the map and the map
2.95 +object. The first NodeMap writing command should write an unique map because
2.96 +it is regarded as ID map.
2.97 +
2.98 +\see IdMap, DescriptorMap
2.99 +
2.100 +\code
2.101 +IdMap<ListGraph, Node> nodeIdMap;
2.102 +writer.addNodeMap("id", nodeIdMap);
2.103 +
2.104 +writer.addNodeMap("x-coord", xCoordMap);
2.105 +writer.addNodeMap("y-coord", yCoordMap);
2.106 +writer.addNodeMap("color", colorMap);
2.107 +\endcode
2.108 +
2.109 +With the \c addEdgeMap() member function you can give an edge map
2.110 +writing command similar to the NodeMaps. The first map writing command should
2.111 +write unique map.
2.112 +
2.113 +\see IdMap, DescriptorMap
2.114 +\code
2.115 +DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
2.116 +writer.addEdgeMap("descriptor", edgeDescMap);
2.117 +
2.118 +writer.addEdgeMap("weight", weightMap);
2.119 +writer.addEdgeMap("label", labelMap);
2.120 +\endcode
2.121 +
2.122 +With \c addNode() and \c addEdge() functions you can point out Nodes and
2.123 +Edges in the graph. By example, you can write out the source and target
2.124 +of the graph.
2.125 +
2.126 +\code
2.127 +writer.addNode("source", sourceNode);
2.128 +writer.addNode("target", targetNode);
2.129 +
2.130 +writer.addEdge("observed", edge);
2.131 +\endcode
2.132 +
2.133 +After you give all write commands you must call the \c run() member
2.134 +function, what execute all the write commands.
2.135 +
2.136 +\code
2.137 +writer.run();
2.138 +\endcode
2.139 +
2.140 +\subsection reading Reading a graph
2.141 +
2.142 +The given file format may contain many maps and outpointed nodes or edges.
2.143 +If you read a graph you need not read all the maps and items just those
2.144 +that you need. The interface of the \c GraphReader is very similar to
2.145 +the GraphWriter but the reading method does not depend on the order the
2.146 +given commands.
2.147 +
2.148 +The reader object suppose that each not readed value does not contains
2.149 +whitespaces therefore it has some extra possibilities to control how could
2.150 +it skip the values when the string representation contains spaces.
2.151 +
2.152 +\code
2.153 +GraphReader<ListGraph> reader(graph);
2.154 +\endcode
2.155 +
2.156 +The \c addNodeMap() function reads a map from the \c \@nodeset section.
2.157 +If there is a map what you do not want to read from the file and there is
2.158 +whitespace in the string represenation of the values then you should
2.159 +call the \c skipNodeMap() template member function with proper parameters.
2.160 +
2.161 +\see QuotedStringReader
2.162 +\code
2.163 +reader.addNodeMap("x-coord", xCoordMap);
2.164 +reader.addNodeMap("y-coord", yCoordMap);
2.165 +
2.166 +reader.addNodeMap<QuotedStringReader>("label", labelMap);
2.167 +reader.skipNodeMap<QuotedStringReader>("description");
2.168 +
2.169 +reader.addNodeMap("color", colorMap);
2.170 +\endcode
2.171 +
2.172 +With the \c addEdgeMap() member function you can give an edge map
2.173 +reading command similar to the NodeMaps.
2.174 +
2.175 +\code
2.176 +reader.addEdgeMap("weight", weightMap);
2.177 +reader.addEdgeMap("label", labelMap);
2.178 +\endcode
2.179 +
2.180 +With \c addNode() and \c addEdge() functions you can read outpointed Nodes and
2.181 +Edges.
2.182 +
2.183 +\code
2.184 +reader.addNode("source", sourceNode);
2.185 +reader.addNode("target", targetNode);
2.186 +
2.187 +reader.addEdge("observed", edge);
2.188 +\endcode
2.189 +
2.190 +After you give all read commands you must call the \c run() member
2.191 +function, what execute all the commands.
2.192 +
2.193 +\code
2.194 +reader.run();
2.195 +\endcode
2.196 +
2.197 +\section types The background of the Reading and Writing
2.198 +The \c GraphReader should know how can read a Value from the given map.
2.199 +By the default implementation the input operator reads a value from
2.200 +the stream and the type of the readed value is the value type of the given map.
2.201 +When the reader should skip a value in the stream, because you do not
2.202 +want to store it in map, the reader skips a character sequence without
2.203 +whitespace.
2.204 +
2.205 +If you want to change the functionality of the reader, you can use
2.206 +template parameters to specialize it. When you give a reading
2.207 +command for a map you can give a Reader type as template parameter.
2.208 +With this template parameter you can control how does read the Reader
2.209 +a value from the stream.
2.210 +
2.211 +The reader has the next structure:
2.212 +\code
2.213 +struct TypeReader {
2.214 + typedef TypeName Value;
2.215 +
2.216 + void read(std::istream& is, Value& value);
2.217 +};
2.218 +\endcode
2.219 +
2.220 +By example, the \c "strings" nodemap contains strings and you do not need
2.221 +the value of the string just the length. Then you can implement own Reader
2.222 +struct.
2.223 +
2.224 +\code
2.225 +struct LengthReader {
2.226 + typedef int Value;
2.227 +
2.228 + void read(std::istream& is, Value& value) {
2.229 + std::string tmp;
2.230 + is >> tmp;
2.231 + value = tmp.length();
2.232 + }
2.233 +};
2.234 +...
2.235 +reader.addNodeMap<LengthReader>("strings", lengthMap);
2.236 +\endcode
2.237 +
2.238 +The global functionality of the reader class can be changed by giving a
2.239 +special template parameter for the GraphReader class. In default way the
2.240 +template parameter the \c DefaultReaderTraits. A reader traits class
2.241 +should provide an inner template class Reader for each type, and an
2.242 +DefaultReader for skipping a value.
2.243 +
2.244 +The specialization of the writing should be very similar to the reading.
2.245 +
2.246 +
2.247 +*/