COIN-OR::LEMON - Graph Library

Changeset 156:e561aa7675de in lemon-1.2


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

Files:
1 added
4 edited

Legend:

Unmodified
Added
Removed
  • doc/Makefile.am

    r154 r156  
    44        doc/dirs.dox \
    55        doc/groups.dox \
     6        doc/lgf.dox \
    67        doc/license.dox \
    78        doc/mainpage.dox \
  • doc/groups.dox

    r83 r156  
    484484
    485485/**
    486 @defgroup section_io Section readers and writers
    487 @ingroup lemon_io
    488 \brief Section readers and writers for LEMON Input-Output.
    489 
    490 This group describes section reader and writer classes that can be
    491 attached to \ref LemonReader and \ref LemonWriter.
    492 */
    493 
    494 /**
    495 @defgroup item_io Item readers and writers
    496 @ingroup lemon_io
    497 \brief Item readers and writers for LEMON Input-Output.
    498 
    499 This group describes reader and writer classes for various data types
    500 (e.g. map or attribute values). These classes can be attached to
    501 \ref LemonReader and \ref LemonWriter.
    502 */
    503 
    504 /**
    505486@defgroup eps_io Postscript exporting
    506487@ingroup io_group
  • 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.