[Lemon-commits] [lemon_svn] deba: r2023 - hugo/trunk/doc

[Lemon SVN]

Author: deba
Date: Mon Jul  4 17:03:25 2005
New Revision: 2023

Modified:
   hugo/trunk/doc/graph_io.dox

Log:
Updated but not complete doc for IO.



Modified: hugo/trunk/doc/graph_io.dox
==============================================================================
--- hugo/trunk/doc/graph_io.dox	(original)
+++ hugo/trunk/doc/graph_io.dox	Mon Jul  4 17:03:25 2005
@@ -9,12 +9,13 @@
 
 \section format The general file format
 
-The file contains at most four sections in the following order:
+The file contains sections in the following order:
 
 \li nodeset
 \li edgeset
 \li nodes
 \li edges
+\li attributes
 
 The nodeset section starts with the following line:
 
@@ -78,6 +79,22 @@
 The file may contain empty lines and comment lines. The comment lines
 start with an \c # character.
 
+The attributes section can handle some information about the graph. It
+contains in each line an key and the mapped value to key. The key should
+be a string without whitespace, the value can be from various type.
+
+\code
+ at attributes
+title "Four colored plan graph"
+author "Balazs DEZSO"
+copyright "Lemon Library"
+version 12
+\endcode
+
+\code
+ at end
+\endcode
+=======
 The file ends with the 
 
 <tt> \@end </tt>
@@ -141,6 +158,13 @@
 writer.writeEdge("observed", edge);
 \endcode
 
+With \c writeAttribute() function you can write an attribute to the file.
+
+\code
+writer.writeAttribute("author", "Balazs DEZSO");
+writer.writeAttribute("version", 12);
+\endcode
+
 After you give all write commands you must call the \c run() member
 function, which executes all the writing commands.
 
@@ -199,6 +223,15 @@
 reader.readEdge("observed", edge);
 \endcode
 
+With \c readAttribute() function you can read an attribute from the file.
+
+\code
+std::string author;
+writer.readAttribute("author", author);
+int version;
+writer.writeAttribute("version", version);
+\endcode
+
 After you give all read commands you must call the \c run() member
 function, which executes all the commands.
 
@@ -256,6 +289,151 @@
 
 The specialization of  writing should be very similar to that of reading.
 
+\section undir Undir graphs
+
+In the undir graph format there is an \c undiredgeset section instead of
+the \c edgeset section. The first line of the section describes the 
+undirected egdes' names and all next lines describes one undirected edge
+with the the incident nodes and the values of the map.
+
+The format handles the directed edge maps as a syntactical sugar, if there
+is two map which names are the same with a \c '+' and a \c '-' prefix
+then it can be read as an directed map.
+
+\code
+ at undiredgeset
+             id    capacity +flow -flow
+32   2       1     4.3      2.0	  0.0
+21   21      5     2.6      0.0   2.6
+21   12      8     3.4      0.0   0.0
+\endcode
+
+The \c edges section changed to \c undiredges section. This section
+describes labeled edges and undirected edges. The directed edge label
+should start with a \c '+' and a \c '-' prefix what decide the direction
+of the edge. 
+
+\code
+ at undiredges
+undiredge 1
++edge 5
+-back 5
+\endcode
+
+There are similar classes to the \c GraphReader ans \c GraphWriter
+which handle the undirected graphs. These classes are the 
+\c UndirGraphReader and \UndirGraphWriter.
+
+The \c readUndirMap() function reads an undirected map and the
+\c readUndirEdge() reads an undirected edge from the file, 
+
+\code
+reader.readUndirEdgeMap("capacity", capacityMap);
+reader.readEdgeMap("flow", flowMap);
+...
+reader.readUndirEdge("undir_edge", undir_edge);
+reader.readEdge("edge", edge);
+\endcode
+
+\section advanced Advanced features
+
+The graph reader and writer classes gives an easy way to read and write
+graphs. But sometimes we want more advanced features. This way we can
+use the more general lemon reader and writer interface.
+
+The lemon format is an section oriented file format. It contains one or
+more section, each starts with a line with \c \@ first character.
+The content of the section this way cannot contain line with \c \@ first
+character. The file may contains comment lines with \c # first character.
+
+The \c LemonReader and \c LemonWriter gives a framework to read and
+write sections. There are various section reader and section writer
+classes which can be attached to a \c LemonReader or a \c LemonWriter.
+
+There are default section readers and writers for reading and writing
+item sets, and labeled items in the graph. These reads and writes
+the format described above. Other type of data can be handled with own
+section reader and writer classes which are inherited from the
+\c LemonReader::SectionReader or the \c LemonWriter::SectionWriter classes.
+
+The next example defines a special section reader which reads the
+\c \@description sections into a string:
+
+\code 
+class DescriptionReader : LemonReader::SectionReader {
+protected:
+  virtual bool header(const std::string& line) {
+    std::istringstream ls(line);
+    std::string head;
+    ls >> head;
+    return head == "@description";
+  }
+
+  virtual void read(std::istream& is) {
+    std::string line;
+    while (getline(is, line)) {
+      desc += line;
+    }
+  }
+public:
+
+  typedef LemonReader::SectionReader Parent;
+  
+  DescriptionReader(LemonReader& reader) : Parent(reader) {}
+
+  const std::string& description() const {
+    return description;
+  }
+
+private:
+  std::string desc;
+};
+\endcode
+
+The other advanced stuff of the generalized file format is that 
+multiple edgesets can be stored to the same nodeset. It can be used 
+by example as a network traffic matrix.
+
+In example there is a network with symmetric links and there are assymetric
+traffic request on the network. This construction can be stored in an
+undirected graph and in an directed NewEdgeSetAdaptor class. The example
+shows the input with the LemonReader class:
+
+\code
+UndirListGraph network;
+UndirListGraph::UndirEdgeSet<double> capacity;
+NewEdgeSetAdaptor<UndirListGraph> traffic(network);
+NewEdgeSetAdaptor<UndirListGraph>::EdgeSet<double> request(network);
+
+LemonReader reader(std::cin);
+NodeSetReader nodesetReader(reader, network);
+UndirEdgeSetReader undirEdgesetReader(reader, network, nodesetReader);
+undirEdgesetReader.readEdgeMap("capacity", capacity);
+EdgeSetReader edgesetReader(reader, traffic, nodesetReader);
+edgesetReader.readEdgeMap("request", request);
+
+reader.run();
+\endcode
+
+Because the GraphReader and the UndirGraphReader can be converted
+to LemonReader and it can resolve the ID's of the items, the previous
+result can be achived with the UndirGraphReader class also.
+
+
+\code
+UndirListGraph network;
+UndirListGraph::UndirEdgeSet<double> capacity;
+NewEdgeSetAdaptor<UndirListGraph> traffic(network);
+NewEdgeSetAdaptor<UndirListGraph>::EdgeSet<double> request(network);
+
+UndirGraphReader reader(std::cin, network);
+reader.readEdgeMap("capacity", capacity);
+EdgeSetReader edgesetReader(reader, traffic, reader);
+edgesetReader.readEdgeMap("request", request);
+
+reader.run();
+\endcode
+
 \author Balazs Dezso
 */
 }