COIN-OR::LEMON - Graph Library

Changeset 156:e561aa7675de in lemon for lemon


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

More flexible header names in .lgf + largely improved doc

Location:
lemon
Files:
2 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) {
  • lemon/lgf_writer.h

    r148 r156  
    205205
    206206    bool requireEscape(const std::string& str) {
     207      if (str.empty() || str[0] == '@') return true;
    207208      std::istringstream is(str);
    208209      char c;
     
    232233  }
    233234 
    234   /// \e
     235  /// \ingroup lemon_io
     236  /// 
     237  /// \brief LGF writer for directed graphs
     238  ///
     239  /// This utility writes an \ref lgf-format "LGF" file.
     240  ///
     241  /// The writing method does a batch processing. The user creates a
     242  /// writer object, then various writing rules can be added to the
     243  /// writer, and eventually the writing is executed with the \c run()
     244  /// member function. A map writing rule can be added to the writer
     245  /// with the \c nodeMap() or \c arcMap() members. An optional
     246  /// converter parameter can also be added as a standard functor converting from
     247  /// the value type of the map to std::string. If it is set, it will
     248  /// determine how the map's value type is written to the output
     249  /// stream. If the functor is not set, then a default conversion
     250  /// will be used. The \c attribute(), \c node() and \c arc() functions
     251  /// are used to add attribute writing rules.
     252  ///
     253  ///\code
     254  ///     DigraphWriter<Digraph>(std::cout, digraph).
     255  ///       nodeMap("coordinates", coord_map).
     256  ///       nodeMap("size", size).
     257  ///       nodeMap("title", title).
     258  ///       arcMap("capacity", cap_map).
     259  ///       node("source", src).
     260  ///       node("target", trg).
     261  ///       attribute("caption", caption).
     262  ///       run();
     263  ///\endcode
     264  ///
     265  ///
     266  /// By default, the writer does not write additional captions to the
     267  /// sections, but they can be give as an optional parameter of
     268  /// the \c nodes(), \c arcs() or \c
     269  /// attributes() functions.
     270  ///
     271  /// The \c skipNodes() and \c skipArcs() functions forbid the
     272  /// writing of the sections. If two arc sections should be written to the
     273  /// output, it can be done in two passes, the first pass writes the
     274  /// node section and the first arc section, then the second pass
     275  /// skips the node section and writes just the arc section to the
     276  /// stream. The output stream can be retrieved with the \c ostream()
     277  /// function, hence the second pass can append its output to the output of the
     278  /// first pass.
    235279  template <typename _Digraph>
    236280  class DigraphWriter {
     
    274318  public:
    275319
    276     /// \e
     320    /// \brief Constructor
     321    ///
     322    /// Construct a directed graph writer, which writes to the given
     323    /// output stream.
    277324    DigraphWriter(std::ostream& is, Digraph& digraph)
    278325      : _os(&is), local_os(false), _digraph(digraph),
    279326        _skip_nodes(false), _skip_arcs(false) {}
    280327
    281     /// \e
     328    /// \brief Constructor
     329    ///
     330    /// Construct a directed graph writer, which writes to the given
     331    /// output file.
    282332    DigraphWriter(const std::string& fn, Digraph& digraph)
    283333      : _os(new std::ofstream(fn.c_str())), local_os(true), _digraph(digraph),
    284334        _skip_nodes(false), _skip_arcs(false) {}
    285335
    286     /// \e
     336    /// \brief Constructor
     337    ///
     338    /// Construct a directed graph writer, which writes to the given
     339    /// output file.
    287340    DigraphWriter(const char* fn, Digraph& digraph)
    288341      : _os(new std::ofstream(fn)), local_os(true), _digraph(digraph),
    289342        _skip_nodes(false), _skip_arcs(false) {}
    290343
     344    /// \brief Copy constructor
     345    ///
     346    /// The copy constructor transfers all data from the other writer,
     347    /// therefore the copied writer will not be usable more.
    291348    DigraphWriter(DigraphWriter& other)
    292349      : _os(other._os), local_os(other.local_os), _digraph(other._digraph),
     
    308365    }
    309366
    310     /// \e
     367    /// \brief Destructor
    311368    ~DigraphWriter() {
    312369      for (typename NodeMaps::iterator it = _node_maps.begin();
     
    336393  public:
    337394
    338     /// \e
     395    /// \name Writing rules
     396    /// @{
     397   
     398    /// \brief Node map reading rule
     399    ///
     400    /// Add a node map reading rule to the writer.
    339401    template <typename Map>
    340402    DigraphWriter& nodeMap(const std::string& caption, const Map& map) {
     
    346408    }
    347409
    348     /// \e
     410    /// \brief Node map writing rule
     411    ///
     412    /// Add a node map writing rule with specialized converter to the
     413    /// writer.
    349414    template <typename Map, typename Converter>
    350415    DigraphWriter& nodeMap(const std::string& caption, const Map& map,
     
    357422    }
    358423
    359     /// \e
     424    /// \brief Arc map writing rule
     425    ///
     426    /// Add an arc map writing rule to the writer.
    360427    template <typename Map>
    361428    DigraphWriter& arcMap(const std::string& caption, const Map& map) {
     
    367434    }
    368435
    369     /// \e
     436    /// \brief Arc map writing rule
     437    ///
     438    /// Add an arc map writing rule with specialized converter to the
     439    /// writer.
    370440    template <typename Map, typename Converter>
    371441    DigraphWriter& arcMap(const std::string& caption, const Map& map,
     
    378448    }
    379449
    380     /// \e
     450    /// \brief Attribute writing rule
     451    ///
     452    /// Add an attribute writing rule to the writer.
    381453    template <typename Value>
    382454    DigraphWriter& attribute(const std::string& caption, const Value& value) {
     
    387459    }
    388460
    389     /// \e
     461    /// \brief Attribute writing rule
     462    ///
     463    /// Add an attribute writing rule with specialized converter to the
     464    /// writer.
    390465    template <typename Value, typename Converter>
    391466    DigraphWriter& attribute(const std::string& caption, const Value& value,
     
    397472    }
    398473
    399     /// \e
     474    /// \brief Node writing rule
     475    ///
     476    /// Add a node writing rule to the writer.
    400477    DigraphWriter& node(const std::string& caption, const Node& node) {
    401478      typedef _writer_bits::MapLookUpConverter<Node> Converter;
     
    407484    }
    408485
    409     /// \e
     486    /// \brief Arc writing rule
     487    ///
     488    /// Add an arc writing rule to writer.
    410489    DigraphWriter& arc(const std::string& caption, const Arc& arc) {
    411490      typedef _writer_bits::MapLookUpConverter<Arc> Converter;
     
    417496    }
    418497
    419     /// \e
     498    /// \name Select section by name
     499    /// @{
     500
     501    /// \brief Set \c \@nodes section to be read
     502    ///
     503    /// Set \c \@nodes section to be read
    420504    DigraphWriter& nodes(const std::string& caption) {
    421505      _nodes_caption = caption;
     
    423507    }
    424508
    425     /// \e
     509    /// \brief Set \c \@arcs section to be read
     510    ///
     511    /// Set \c \@arcs section to be read
    426512    DigraphWriter& arcs(const std::string& caption) {
    427513      _arcs_caption = caption;
     
    429515    }
    430516
    431     /// \e
     517    /// \brief Set \c \@attributes section to be read
     518    ///
     519    /// Set \c \@attributes section to be read
    432520    DigraphWriter& attributes(const std::string& caption) {
    433521      _attributes_caption = caption;
     
    435523    }
    436524
     525    /// \name Skipping section
     526    /// @{
     527
     528    /// \brief Skip writing the node set
     529    ///
     530    /// The \c \@nodes section will be not written to the stream.
    437531    DigraphWriter& skipNodes() {
    438532      LEMON_ASSERT(!_skip_nodes, "Multiple usage of skipNodes() member");
     
    440534    }
    441535
     536    /// \brief Skip writing arc set
     537    ///
     538    /// The \c \@arcs section will be not written to the stream.
    442539    DigraphWriter& skipArcs() {
    443540      LEMON_ASSERT(!_skip_arcs, "Multiple usage of skipArcs() member");
    444541      return *this;
    445542    }
     543
     544    /// @}
    446545
    447546  private:
     
    459558      *_os << "@nodes";
    460559      if (!_nodes_caption.empty()) {
    461         *_os << ' ' << _nodes_caption;
     560        _writer_bits::writeToken(*_os << ' ', _nodes_caption);
    462561      }
    463562      *_os << std::endl;
     
    468567      for (typename NodeMaps::iterator it = _node_maps.begin();
    469568           it != _node_maps.end(); ++it) {
    470         *_os << it->first << '\t';
     569        _writer_bits::writeToken(*_os, it->first) << '\t';
    471570      }
    472571      *_os << std::endl;
     
    519618      *_os << "@arcs";
    520619      if (!_arcs_caption.empty()) {
    521         *_os << ' ' << _arcs_caption;
     620        _writer_bits::writeToken(*_os << ' ', _arcs_caption);
    522621      }
    523622      *_os << std::endl;
     
    529628      for (typename ArcMaps::iterator it = _arc_maps.begin();
    530629           it != _arc_maps.end(); ++it) {
    531         *_os << it->first << '\t';
     630        _writer_bits::writeToken(*_os, it->first) << '\t';
    532631      }
    533632      *_os << std::endl;
     
    578677      *_os << "@attributes";
    579678      if (!_attributes_caption.empty()) {
    580         *_os << ' ' << _attributes_caption;
     679        _writer_bits::writeToken(*_os << ' ', _attributes_caption);
    581680      }
    582681      *_os << std::endl;
    583682      for (typename Attributes::iterator it = _attributes.begin();
    584683           it != _attributes.end(); ++it) {
    585         *_os << it->first << ' ';
     684        _writer_bits::writeToken(*_os, it->first) << ' ';
    586685        _writer_bits::writeToken(*_os, it->second->get());
    587686        *_os << std::endl;
     
    591690  public:
    592691   
    593     /// \e
     692    /// \name Execution of the writer   
     693    /// @{
     694
     695    /// \brief Start the batch processing
     696    ///
     697    /// This function starts the batch processing
    594698    void run() {
    595699      if (!_skip_nodes) {
     
    602706    }
    603707
    604     /// \e
    605     std::ostream& stream() {
     708    /// \brief Gives back the stream of the writer
     709    ///
     710    /// Gives back the stream of the writer
     711    std::ostream& ostream() {
    606712      return *_os;
    607713    }
     714
     715    /// @}
    608716  };
    609717
     718  /// \relates DigraphWriter
    610719  template <typename Digraph>
    611720  DigraphWriter<Digraph> digraphWriter(std::istream& is, Digraph& digraph) {
     
    613722  }
    614723
     724  /// \relates DigraphWriter
    615725  template <typename Digraph>
    616726  DigraphWriter<Digraph> digraphWriter(const std::string& fn,
     
    619729  }
    620730
     731  /// \relates DigraphWriter
    621732  template <typename Digraph>
    622733  DigraphWriter<Digraph> digraphWriter(const char* fn, Digraph& digraph) {
Note: See TracChangeset for help on using the changeset viewer.