1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/doc/graph_io.dox Tue Feb 01 15:51:22 2005 +0000
1.3 @@ -0,0 +1,244 @@
1.4 +/*!
1.5 +
1.6 +
1.7 +
1.8 +\page graph-io-page Graph Input-Output
1.9 +
1.10 +The standard graph IO makes possible to store graphs and additional maps
1.11 +in flexible and efficient way.
1.12 +
1.13 +\section format The general file format
1.14 +
1.15 +The graph file contains at most four section in the next order:
1.16 +
1.17 +\li nodeset
1.18 +\li edgeset
1.19 +\li nodes
1.20 +\li edges
1.21 +
1.22 +The nodeset section starts with the \c \@nodeset line.
1.23 +The next line contains the names of the maps separated by whitespaces.
1.24 +Each following line describes a node in the graph, it contains
1.25 +in the right order the values of the maps. The first map should contain
1.26 +unique values because it regarded as Id-map.
1.27 +
1.28 +\code
1.29 +@nodeset
1.30 +id x-coord y-coord color
1.31 +3 1.0 4.0 blue
1.32 +5 2.3 5.7 red
1.33 +12 7.8 2.3 green
1.34 +\endcode
1.35 +
1.36 +The edgeset section is very similar to the nodeset section, it has
1.37 +same coloumn oriented structure. It starts with the line \c \@edgeset
1.38 +The next line contains the whitespace separated list of names of the map.
1.39 +Each of the next lines describes one edge. The first two element in the line
1.40 +is the ID of the source and target node as occurs in the first node map.
1.41 +
1.42 +\code
1.43 +@edgeset
1.44 + id weight label
1.45 +3 5 a 4.3 a-edge
1.46 +5 12 c 2.6 c-edge
1.47 +3 12 g 3.4 g-edge
1.48 +\endcode
1.49 +
1.50 +The next section contains outpointed nodes. The section starts with
1.51 +\c \@nodes. Each of the next lines contains a label for a node in the graph
1.52 +and then the ID described in the first column in the nodeset.
1.53 +
1.54 +\code
1.55 +@nodes
1.56 +source 3
1.57 +target 12
1.58 +\endcode
1.59 +
1.60 +The last section describes the outpointed edges. It starts with \c \@edges
1.61 +and then each line contains the name of the edge and the ID.
1.62 +
1.63 +\code
1.64 +@nodes
1.65 +observed c
1.66 +\endcode
1.67 +
1.68 +The file ends with the \c \@end line.
1.69 +
1.70 +The file may contain empty lines and comment lines. The comment lines
1.71 +start with an \c # character.
1.72 +
1.73 +\code
1.74 +@end
1.75 +\endcode
1.76 +
1.77 +\section use Using graph input-output
1.78 +The graph input and output based on writing and reading commands. The user
1.79 +adds writing and reading commands for the reader or writer class, after
1.80 +calls the \c run() method what executes all the given commands.
1.81 +
1.82 +\subsection write Writing a graph
1.83 +
1.84 +The \c GraphWriter class provides the graph output. To write a graph
1.85 +you should first give writing commands for the writer. You can declare
1.86 +write command as \c NodeMap or \c EdgeMap writing and outpointed Node and
1.87 +Edge writing.
1.88 +
1.89 +\code
1.90 +GraphWriter<ListGraph> writer(graph);
1.91 +\endcode
1.92 +
1.93 +The \c addNodeMap() function declares a \c NodeMap writing command in the
1.94 +\c GraphWriter. You should give as parameter the name of the map and the map
1.95 +object. The first NodeMap writing command should write an unique map because
1.96 +it is regarded as ID map.
1.97 +
1.98 +\see IdMap, DescriptorMap
1.99 +
1.100 +\code
1.101 +IdMap<ListGraph, Node> nodeIdMap;
1.102 +writer.addNodeMap("id", nodeIdMap);
1.103 +
1.104 +writer.addNodeMap("x-coord", xCoordMap);
1.105 +writer.addNodeMap("y-coord", yCoordMap);
1.106 +writer.addNodeMap("color", colorMap);
1.107 +\endcode
1.108 +
1.109 +With the \c addEdgeMap() member function you can give an edge map
1.110 +writing command similar to the NodeMaps. The first map writing command should
1.111 +write unique map.
1.112 +
1.113 +\see IdMap, DescriptorMap
1.114 +\code
1.115 +DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
1.116 +writer.addEdgeMap("descriptor", edgeDescMap);
1.117 +
1.118 +writer.addEdgeMap("weight", weightMap);
1.119 +writer.addEdgeMap("label", labelMap);
1.120 +\endcode
1.121 +
1.122 +With \c addNode() and \c addEdge() functions you can point out Nodes and
1.123 +Edges in the graph. By example, you can write out the source and target
1.124 +of the graph.
1.125 +
1.126 +\code
1.127 +writer.addNode("source", sourceNode);
1.128 +writer.addNode("target", targetNode);
1.129 +
1.130 +writer.addEdge("observed", edge);
1.131 +\endcode
1.132 +
1.133 +After you give all write commands you must call the \c run() member
1.134 +function, what execute all the write commands.
1.135 +
1.136 +\code
1.137 +writer.run();
1.138 +\endcode
1.139 +
1.140 +\subsection reading Reading a graph
1.141 +
1.142 +The given file format may contain many maps and outpointed nodes or edges.
1.143 +If you read a graph you need not read all the maps and items just those
1.144 +that you need. The interface of the \c GraphReader is very similar to
1.145 +the GraphWriter but the reading method does not depend on the order the
1.146 +given commands.
1.147 +
1.148 +The reader object suppose that each not readed value does not contains
1.149 +whitespaces therefore it has some extra possibilities to control how could
1.150 +it skip the values when the string representation contains spaces.
1.151 +
1.152 +\code
1.153 +GraphReader<ListGraph> reader(graph);
1.154 +\endcode
1.155 +
1.156 +The \c addNodeMap() function reads a map from the \c \@nodeset section.
1.157 +If there is a map what you do not want to read from the file and there is
1.158 +whitespace in the string represenation of the values then you should
1.159 +call the \c skipNodeMap() template member function with proper parameters.
1.160 +
1.161 +\see QuotedStringReader
1.162 +\code
1.163 +reader.addNodeMap("x-coord", xCoordMap);
1.164 +reader.addNodeMap("y-coord", yCoordMap);
1.165 +
1.166 +reader.addNodeMap<QuotedStringReader>("label", labelMap);
1.167 +reader.skipNodeMap<QuotedStringReader>("description");
1.168 +
1.169 +reader.addNodeMap("color", colorMap);
1.170 +\endcode
1.171 +
1.172 +With the \c addEdgeMap() member function you can give an edge map
1.173 +reading command similar to the NodeMaps.
1.174 +
1.175 +\code
1.176 +reader.addEdgeMap("weight", weightMap);
1.177 +reader.addEdgeMap("label", labelMap);
1.178 +\endcode
1.179 +
1.180 +With \c addNode() and \c addEdge() functions you can read outpointed Nodes and
1.181 +Edges.
1.182 +
1.183 +\code
1.184 +reader.addNode("source", sourceNode);
1.185 +reader.addNode("target", targetNode);
1.186 +
1.187 +reader.addEdge("observed", edge);
1.188 +\endcode
1.189 +
1.190 +After you give all read commands you must call the \c run() member
1.191 +function, what execute all the commands.
1.192 +
1.193 +\code
1.194 +reader.run();
1.195 +\endcode
1.196 +
1.197 +\section types The background of the Reading and Writing
1.198 +The \c GraphReader should know how can read a Value from the given map.
1.199 +By the default implementation the input operator reads a value from
1.200 +the stream and the type of the readed value is the value type of the given map.
1.201 +When the reader should skip a value in the stream, because you do not
1.202 +want to store it in map, the reader skips a character sequence without
1.203 +whitespace.
1.204 +
1.205 +If you want to change the functionality of the reader, you can use
1.206 +template parameters to specialize it. When you give a reading
1.207 +command for a map you can give a Reader type as template parameter.
1.208 +With this template parameter you can control how does read the Reader
1.209 +a value from the stream.
1.210 +
1.211 +The reader has the next structure:
1.212 +\code
1.213 +struct TypeReader {
1.214 + typedef TypeName Value;
1.215 +
1.216 + void read(std::istream& is, Value& value);
1.217 +};
1.218 +\endcode
1.219 +
1.220 +By example, the \c "strings" nodemap contains strings and you do not need
1.221 +the value of the string just the length. Then you can implement own Reader
1.222 +struct.
1.223 +
1.224 +\code
1.225 +struct LengthReader {
1.226 + typedef int Value;
1.227 +
1.228 + void read(std::istream& is, Value& value) {
1.229 + std::string tmp;
1.230 + is >> tmp;
1.231 + value = tmp.length();
1.232 + }
1.233 +};
1.234 +...
1.235 +reader.addNodeMap<LengthReader>("strings", lengthMap);
1.236 +\endcode
1.237 +
1.238 +The global functionality of the reader class can be changed by giving a
1.239 +special template parameter for the GraphReader class. In default way the
1.240 +template parameter the \c DefaultReaderTraits. A reader traits class
1.241 +should provide an inner template class Reader for each type, and an
1.242 +DefaultReader for skipping a value.
1.243 +
1.244 +The specialization of the writing should be very similar to the reading.
1.245 +
1.246 +
1.247 +*/