Context Navigation

Back to Ticket #35

Ticket #35: digraph_reader_doc.patch

File digraph_reader_doc.patch, 12.8 KB (added by Balazs Dezso, 17 years ago)

lemon/lgf_reader.h

# HG changeset patch
# User Balazs Dezso <deba@inf.elte.hu>
# Date 1210511869 -7200
# Node ID f6b69e8d7fa38c99540c7affa9ecf6572d473d16
# Parent  5c3604513ed0256e35e5fd50c54cd0e37362397e
Documentation for DigraphReader

diff -r 5c3604513ed0 -r f6b69e8d7fa3 lemon/lgf_reader.h

-                      a
+    }
+  }
+  /// \e
+  /// \ingroup lemon_io
+  ///
+  /// \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 are denoted as 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 or \c \@edges (these two names are completely equivalent)
+  /// and \@attributes. Each header lines could contain an optional
+  /// name, which can be use to distinguish the sections of the same
+  /// type.
+  ///
+  /// The \@nodes section stores node maps for a node set. The first
+  /// line comprises from the names of the maps, these map names are
+  /// sequences of non-whitespace characters. One of the maps should
+  /// be called \c "label", which plays specific role in the file.
+  /// Each following non-empty line, until a line starting with \c '@'
+  /// character, describes a node in the graph. These lines contain
+  /// the values of the node maps associated to the current node. The
+  /// values are plain or quoted tokens, a plain token is a sequence
+  /// of a non-whitespace characters. A quoted token is a character
+  /// sequence surrounded by double quotes, and the sequence could
+  /// contain several escape sequences.
+  ///
+  /// The \c \@arcs or \c \@edges section is very similar to the \c
+  /// \@nodes section, it starts with a 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, but before
+  /// the map values the line comprises the source and target of the
+  /// arc, these tokens should be occured in the \c \@nodes section as
+  /// a node label.
+  ///
+  /// The \c \@attrbiutes section contains key-value pairs, each line
+  /// starts with an attribute name, and then an attribute value. The
+  /// name is a sequence of non-whitespace characters, while the value
+  /// is plain or quoted string literal. The value could be a node or
+  /// arc label.
+  ///
+  ///\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 is organized as batch processing. The user
+  /// creates a reader object, then several reading rules can be added
+  /// to the reader, and finally executes the reading with the \c
+  /// run() member function. A map reading rule can be added to the
+  /// reader 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 the
+  /// default method will perform this task. One map could be read in
+  /// multiple map objects, if more reading rule is used with the same
+  /// map name. The \c attribute(), \c node() and \c arc() functions
+  /// can be used to add attribute reading rules.
+  ///
+  ///\code
+  ///     DigraphReader<Digraph>(std::cin, digraph).
+  ///       nodeMap("coordinates", coord_map).
+  ///       arcMap("capacity", cap_map).
+  ///       node("source", src).
+  ///       node("target", trg).
+  ///       attribute("caption", caption).
+  ///       run();
+  ///\endcode
+  ///
+  /// In the default behaviour the reader uses the first section in
+  /// the file of the proper type. If a section has an optional name,
+  /// then it can be select to read with the \c nodes(), \c arcs() or
+  /// \c attributes() functions.
+  ///
+  /// The \c useNodes() and \c useArcs() functions can be used to
+  /// specify that the nodes or arcs should not be constructed during
+  /// the reading, the argument of these functions is a node map or
+  /// arc map, which determines the label map for the items. One
+  /// application of these member is the multipass reading, which is a
+  /// very important approach in the LEMON IO, because several tasks
+  /// are solveable just with this technic. If two \e \@arcs should be
+  /// read from the file (for example transport matrix), then it could
+  /// be made with two phases. The first phase reads the node set and
+  /// one of the arc set, and it should read the label column to a
+  /// map. The second phase could 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 path into
+  /// node map or arc map. It is impossible in singlepass, because the
+  /// arcs are not constructed yet, when the node maps are read.
   template <typename _Digraph>
   class DigraphReader {
   public:
 …
   public:
+    /// \e
+    /// \brief Constructor
+    ///
+    /// Construct a directed graph reader, which reads from the given
+    /// input stream.
     DigraphReader(std::istream& is, Digraph& digraph)
       : _is(&is), local_is(false), _digraph(digraph),
         _use_nodes(false), _use_arcs(false) {}
+    /// \e
+    /// \brief Constructor
+    ///
+    /// Construct a directed graph reader, which reads from the given
+    /// file.
     DigraphReader(const std::string& fn, Digraph& digraph)
       : _is(new std::ifstream(fn.c_str())), local_is(true), _digraph(digraph),
         _use_nodes(false), _use_arcs(false) {}
+    /// \e
+    /// \brief Constructor
+    ///
+    /// Construct a directed graph reader, which reads from the given
+    /// file.
     DigraphReader(const char* fn, Digraph& digraph)
       : _is(new std::ifstream(fn)), local_is(true), _digraph(digraph),
         _use_nodes(false), _use_arcs(false) {}
+    /// \e
+    /// \brief Copy constructor
+    ///
+    /// The copy constructor transfers all data from the other reader,
+    /// therefore the copied reader will not be useable 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) {
 …
       _attributes_caption = other._attributes_caption;
+    }
     /// \e
+    /// \brief Destructor
     ~DigraphReader() {
       for (typename NodeMaps::iterator it = _node_maps.begin();
            it != _node_maps.end(); ++it) {
 …
   public:
+    /// \e
+    /// \name Reading rules
+    /// @{
+    /// \brief Node map reading rule
+    ///
+    /// Add a node map reading rule to the reader.
     template <typename Map>
     DigraphReader& nodeMap(const std::string& caption, Map& map) {
       checkConcept<concepts::WriteMap<Node, typename Map::Value>, Map>();
 …
       return *this;
+    }
+    /// \e
+    /// \brief Node map reading rule
+    ///
+    /// Add a node map reading rule with specialized converter to the
+    /// reader.
     template <typename Map, typename Converter>
     DigraphReader& nodeMap(const std::string& caption, Map& map,
                            const Converter& converter = Converter()) {
 …
       return *this;
+    }
+    /// \e
+    /// \brief Arc map reading rule
+    ///
+    /// Add an arc map reading rule to the reader.
     template <typename Map>
     DigraphReader& arcMap(const std::string& caption, Map& map) {
       checkConcept<concepts::WriteMap<Arc, typename Map::Value>, Map>();
 …
       return *this;
+    }
+    /// \e
+    /// \brief Arc map reading rule
+    ///
+    /// Add an arc map reading rule with specialized converter to the
+    /// reader.
     template <typename Map, typename Converter>
     DigraphReader& arcMap(const std::string& caption, Map& map,
                           const Converter& converter = Converter()) {
 …
       return *this;
+    }
+    /// \e
+    /// \brief Attribute reading rule
+    ///
+    /// Add an attribute reading rule to the reader.
     template <typename Value>
     DigraphReader& attribute(const std::string& caption, Value& value) {
       _reader_bits::ValueStorageBase* storage =
 …
       return *this;
+    }
+    /// \e
+    /// \brief Attribute reading rule
+    ///
+    /// Add an attribute reading rule with specialized converter to the
+    /// reader.
     template <typename Value, typename Converter>
     DigraphReader& attribute(const std::string& caption, Value& value,
                              const Converter& converter = Converter()) {
 …
       return *this;
+    }
+    /// \e
+    /// \brief Node reading rule
+    ///
+    /// Add a node reading rule with specialized converter to the
+    /// reader.
     DigraphReader& node(const std::string& caption, Node& node) {
       typedef _reader_bits::MapLookUpConverter<Node> Converter;
       Converter converter(_node_index);
 …
       return *this;
+    }
+    /// \e
+    /// \brief Arc reading rule
+    ///
+    /// Add an arc reading rule with specialized converter to the
+    /// reader.
     DigraphReader& arc(const std::string& caption, Arc& arc) {
       typedef _reader_bits::MapLookUpConverter<Arc> Converter;
       Converter converter(_arc_index);
 …
       return *this;
+    }
+    /// \e
+    /// @}
+    /// \name Select section by name
+    /// @{
+    /// \brief Set \c \@nodes section to be read
+    ///
+    /// Set \c \@nodes section to be read
     DigraphReader& nodes(const std::string& caption) {
       _nodes_caption = caption;
       return *this;
+    }
+    /// \e
+    /// \brief Set \c \@arcs section to be read
+    ///
+    /// Set \c \@arcs section to be read
     DigraphReader& arcs(const std::string& caption) {
       _arcs_caption = caption;
       return *this;
+    }
+    /// \e
+    /// \brief Set \c \@attributes section to be read
+    ///
+    /// Set \c \@attributes section to be read
     DigraphReader& attributes(const std::string& caption) {
       _attributes_caption = caption;
       return *this;
+    }
+    /// \e
+    /// @}
+    /// \name Using previously constructed node or arc set
+    /// @{
+    /// \brief Use previously constructed node set
+    ///
+    /// Use previously constructed node set, and specify the node
+    /// label map.
     template <typename Map>
     DigraphReader& useNodes(const Map& map) {
       checkConcept<concepts::ReadMap<Node, typename Map::Value>, Map>();
 …
       return *this;
+    }
+    /// \e
+    /// \brief Use previously constructed node set
+    ///
+    /// Use previously constructed node set, and specify the node
+    /// label map and a functor which converts the label map values to
+    /// std::string.
     template <typename Map, typename Converter>
     DigraphReader& useNodes(const Map& map,
                             const Converter& converter = Converter()) {
 …
       return *this;
+    }
+    /// \e
+    /// \brief Use previously constructed arc set
+    ///
+    /// Use previously constructed arc set, and specify the arc
+    /// label map.
     template <typename Map>
     DigraphReader& useArcs(const Map& map) {
       checkConcept<concepts::ReadMap<Arc, typename Map::Value>, Map>();
 …
       return *this;
+    }
+    /// \e
+    /// \brief Use previously constructed arc set
+    ///
+    /// Use previously constructed arc set, and specify the arc
+    /// label map and a functor which converts the label map values to
+    /// std::string.
     template <typename Map, typename Converter>
     DigraphReader& useArcs(const Map& map,
                             const Converter& converter = Converter()) {
 …
+      }
       return *this;
+    }
+    /// @}
   private:
 …
+    }
   public:
+    /// \e
+    /// \name Execution of the reader
+    /// @{
+    /// \brief Start the batch processing
+    ///
+    /// This function starts the batch processing
     void run() {
       LEMON_ASSERT(_is != 0, "This reader assigned to an other reader");
 …
+      }
+    }
+    /// @}
   };

Download in other formats:

Original Format