[Lemon-commits] Alpar Juttner: More flexible header names in .lg...
Lemon HG
hg at lemon.cs.elte.hu
Sat May 17 07:34:38 CEST 2008
details: http://lemon.cs.elte.hu/hg/lemon/rev/e561aa7675de
changeset: 156:e561aa7675de
user: Alpar Juttner <alpar [at] cs.elte.hu>
date: Sat May 17 06:30:02 2008 +0100
description:
More flexible header names in .lgf + largely improved doc
diffstat:
5 files changed, 387 insertions(+), 100 deletions(-)
doc/Makefile.am | 1
doc/groups.dox | 19 ----
doc/lgf.dox | 96 +++++++++++++++++++++++
lemon/lgf_reader.h | 210 ++++++++++++++++++++++++++++++++++++++--------------
lemon/lgf_writer.h | 161 +++++++++++++++++++++++++++++++++------
diffs (truncated from 908 to 300 lines):
diff -r 5c3604513ed0 -r e561aa7675de doc/Makefile.am
--- a/doc/Makefile.am Mon May 05 11:41:30 2008 +0200
+++ b/doc/Makefile.am Sat May 17 06:30:02 2008 +0100
@@ -3,6 +3,7 @@
doc/coding_style.dox \
doc/dirs.dox \
doc/groups.dox \
+ doc/lgf.dox \
doc/license.dox \
doc/mainpage.dox \
doc/namespaces.dox \
diff -r 5c3604513ed0 -r e561aa7675de doc/groups.dox
--- a/doc/groups.dox Mon May 05 11:41:30 2008 +0200
+++ b/doc/groups.dox Sat May 17 06:30:02 2008 +0100
@@ -483,25 +483,6 @@
*/
/**
- at defgroup section_io Section readers and writers
- at ingroup lemon_io
-\brief Section readers and writers for LEMON Input-Output.
-
-This group describes section reader and writer classes that can be
-attached to \ref LemonReader and \ref LemonWriter.
-*/
-
-/**
- at defgroup item_io Item readers and writers
- at ingroup lemon_io
-\brief Item readers and writers for LEMON Input-Output.
-
-This group describes reader and writer classes for various data types
-(e.g. map or attribute values). These classes can be attached to
-\ref LemonReader and \ref LemonWriter.
-*/
-
-/**
@defgroup eps_io Postscript exporting
@ingroup io_group
\brief General \c EPS drawer and graph exporter
diff -r 5c3604513ed0 -r e561aa7675de doc/lgf.dox
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/lgf.dox Sat May 17 06:30:02 2008 +0100
@@ -0,0 +1,96 @@
+/* -*- 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
diff -r 5c3604513ed0 -r e561aa7675de lemon/lgf_reader.h
--- a/lemon/lgf_reader.h Mon May 05 11:41:30 2008 +0200
+++ b/lemon/lgf_reader.h Sat May 17 06:30:02 2008 +0100
@@ -268,35 +268,58 @@
str = os.str();
return is;
}
-
- std::istream& readIdentifier(std::istream& is, std::string& str) {
- std::ostringstream os;
-
- char c;
- is >> std::ws;
-
- if (!is.get(c))
- return is;
-
- if (!isIdentifierFirstChar(c))
- throw DataFormatError("Wrong char in identifier");
-
- os << c;
-
- while (is.get(c) && !isWhiteSpace(c)) {
- if (!isIdentifierChar(c))
- throw DataFormatError("Wrong char in identifier");
- os << c;
- }
- if (!is) is.clear();
-
- str = os.str();
- return is;
- }
}
-
- /// \e
+
+ /// \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.
template <typename _Digraph>
class DigraphReader {
public:
@@ -341,23 +364,34 @@
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 usable 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) {
@@ -377,7 +411,7 @@
_attributes_caption = other._attributes_caption;
}
- /// \e
+ /// \brief Destructor
~DigraphReader() {
for (typename NodeMaps::iterator it = _node_maps.begin();
it != _node_maps.end(); ++it) {
@@ -406,7 +440,12 @@
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>();
@@ -416,7 +455,10 @@
return *this;
}
- /// \e
+ /// \brief Node map reading rule
+ ///
More information about the Lemon-commits
mailing list