RhodeCode

/* -*- 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

 1       (10,20)     10      "First node"

 2       (80,80)     8       "Second node"

 3       (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

 1   2   16

 1   3   12

 2   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

	doc/lgf.dox \

  /// \ingroup lemon_io

  ///  

  /// \brief LGF reader for directed graphs

  ///

  /// This utility reads an \ref lgf-format "LGF" file.

  ///

  /// 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

  ///     DigraphReader<Digraph>(std::cin, digraph).

  ///       nodeMap("coordinates", coord_map).

  ///       arcMap("capacity", cap_map).

  ///       node("source", src).

  ///       node("target", trg).

  ///       attribute("caption", caption).

  ///       run();

  ///\endcode

  ///

  /// 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 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 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.

    /// \brief Constructor

    ///

    /// Construct a directed graph reader, which reads from the given

    /// input stream.

    /// \brief Constructor

    ///

    /// Construct a directed graph reader, which reads from the given

    /// file.

    /// \brief Constructor

    ///

    /// Construct a directed graph reader, which reads from the given

    /// file.

    /// \brief Copy constructor

    ///

    /// The copy constructor transfers all data from the other reader,

    /// therefore the copied reader will not be usable more. 

    /// \brief Destructor

    /// \name Reading rules

    /// @{

    /// \brief Node map reading rule

    ///

    /// Add a node map reading rule to the reader.

    /// \brief Node map reading rule

    ///

    /// Add a node map reading rule with specialized converter to the

    /// reader.

    /// \brief Arc map reading rule

    ///

    /// Add an arc map reading rule to the reader.

    /// \brief Arc map reading rule

    ///

    /// Add an arc map reading rule with specialized converter to the

    /// reader.

    /// \brief Attribute reading rule

    ///

    /// Add an attribute reading rule to the reader.

    /// \brief Attribute reading rule

    ///

    /// Add an attribute reading rule with specialized converter to the

    /// reader.

    /// \brief Node reading rule

    ///

    /// Add a node reading rule to reader.

    /// \brief Arc reading rule

    ///

    /// Add an arc reading rule to reader.

    /// @}

    /// \name Select section by name

    /// @{

    /// \brief Set \c \@nodes section to be read

    ///

    /// Set \c \@nodes section to be read

    /// \brief Set \c \@arcs section to be read

    ///

    /// Set \c \@arcs section to be read

    /// \brief Set \c \@attributes section to be read

    ///

    /// Set \c \@attributes section to be read

    /// @}

    /// \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.

    /// \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.

    /// \brief Use previously constructed arc set

    ///

    /// Use previously constructed arc set, and specify the arc

    /// label map.

    /// \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.

    /// @}

	while (_reader_bits::readToken(line, map)) {

	while (_reader_bits::readToken(line, map)) {

	if (!_reader_bits::readToken(line, attr))

    /// \name Execution of the reader    

    /// @{

    /// \brief Start the batch processing

    ///

    /// This function starts the batch processing

	  _reader_bits::readToken(line, section);

	  _reader_bits::readToken(line, caption);

    /// @}

  /// \relates DigraphReader

  /// \relates DigraphReader

  /// \relates DigraphReader

      if (str.empty() || str[0] == '@') return true;

  /// \ingroup lemon_io

  ///  

  /// \brief LGF writer for directed graphs

  ///

  /// This utility writes an \ref lgf-format "LGF" file.

  ///

  /// 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

  ///     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).

  ///       attribute("caption", caption).

  ///       run();

  ///\endcode

  ///

  ///

  /// 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 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 its output to the output of the

  /// first pass.

    /// \brief Constructor

    ///

    /// Construct a directed graph writer, which writes to the given

    /// output stream.

    /// \brief Constructor

    ///

    /// Construct a directed graph writer, which writes to the given

    /// output file.

    /// \brief Constructor

    ///

    /// Construct a directed graph writer, which writes to the given

    /// output file.

    /// \brief Copy constructor

    ///

    /// The copy constructor transfers all data from the other writer,

    /// therefore the copied writer will not be usable more. 

    /// \brief Destructor

    /// \name Writing rules

    /// @{

    /// \brief Node map reading rule

    ///

    /// Add a node map reading rule to the writer.

    /// \brief Node map writing rule

    ///

    /// Add a node map writing rule with specialized converter to the

    /// writer.

    /// \brief Arc map writing rule

    ///

    /// Add an arc map writing rule to the writer.

    /// \brief Arc map writing rule

    ///

    /// Add an arc map writing rule with specialized converter to the

    /// writer.

    /// \brief Attribute writing rule

    ///

    /// Add an attribute writing rule to the writer.

    /// \brief Attribute writing rule

    ///

    /// Add an attribute writing rule with specialized converter to the

    /// writer.

    /// \brief Node writing rule

    ///

    /// Add a node writing rule to the writer.

    /// \brief Arc writing rule

    ///

    /// Add an arc writing rule to writer.

    /// \name Select section by name

    /// @{

    /// \brief Set \c \@nodes section to be read

    ///

    /// Set \c \@nodes section to be read

    /// \brief Set \c \@arcs section to be read

    ///

    /// Set \c \@arcs section to be read

    /// \brief Set \c \@attributes section to be read

    ///

    /// Set \c \@attributes section to be read

    /// \name Skipping section

    /// @{

    /// \brief Skip writing the node set

    ///

    /// The \c \@nodes section will be not written to the stream.

    /// \brief Skip writing arc set

    ///

    /// The \c \@arcs section will be not written to the stream.

    /// @}

	_writer_bits::writeToken(*_os << ' ', _nodes_caption);

	_writer_bits::writeToken(*_os, it->first) << '\t';

	_writer_bits::writeToken(*_os << ' ', _arcs_caption);

	_writer_bits::writeToken(*_os, it->first) << '\t';

	_writer_bits::writeToken(*_os << ' ', _attributes_caption);

	_writer_bits::writeToken(*_os, it->first) << ' ';

    /// \name Execution of the writer    

    /// @{

    /// \brief Start the batch processing

    ///

    /// This function starts the batch processing

    /// \brief Gives back the stream of the writer

    ///

    /// Gives back the stream of the writer

    std::ostream& ostream() {

    /// @}

  /// \relates DigraphWriter

  /// \relates DigraphWriter

  /// \relates DigraphWriter