[Lemon-commits] [lemon_svn] deba: r1513 - hugo/trunk/doc
Lemon SVN
svn at lemon.cs.elte.hu
Mon Nov 6 20:45:58 CET 2006
Author: deba
Date: Tue Feb 1 16:51:22 2005
New Revision: 1513
Added:
hugo/trunk/doc/graph_io.dox
Modified:
hugo/trunk/doc/Doxyfile
Log:
Tutorial for graph input - output
Modified: hugo/trunk/doc/Doxyfile
==============================================================================
--- hugo/trunk/doc/Doxyfile (original)
+++ hugo/trunk/doc/Doxyfile Tue Feb 1 16:51:22 2005
@@ -454,6 +454,7 @@
namespaces.dox \
license.dox \
developpers_interface.dox \
+ graph_io.dox \
../src/lemon \
../src/lemon/concept \
../src/test/test_tools.h
Added: hugo/trunk/doc/graph_io.dox
==============================================================================
--- (empty file)
+++ hugo/trunk/doc/graph_io.dox Tue Feb 1 16:51:22 2005
@@ -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
+ at 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
+ at 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
+ at 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
+ at 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
+ at 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<ListGraph> 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<ListGraph, Node> 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<ListGraph, Edge, ListGraph::EdgeMap<int> > 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<ListGraph> 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<QuotedStringReader>("label", labelMap);
+reader.skipNodeMap<QuotedStringReader>("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<LengthReader>("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.
+
+
+*/
More information about the Lemon-commits
mailing list