diff -r b5ad821053a1 -r eb57527fd183 doc/graph_io.dox --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/graph_io.dox Tue Feb 01 15:51:22 2005 +0000 @@ -0,0 +1,244 @@ +/*! + + + +\page graph-io-page Graph Input-Output + +The standard graph IO makes possible to store graphs and additional maps +in flexible and efficient way. + +\section format The general file format + +The graph file contains at most four section in the next order: + +\li nodeset +\li edgeset +\li nodes +\li edges + +The nodeset section starts with the \c \@nodeset line. +The next line contains the names of the maps separated by whitespaces. +Each following line describes a node in the graph, it contains +in the right order the values of the maps. The first map should contain +unique values because it regarded as Id-map. + +\code +@nodeset +id x-coord y-coord color +3 1.0 4.0 blue +5 2.3 5.7 red +12 7.8 2.3 green +\endcode + +The edgeset section is very similar to the nodeset section, it has +same coloumn oriented structure. It starts with the line \c \@edgeset +The next line contains the whitespace separated list of names of the map. +Each of the next lines describes one edge. The first two element in the line +is the ID of the source and target node as occurs in the first node map. + +\code +@edgeset + id weight label +3 5 a 4.3 a-edge +5 12 c 2.6 c-edge +3 12 g 3.4 g-edge +\endcode + +The next section contains outpointed nodes. The section starts with +\c \@nodes. Each of the next lines contains a label for a node in the graph +and then the ID described in the first column in the nodeset. + +\code +@nodes +source 3 +target 12 +\endcode + +The last section describes the outpointed edges. It starts with \c \@edges +and then each line contains the name of the edge and the ID. + +\code +@nodes +observed c +\endcode + +The file ends with the \c \@end line. + +The file may contain empty lines and comment lines. The comment lines +start with an \c # character. + +\code +@end +\endcode + +\section use Using graph input-output +The graph input and output based on writing and reading commands. The user +adds writing and reading commands for the reader or writer class, after +calls the \c run() method what executes all the given commands. + +\subsection write Writing a graph + +The \c GraphWriter class provides the graph output. To write a graph +you should first give writing commands for the writer. You can declare +write command as \c NodeMap or \c EdgeMap writing and outpointed Node and +Edge writing. + +\code +GraphWriter writer(graph); +\endcode + +The \c addNodeMap() function declares a \c NodeMap writing command in the +\c GraphWriter. You should give as parameter the name of the map and the map +object. The first NodeMap writing command should write an unique map because +it is regarded as ID map. + +\see IdMap, DescriptorMap + +\code +IdMap nodeIdMap; +writer.addNodeMap("id", nodeIdMap); + +writer.addNodeMap("x-coord", xCoordMap); +writer.addNodeMap("y-coord", yCoordMap); +writer.addNodeMap("color", colorMap); +\endcode + +With the \c addEdgeMap() member function you can give an edge map +writing command similar to the NodeMaps. The first map writing command should +write unique map. + +\see IdMap, DescriptorMap +\code +DescriptorMap > edgeDescMap(graph); +writer.addEdgeMap("descriptor", edgeDescMap); + +writer.addEdgeMap("weight", weightMap); +writer.addEdgeMap("label", labelMap); +\endcode + +With \c addNode() and \c addEdge() functions you can point out Nodes and +Edges in the graph. By example, you can write out the source and target +of the graph. + +\code +writer.addNode("source", sourceNode); +writer.addNode("target", targetNode); + +writer.addEdge("observed", edge); +\endcode + +After you give all write commands you must call the \c run() member +function, what execute all the write commands. + +\code +writer.run(); +\endcode + +\subsection reading Reading a graph + +The given file format may contain many maps and outpointed nodes or edges. +If you read a graph you need not read all the maps and items just those +that you need. The interface of the \c GraphReader is very similar to +the GraphWriter but the reading method does not depend on the order the +given commands. + +The reader object suppose that each not readed value does not contains +whitespaces therefore it has some extra possibilities to control how could +it skip the values when the string representation contains spaces. + +\code +GraphReader reader(graph); +\endcode + +The \c addNodeMap() function reads a map from the \c \@nodeset section. +If there is a map what you do not want to read from the file and there is +whitespace in the string represenation of the values then you should +call the \c skipNodeMap() template member function with proper parameters. + +\see QuotedStringReader +\code +reader.addNodeMap("x-coord", xCoordMap); +reader.addNodeMap("y-coord", yCoordMap); + +reader.addNodeMap("label", labelMap); +reader.skipNodeMap("description"); + +reader.addNodeMap("color", colorMap); +\endcode + +With the \c addEdgeMap() member function you can give an edge map +reading command similar to the NodeMaps. + +\code +reader.addEdgeMap("weight", weightMap); +reader.addEdgeMap("label", labelMap); +\endcode + +With \c addNode() and \c addEdge() functions you can read outpointed Nodes and +Edges. + +\code +reader.addNode("source", sourceNode); +reader.addNode("target", targetNode); + +reader.addEdge("observed", edge); +\endcode + +After you give all read commands you must call the \c run() member +function, what execute all the commands. + +\code +reader.run(); +\endcode + +\section types The background of the Reading and Writing +The \c GraphReader should know how can read a Value from the given map. +By the default implementation the input operator reads a value from +the stream and the type of the readed value is the value type of the given map. +When the reader should skip a value in the stream, because you do not +want to store it in map, the reader skips a character sequence without +whitespace. + +If you want to change the functionality of the reader, you can use +template parameters to specialize it. When you give a reading +command for a map you can give a Reader type as template parameter. +With this template parameter you can control how does read the Reader +a value from the stream. + +The reader has the next structure: +\code +struct TypeReader { + typedef TypeName Value; + + void read(std::istream& is, Value& value); +}; +\endcode + +By example, the \c "strings" nodemap contains strings and you do not need +the value of the string just the length. Then you can implement own Reader +struct. + +\code +struct LengthReader { + typedef int Value; + + void read(std::istream& is, Value& value) { + std::string tmp; + is >> tmp; + value = tmp.length(); + } +}; +... +reader.addNodeMap("strings", lengthMap); +\endcode + +The global functionality of the reader class can be changed by giving a +special template parameter for the GraphReader class. In default way the +template parameter the \c DefaultReaderTraits. A reader traits class +should provide an inner template class Reader for each type, and an +DefaultReader for skipping a value. + +The specialization of the writing should be very similar to the reading. + + +*/