Context Navigation

Back to Ticket #35

Ticket #35: lgf-page.patch

File lgf-page.patch, 16.9 KB (added by Alpar Juttner, 17 years ago)
To be applied on the top of lgf_doc.patch

new file doc/lgf.dox

# HG changeset patch
# User Alpar Juttner <alpar@cs.elte.hu>
# Date 1210833006 -3600
# Node ID 8965fe652c0c4df1cc32aebd264497f6c8c86f35
# Parent  a765b4ecbcdbd5e8ac0fc55beecf585ebb481b15
LGF doc goes into a separate page + several fixes in lgf doc

diff --git a/doc/lgf.dox b/doc/lgf.dox
new file mode 100644

-                      -
+/* -*- C++ -*-
+ *
+ * This file is a part of LEMON, a generic C++ optimization library
+ *
+ * Copyright (C) 2003-2008
+ * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
+ * (Egervary Research Group on Combinatorial Optimization, EGRES).
+ *
+ * Permission to use, modify and distribute this software is granted
+ * provided that this copyright notice appears in all copies. For
+ * precise terms see the accompanying LICENSE file.
+ *
+ * This software is provided "AS IS" with no warranty of any kind,
+ * express or implied, and with no claim as to its suitability for any
+ * purpose.
+ *
+ */
+namespace lemon {
+/*!
+\page lgf-format Lemon Graph Format (LGF)
+The \e LGF is a <em>column oriented</em>
+file format for storing graphs and associated data like
+node and edge maps.
+Each line with \c '#' first non-whitespace
+character is considered as a comment line.
+Otherwise the file consists of sections starting with
+a header line. The header lines starts with an \c '@' character followed by the
+type of section. The standard section types are \c \@nodes, \c
+\@arcs and \c \@edges
+and \@attributes. Each header line may also have an optional
+\e name, which can be use to distinguish the sections of the same
+type.
+The standard sections are column oriented, each line consists of
+<em>token</em>s separated by whitespaces. A token can be \e plain or
+\e quoted. A plain token is just a sequence of non-whitespace characters,
+while a quoted token is a
+character sequence surrounded by double quotes, and it can also
+contain whitespaces and escape sequences.
+The \c \@nodes section describes a set of nodes and associated
+maps. The first is a header line, it columns are the names of the
+maps appearing in the following lines.
+One of the maps must be called \c
+"label", which plays special role in the file.
+The following
+non-empty lines until the next section describes nodes of the
+graph. Each line contains the values of the node maps
+associated to the current node.
+\code
+ @nodes
+ label   coordinates size    title
+       (10,20)     10      "First node"
+       (80,80)     8       "Second node"
+       (40,10)     10      "Third node"
+\endcode
+The \c \@arcs section is very similar to the \c \@nodes section,
+it again starts with a header line describing the names of the arc,
+but the \c "label" map is not obligatory here. The following lines
+describe the arcs. The first two tokens of each line are
+the source and the target node of the arc, respectively, then come the map
+values. The source and target tokens must be node labels.
+\code
+ @arcs
+              capacity
+   2   16
+   3   12
+   3   18
+\endcode
+The \c \@edges is just a synonym of \c \@arcs.
+The \c \@attributes section contains key-value pairs, each line
+consists of two tokens, an attribute name, and then an attribute value.
+\code
+ @attributes
+ source 1
+ target 3
+ caption "LEMON test digraph"
+\endcode
+*/
+}
+//  LocalWords:  whitespace whitespaces

lemon/lgf_reader.h

diff --git a/lemon/lgf_reader.h b/lemon/lgf_reader.h

-                      a
   ///
   /// \brief LGF reader for directed graphs
   ///
+  /// The \e LGF (LEMON graph file) format is the default file format
+  /// of the LEMON library. It is a text based, section oriented
+  /// format, which defines some standard sections for storing graphs
+  /// in text files. Each line with \c '#' first non-whitespace
+  /// character is considered as a comment line. Each section starts with
+  /// a header line, these lines starts with \c '@' character and the
+  /// name of section type.  The standard sections are \c \@nodes, \c
+  /// \@arcs and \c \@edges (these two names are completely equivalent)
+  /// and \@attributes. Each header line may also have an optional
+  /// name, which can be use to distinguish the sections of the same
+  /// type.
+  /// This utility reads an \ref lgf-format "LGF" file.
   ///
+  /// The \@nodes section describes a set of nodes and associated
+  /// maps. The first is a header line consisting of the names of the
+  /// maps, each of them is a plain or quoted token. A plain token is
+  /// a sequence of non-whitespace characters, and a quoted token is a
+  /// character sequence surrounded by double quotes, and the sequence
+  /// may contain escape sequences. One of the maps must be called \c
+  /// "label", which plays special role in the file.  Each following
+  /// non-empty line until the next section describes a node in the
+  /// graph. These lines contain the values of the node maps
+  /// associated to the current node, each value is also plain or
+  /// quoted token.
+  ///
+  /// The \c \@arcs section is very similar to the \c \@nodes section,
+  /// it starts with a header line consists from the names of the arc
+  /// maps, the \c "label" map is also necessary. The following lines
+  /// contain the description of the arcs. The first two tokens are
+  /// the source and the target node of the edge, then comes the map
+  /// values. The source and target tokens must be node labels.
+  ///
+  /// The \c \@attributes section contains key-value pairs, each line
+  /// starts with an attribute nome, and then an attribute value. Both
+  /// of them are plain or quoted tokens, but the value could be also
+  /// a node or an arc label.
+  /// The reading method does a batch processing. The user creates a
+  /// reader object, then various reading rules can be added to the
+  /// reader, and eventually the reading is executed with the \c run()
+  /// member function. A map reading rule can be added to the reader
+  /// with the \c nodeMap() or \c arcMap() members. An optional
+  /// converter parameter can also be added as a standard functor converting from
+  /// std::string to the value type of the map. If it is set, it will
+  /// determine how the tokens in the file should be is converted to the map's
+  /// value type. If the functor is not set, then a default conversion
+  /// will be used. One map can be read into multiple map objects at the
+  /// same time. The \c attribute(), \c node() and \c arc() functions
+  /// are used to add attribute reading rules.
   ///
   ///\code
+  /// @nodes
+  /// label   coordinates size    title
+  /// 1       (10,20)     10      "First node"
+  /// 2       (80,80)     8       "Second node"
+  /// 3       (40,10)     10      "Third node"
+  /// @arcs
+  ///         capacity
+  /// 1   2   16
+  /// 1   3   12
+  /// 2   3   18
+  /// @attributes
+  /// source 1
+  /// target 3
+  /// caption "LEMON test digraph"
+  ///\endcode
+  ///
+  /// The writing method does a batch processing. The user creates a
+  /// writer object, then several writing rules can be added to the
+  /// writer, and eventually the writing is executed with the \c run()
+  /// member function. A map writing rule can be added to the writer
+  /// with the \c nodeMap() or \c arcMap() members. The optional
+  /// converter parameter can be a standard functor, which converts an
+  /// the value type of the map to std::string, if it is set, it
+  /// determines how the the map's value type is written to the output
+  /// stream. If the functor is not set, then a default conversion
+  /// will be used. The \c attribute(), \c node() and \c arc() functions
+  /// are used to add attribute writing rules.
+  ///
+  ///\code
+  ///     DigraphWriter<Digraph>(std::cout, digraph).
+  ///     DigraphReader<Digraph>(std::cin, digraph).
   ///       nodeMap("coordinates", coord_map).
-  ///       nodeMap("size", size).
-  ///       nodeMap("title", title).
   ///       arcMap("capacity", cap_map).
   ///       node("source", src).
   ///       node("target", trg).
 …
   ///       run();
   ///\endcode
   ///
   /// By default the writer uses the first section in the file of the
+  /// By default the reader uses the first section in the file of the
   /// proper type. If a section has an optional name, then it can be
+  /// selected to write with the \c nodes(), \c arcs() or \c attributes()
+  /// selected for reading by giving an optional name parameter to
+  /// the \c nodes(), \c arcs() or \c attributes()
   /// functions.
   ///
   /// The \c useNodes() and \c useArcs() functions are used to specify
   /// that the nodes or arcs should not be constructed(added to the
   /// graph) during the reading, the argument of these functions is a
   /// node map or arc map determining the label map for the items. An
   /// application of these function is the multipass reading, which is
   /// important if two \e \@arcs sections should be read from the
   /// file. In this example the first phase reads the node set and one
   /// of the arc set, while the second phase will read the second arc
   /// set into an \e ArcSet class (\c SmartArcSet or \c ListArcSet),
   /// the previously read label node map should be given to the \c
   /// useNodes() functions. An other multipass application is reading
   /// paths into a node map or an arc map. It is impossible in
   /// single pass, because the arcs are not constructed when the node
+  /// The \c useNodes() and \c useArcs() functions are used to tell the reader
+  /// that the nodes or arcs should not be constructed (added to the
+  /// graph) during the reading, but instead the label map of the items
+  /// are given as a parameter of these functions. An
+  /// application of these function is multipass reading, which is
+  /// important if two \e \@arcs sections must be read from the
+  /// file. In this example the first phase would read the node set and one
+  /// of the arc sets, while the second phase would read the second arc
+  /// set into an \e ArcSet class (\c SmartArcSet or \c ListArcSet).
+  /// the previously read label node map should be passed to the \c
+  /// useNodes() functions. Another application of multipass reading when
+  /// paths are given as a node map or an arc map. It is impossible read this in
+  /// a single pass, because the arcs are not constructed when the node
   /// maps are read.
   template <typename _Digraph>
   class DigraphReader {
 …
     /// \brief Copy constructor
     ///
     /// The copy constructor transfers all data from the other reader,
     /// therefore the copied reader will not be useable more.
+    /// therefore the copied reader will not be usable more.
     DigraphReader(DigraphReader& other)
       : _is(other._is), local_is(other.local_is), _digraph(other._digraph),
         _use_nodes(other._use_nodes), _use_arcs(other._use_arcs) {

lemon/lgf_writer.h

diff --git a/lemon/lgf_writer.h b/lemon/lgf_writer.h

-                      a
   ///
   /// \brief LGF writer for directed graphs
   ///
+  /// The \e LGF (LEMON graph file) format is the default file format
+  /// of the LEMON library. It is a text based, section oriented
+  /// format, which defines some standard sections for storing graphs
+  /// in text files. Each line with \c '#' first non-whitespace
+  /// character is considered as a comment line. Each section starts with
+  /// a header line, these lines starts with \c '@' character and the
+  /// name of section type.  The standard sections are \c \@nodes, \c
+  /// \@arcs and \c \@edges (these two names are completely equivalent)
+  /// and \@attributes. Each header line may also have an optional
+  /// name, which can be use to distinguish the sections of the same
+  /// type.
+  /// This utility writes an \ref lgf-format "LGF" file.
   ///
+  /// The \@nodes section describes a set of nodes and associated
+  /// maps. The first is a header line consisting of the names of the
+  /// maps, each of them is a plain or quoted token. A plain token is
+  /// a sequence of non-whitespace characters, and a quoted token is a
+  /// character sequence surrounded by double quotes, and the sequence
+  /// may contain escape sequences. One of the maps must be called \c
+  /// "label", which plays special role in the file.  Each following
+  /// non-empty line until the next section describes a node in the
+  /// graph. These lines contain the values of the node maps
+  /// associated to the current node, each value is also plain or
+  /// quoted token.
+  ///
+  /// The \c \@arcs section is very similar to the \c \@nodes section,
+  /// it starts with a header line consists from the names of the arc
+  /// maps, the \c "label" map is also necessary. The following lines
+  /// contain the description of the arcs. The first two tokens are
+  /// the source and the target node of the edge, then comes the map
+  /// values. The source and target tokens must be node labels.
+  ///
+  /// The \c \@attributes section contains key-value pairs, each line
+  /// starts with an attribute nome, and then an attribute value. Both
+  /// of them are plain or quoted tokens, but the value could be also
+  /// a node or an arc label.
+  /// The writing method does a batch processing. The user creates a
+  /// writer object, then various writing rules can be added to the
+  /// writer, and eventually the writing is executed with the \c run()
+  /// member function. A map writing rule can be added to the writer
+  /// with the \c nodeMap() or \c arcMap() members. An optional
+  /// converter parameter can also be added as a standard functor converting from
+  /// the value type of the map to std::string. If it is set, it will
+  /// determine how the map's value type is written to the output
+  /// stream. If the functor is not set, then a default conversion
+  /// will be used. The \c attribute(), \c node() and \c arc() functions
+  /// are used to add attribute writing rules.
   ///
   ///\code
+  /// @nodes
+  /// label   coordinates size    title
+  /// 1       (10,20)     10      "First node"
+  /// 2       (80,80)     8       "Second node"
+  /// 3       (40,10)     10      "Third node"
+  /// @arcs
+  ///         capacity
+  /// 1   2   16
+  /// 1   3   12
+  /// 2   3   18
+  /// @attributes
+  /// source 1
+  /// target 3
+  /// caption "LEMON test digraph"
+  ///\endcode
+  ///
+  /// The reading method does a batch processing. The user creates a
+  /// writer object, then several reading rules can be added to the
+  /// writer, and eventually the reading is executed with the \c run()
+  /// member function. A map reading rule can be added to the writer
+  /// with the \c nodeMap() or \c arcMap() members. The optional
+  /// converter parameter can be a standard functor, which converts an
+  /// std::string to the value type of the map, if it is set, it
+  /// determines how the read string literal is converted to the map's
+  /// value type. If the functor is not set, then a default conversion
+  /// will be used. One map can be read in multiple map objects at the
+  /// same time. The \c attribute(), \c node() and \c arc() functions
+  /// are used to add attribute reading rules.
+  ///
+  ///\code
+  ///     DigraphWriter<Digraph>(std::cin, digraph).
+  ///     DigraphWriter<Digraph>(std::cout, digraph).
   ///       nodeMap("coordinates", coord_map).
+  ///       nodeMap("size", size).
+  ///       nodeMap("title", title).
   ///       arcMap("capacity", cap_map).
   ///       node("source", src).
   ///       node("target", trg).
 …
   ///       run();
   ///\endcode
   ///
+  /// By default the writer does not write additional captions to the
+  /// section, but they can added with the \c nodes(), \c arcs() or \c
+  ///
+  /// By default, the writer does not write additional captions to the
+  /// sections, but they can be give as an optional parameter of
+  /// the \c nodes(), \c arcs() or \c
   /// attributes() functions.
   ///
   /// The \c skipNodes() and \c skipArcs() functions forbid the
   /// writing of the sections. If two arc sections should write to the
   /// output, it can be made in two passes, the first pass writes the
+  /// writing of the sections. If two arc sections should be written to the
+  /// output, it can be done in two passes, the first pass writes the
   /// node section and the first arc section, then the second pass
   /// skips the node section and writes just the arc section to the
   /// stream. The output stream can be retrieved with the \c ostream()
   /// function, hence the second pass can append the output of the
+  /// function, hence the second pass can append its output to the output of the
   /// first pass.
   template <typename _Digraph>
   class DigraphWriter {
 …
     /// \brief Copy constructor
     ///
     /// The copy constructor transfers all data from the other writer,
     /// therefore the copied writer will not be useable more.
+    /// therefore the copied writer will not be usable more.
     DigraphWriter(DigraphWriter& other)
       : _os(other._os), local_os(other.local_os), _digraph(other._digraph),
         _skip_nodes(other._skip_nodes), _skip_arcs(other._skip_arcs) {

Download in other formats:

Original Format