COIN-OR::LEMON - Graph Library

Changeset 156:e561aa7675de in lemon-main for lemon/lgf_reader.h


Ignore:
Timestamp:
05/17/08 07:30:02 (17 years ago)
Author:
Alpar Juttner <alpar@…>
Branch:
default
Phase:
public
Message:

More flexible header names in .lgf + largely improved doc

File:
1 edited

Legend:

Unmodified
Added
Removed
  • lemon/lgf_reader.h

    r148 r156  
    269269      return is;
    270270    }
    271 
    272     std::istream& readIdentifier(std::istream& is, std::string& str) {
    273       std::ostringstream os;
    274 
    275       char c;
    276       is >> std::ws;
    277      
    278       if (!is.get(c))
    279         return is;
    280 
    281       if (!isIdentifierFirstChar(c))
    282         throw DataFormatError("Wrong char in identifier");
    283      
    284       os << c;
    285      
    286       while (is.get(c) && !isWhiteSpace(c)) {
    287         if (!isIdentifierChar(c))
    288           throw DataFormatError("Wrong char in identifier");     
    289         os << c;
    290       }
    291       if (!is) is.clear();
    292      
    293       str = os.str();
    294       return is;
    295     }
    296271   
    297272  }
    298  
    299   /// \e
     273
     274  /// \ingroup lemon_io
     275  /// 
     276  /// \brief LGF reader for directed graphs
     277  ///
     278  /// This utility reads an \ref lgf-format "LGF" file.
     279  ///
     280  /// The reading method does a batch processing. The user creates a
     281  /// reader object, then various reading rules can be added to the
     282  /// reader, and eventually the reading is executed with the \c run()
     283  /// member function. A map reading rule can be added to the reader
     284  /// with the \c nodeMap() or \c arcMap() members. An optional
     285  /// converter parameter can also be added as a standard functor converting from
     286  /// std::string to the value type of the map. If it is set, it will
     287  /// determine how the tokens in the file should be is converted to the map's
     288  /// value type. If the functor is not set, then a default conversion
     289  /// will be used. One map can be read into multiple map objects at the
     290  /// same time. The \c attribute(), \c node() and \c arc() functions
     291  /// are used to add attribute reading rules.
     292  ///
     293  ///\code
     294  ///     DigraphReader<Digraph>(std::cin, digraph).
     295  ///       nodeMap("coordinates", coord_map).
     296  ///       arcMap("capacity", cap_map).
     297  ///       node("source", src).
     298  ///       node("target", trg).
     299  ///       attribute("caption", caption).
     300  ///       run();
     301  ///\endcode
     302  ///
     303  /// By default the reader uses the first section in the file of the
     304  /// proper type. If a section has an optional name, then it can be
     305  /// selected for reading by giving an optional name parameter to
     306  /// the \c nodes(), \c arcs() or \c attributes()
     307  /// functions.
     308  ///
     309  /// The \c useNodes() and \c useArcs() functions are used to tell the reader
     310  /// that the nodes or arcs should not be constructed (added to the
     311  /// graph) during the reading, but instead the label map of the items
     312  /// are given as a parameter of these functions. An
     313  /// application of these function is multipass reading, which is
     314  /// important if two \e \@arcs sections must be read from the
     315  /// file. In this example the first phase would read the node set and one
     316  /// of the arc sets, while the second phase would read the second arc
     317  /// set into an \e ArcSet class (\c SmartArcSet or \c ListArcSet).
     318  /// The previously read label node map should be passed to the \c
     319  /// useNodes() functions. Another application of multipass reading when
     320  /// paths are given as a node map or an arc map. It is impossible read this in
     321  /// a single pass, because the arcs are not constructed when the node
     322  /// maps are read.
    300323  template <typename _Digraph>
    301324  class DigraphReader {
     
    342365  public:
    343366
    344     /// \e
     367    /// \brief Constructor
     368    ///
     369    /// Construct a directed graph reader, which reads from the given
     370    /// input stream.
    345371    DigraphReader(std::istream& is, Digraph& digraph)
    346372      : _is(&is), local_is(false), _digraph(digraph),
    347373        _use_nodes(false), _use_arcs(false) {}
    348374
    349     /// \e
     375    /// \brief Constructor
     376    ///
     377    /// Construct a directed graph reader, which reads from the given
     378    /// file.
    350379    DigraphReader(const std::string& fn, Digraph& digraph)
    351380      : _is(new std::ifstream(fn.c_str())), local_is(true), _digraph(digraph),
    352381        _use_nodes(false), _use_arcs(false) {}
    353 
    354 
    355     /// \e
     382   
     383    /// \brief Constructor
     384    ///
     385    /// Construct a directed graph reader, which reads from the given
     386    /// file.
    356387    DigraphReader(const char* fn, Digraph& digraph)
    357388      : _is(new std::ifstream(fn)), local_is(true), _digraph(digraph),
    358389        _use_nodes(false), _use_arcs(false) {}
    359390
    360     /// \e
     391    /// \brief Copy constructor
     392    ///
     393    /// The copy constructor transfers all data from the other reader,
     394    /// therefore the copied reader will not be usable more.
    361395    DigraphReader(DigraphReader& other)
    362396      : _is(other._is), local_is(other.local_is), _digraph(other._digraph),
     
    378412    }
    379413
    380     /// \e
     414    /// \brief Destructor
    381415    ~DigraphReader() {
    382416      for (typename NodeMaps::iterator it = _node_maps.begin();
     
    407441  public:
    408442
    409     /// \e
     443    /// \name Reading rules
     444    /// @{
     445   
     446    /// \brief Node map reading rule
     447    ///
     448    /// Add a node map reading rule to the reader.
    410449    template <typename Map>
    411450    DigraphReader& nodeMap(const std::string& caption, Map& map) {
     
    417456    }
    418457
    419     /// \e
     458    /// \brief Node map reading rule
     459    ///
     460    /// Add a node map reading rule with specialized converter to the
     461    /// reader.
    420462    template <typename Map, typename Converter>
    421463    DigraphReader& nodeMap(const std::string& caption, Map& map,
     
    428470    }
    429471
    430     /// \e
     472    /// \brief Arc map reading rule
     473    ///
     474    /// Add an arc map reading rule to the reader.
    431475    template <typename Map>
    432476    DigraphReader& arcMap(const std::string& caption, Map& map) {
     
    438482    }
    439483
    440     /// \e
     484    /// \brief Arc map reading rule
     485    ///
     486    /// Add an arc map reading rule with specialized converter to the
     487    /// reader.
    441488    template <typename Map, typename Converter>
    442489    DigraphReader& arcMap(const std::string& caption, Map& map,
     
    449496    }
    450497
    451     /// \e
     498    /// \brief Attribute reading rule
     499    ///
     500    /// Add an attribute reading rule to the reader.
    452501    template <typename Value>
    453502    DigraphReader& attribute(const std::string& caption, Value& value) {
     
    458507    }
    459508
    460     /// \e
     509    /// \brief Attribute reading rule
     510    ///
     511    /// Add an attribute reading rule with specialized converter to the
     512    /// reader.
    461513    template <typename Value, typename Converter>
    462514    DigraphReader& attribute(const std::string& caption, Value& value,
     
    468520    }
    469521
    470     /// \e
     522    /// \brief Node reading rule
     523    ///
     524    /// Add a node reading rule to reader.
    471525    DigraphReader& node(const std::string& caption, Node& node) {
    472526      typedef _reader_bits::MapLookUpConverter<Node> Converter;
     
    478532    }
    479533
    480     /// \e
     534    /// \brief Arc reading rule
     535    ///
     536    /// Add an arc reading rule to reader.
    481537    DigraphReader& arc(const std::string& caption, Arc& arc) {
    482538      typedef _reader_bits::MapLookUpConverter<Arc> Converter;
     
    488544    }
    489545
    490     /// \e
     546    /// @}
     547
     548    /// \name Select section by name
     549    /// @{
     550
     551    /// \brief Set \c \@nodes section to be read
     552    ///
     553    /// Set \c \@nodes section to be read
    491554    DigraphReader& nodes(const std::string& caption) {
    492555      _nodes_caption = caption;
     
    494557    }
    495558
    496     /// \e
     559    /// \brief Set \c \@arcs section to be read
     560    ///
     561    /// Set \c \@arcs section to be read
    497562    DigraphReader& arcs(const std::string& caption) {
    498563      _arcs_caption = caption;
     
    500565    }
    501566
    502     /// \e
     567    /// \brief Set \c \@attributes section to be read
     568    ///
     569    /// Set \c \@attributes section to be read
    503570    DigraphReader& attributes(const std::string& caption) {
    504571      _attributes_caption = caption;
     
    506573    }
    507574
    508     /// \e
     575    /// @}
     576
     577    /// \name Using previously constructed node or arc set
     578    /// @{
     579
     580    /// \brief Use previously constructed node set
     581    ///
     582    /// Use previously constructed node set, and specify the node
     583    /// label map.
    509584    template <typename Map>
    510585    DigraphReader& useNodes(const Map& map) {
     
    519594    }
    520595
    521     /// \e
     596    /// \brief Use previously constructed node set
     597    ///
     598    /// Use previously constructed node set, and specify the node
     599    /// label map and a functor which converts the label map values to
     600    /// std::string.
    522601    template <typename Map, typename Converter>
    523602    DigraphReader& useNodes(const Map& map,
     
    532611    }
    533612
    534     /// \e
     613    /// \brief Use previously constructed arc set
     614    ///
     615    /// Use previously constructed arc set, and specify the arc
     616    /// label map.
    535617    template <typename Map>
    536618    DigraphReader& useArcs(const Map& map) {
     
    545627    }
    546628
    547     /// \e
     629    /// \brief Use previously constructed arc set
     630    ///
     631    /// Use previously constructed arc set, and specify the arc
     632    /// label map and a functor which converts the label map values to
     633    /// std::string.
    548634    template <typename Map, typename Converter>
    549635    DigraphReader& useArcs(const Map& map,
     
    558644    }
    559645
     646    /// @}
     647
    560648  private:
    561649
     
    598686        std::string map;
    599687        int index = 0;
    600         while (_reader_bits::readIdentifier(line, map)) {
     688        while (_reader_bits::readToken(line, map)) {
    601689          if (maps.find(map) != maps.end()) {
    602690            std::ostringstream msg;
     
    681769        std::string map;
    682770        int index = 0;
    683         while (_reader_bits::readIdentifier(line, map)) {
     771        while (_reader_bits::readToken(line, map)) {
    684772          if (maps.find(map) != maps.end()) {
    685773            std::ostringstream msg;
     
    788876       
    789877        std::string attr, token;
    790         if (!_reader_bits::readIdentifier(line, attr))
     878        if (!_reader_bits::readToken(line, attr))
    791879          throw DataFormatError("Attribute name not found");
    792880        if (!_reader_bits::readToken(line, token))
     
    828916
    829917  public:
    830    
    831     /// \e
     918
     919    /// \name Execution of the reader   
     920    /// @{
     921
     922    /// \brief Start the batch processing
     923    ///
     924    /// This function starts the batch processing
    832925    void run() {
    833926     
     
    847940          std::string section, caption;
    848941          line >> c;
    849           _reader_bits::readIdentifier(line, section);
    850           _reader_bits::readIdentifier(line, caption);
     942          _reader_bits::readToken(line, section);
     943          _reader_bits::readToken(line, caption);
    851944
    852945          if (line >> c)
     
    892985
    893986    }
     987
     988    /// @}
    894989   
    895990  };
    896991
     992  /// \relates DigraphReader
    897993  template <typename Digraph>
    898994  DigraphReader<Digraph> digraphReader(std::istream& is, Digraph& digraph) {
     
    900996  }
    901997
     998  /// \relates DigraphReader
    902999  template <typename Digraph>
    9031000  DigraphReader<Digraph> digraphReader(const std::string& fn,
     
    9061003  }
    9071004
     1005  /// \relates DigraphReader
    9081006  template <typename Digraph>
    9091007  DigraphReader<Digraph> digraphReader(const char* fn, Digraph& digraph) {
Note: See TracChangeset for help on using the changeset viewer.