# HG changeset patch
# User deba
# Date 1120489405 0
# Node ID aa7428d22aafa4e52503621d26b8dadbd04e600d
# Parent a3b20dd847b5dc309f74979ce72c95dbc890fde7
Updated but not complete doc for IO.
diff -r a3b20dd847b5 -r aa7428d22aaf doc/graph_io.dox
--- a/doc/graph_io.dox Mon Jul 04 13:10:34 2005 +0000
+++ b/doc/graph_io.dox Mon Jul 04 15:03:25 2005 +0000
@@ -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
+@attributes
+title "Four colored plan graph"
+author "Balazs DEZSO"
+copyright "Lemon Library"
+version 12
+\endcode
+
+\code
+@end
+\endcode
+=======
The file ends with the
\@end
@@ -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
+@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
+@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 capacity;
+NewEdgeSetAdaptor traffic(network);
+NewEdgeSetAdaptor::EdgeSet 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 capacity;
+NewEdgeSetAdaptor traffic(network);
+NewEdgeSetAdaptor::EdgeSet 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
*/
}