RhodeCode

/* -*- mode: C++; indent-tabs-mode: nil; -*-

 *

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

 *

 */

#ifndef LEMON_ERROR_H

#define LEMON_ERROR_H

/// \ingroup exceptions

/// \file

/// \brief Basic exception classes and error handling.

#include <exception>

#include <string>

#include <sstream>

#include <iostream>

#include <cstdlib>

#include <memory>

namespace lemon {

  /// \addtogroup exceptions

  /// @{

  /// \brief Generic exception class.

  ///

  /// Base class for exceptions used in LEMON.

  ///

  class Exception : public std::exception {

  public:

    virtual ~Exception() throw() {}

    virtual const char* what() const throw() {

      return "lemon::Exception";

    }

  };

  /// \brief Input-Output error

  ///

  /// This exception is thrown when a file operation cannot be

  /// succeeded.

  class IoError : public Exception {

  protected:

    std::string _message;

    std::string _file;

    mutable std::string _what;

  public:

    /// Copy constructor

      message(error._message);

      file(error._file);

    }

    /// Constructor

      IoError::message(message);

    }

    /// Constructor

      IoError::message(message);

    }

    /// Constructor

      IoError::message(message);

      IoError::file(file);

    }

    /// Constructor

      IoError::message(message);

      IoError::file(file);

    }

    /// Virtual destructor

    virtual ~IoError() throw() {}

    /// Set the error message

      try {

        _message = message;

      } catch (...) {}

    }

    /// Set the error message

      try {

        _message = message;

      } catch (...) {}

    }

    /// Set the file name

      try {

        _file = file;

      } catch (...) {}

    }

    /// Returns the error message

      return _message;

    }

    /// \brief Returns the filename

    ///

      return _file;

    }

    /// \brief Returns a short error message

    ///

    virtual const char* what() const throw() {

      try {

        _what.clear();

        std::ostringstream oss;

        oss << "lemon:IoError" << ": ";

        }

        _what = oss.str();

      }

      catch (...) {}

      if (!_what.empty()) return _what.c_str();

      else return "lemon:IoError";

    }

  };

  /// \brief Format error

  ///

  class FormatError : public Exception {

  protected:

    std::string _message;

    std::string _file;

    int _line;

    mutable std::string _what;

  public:

    /// Copy constructor

      message(error._message);

      file(error._file);

      line(error._line);

    }

    /// Constructor

      FormatError::message(message);

      _line = 0;

    }

    /// Constructor

      FormatError::message(message);

      _line = 0;

    }

    /// Constructor

      FormatError::message(message);

      FormatError::file(file);

      FormatError::line(line);

    }

    /// Constructor

      FormatError::message(message);

      FormatError::file(file);

      FormatError::line(line);

    }

    /// Virtual destructor

    virtual ~FormatError() throw() {}

    /// Set the line number

    /// Set the error message

      try {

        _message = message;

      } catch (...) {}

    }

    /// Set the error message

      try {

        _message = message;

      } catch (...) {}

    }

    /// Set the file name

      try {

        _file = file;

      } catch (...) {}

    }

    /// \brief Returns the line number

    ///

    /// Returns the line number or zero if it was not specified.

    /// Returns the error message

      return _message;

    }

    /// \brief Returns the filename

    ///

      return _file;

    }

    /// \brief Returns a short error message

    ///

    /// Returns a short error message which contains the message, the

    /// file name and the line number.

    virtual const char* what() const throw() {

      try {

        _what.clear();

        std::ostringstream oss;

        oss << "lemon:FormatError" << ": ";

          oss << " (";

          oss << ")";

        }

        _what = oss.str();

      }

      catch (...) {}

      if (!_what.empty()) return _what.c_str();

      else return "lemon:FormatError";

    }

  };

  /// @}

}

#endif // LEMON_ERROR_H

  ///@{

  ///An alias for arcWidths()

  template<class X> GraphToEps<ArcWidthsTraits<X> > edgeWidths(const X &x)

  {

    return arcWidths(x);

  }

  ///An alias for arcColors()

  template<class X> GraphToEps<ArcColorsTraits<X> >

  edgeColors(const X &x)

  {

    return arcColors(x);

  }

  ///An alias for arcWidthScale()

  GraphToEps<T> &edgeWidthScale(double d) {return arcWidthScale(d);}

  ///An alias for autoArcWidthScale()

  GraphToEps<T> &autoEdgeWidthScale(bool b=true)

  {

    return autoArcWidthScale(b);

  }

  ///An alias for absoluteArcWidths()

  GraphToEps<T> &absoluteEdgeWidths(bool b=true)

  {

    return absoluteArcWidths(b);

  }

  ///An alias for parArcDist()

  GraphToEps<T> &parEdgeDist(double d) {return parArcDist(d);}

  ///An alias for hideArcs()

  GraphToEps<T> &hideEdges(bool b=true) {return hideArcs(b);}

  ///@}

};

template<class T>

const int GraphToEps<T>::INTERPOL_PREC = 20;

template<class T>

const double GraphToEps<T>::A4HEIGHT = 841.8897637795276;

template<class T>

const double GraphToEps<T>::A4WIDTH  = 595.275590551181;

template<class T>

const double GraphToEps<T>::A4BORDER = 15;

///Generates an EPS file from a graph

///\ingroup eps_io

///Generates an EPS file from a graph.

///\param g Reference to the graph to be printed.

///\param os Reference to the output stream.

///By default it is <tt>std::cout</tt>.

///

///This function also has a lot of

///\ref named-templ-func-param "named parameters",

///they are declared as the members of class \ref GraphToEps. The following

///example shows how to use these parameters.

///\code

/// graphToEps(g,os).scale(10).coords(coords)

///              .nodeScale(2).nodeSizes(sizes)

///              .arcWidthScale(.4).run();

///\endcode

///

///For more detailed examples see the \ref graph_to_eps_demo.cc demo file.

///

///\warning Don't forget to put the \ref GraphToEps::run() "run()"

///to the end of the parameter list.

///\sa GraphToEps

///\sa graphToEps(G &g, const char *file_name)

template<class G>

GraphToEps<DefaultGraphToEpsTraits<G> >

graphToEps(G &g, std::ostream& os=std::cout)

{

  return

    GraphToEps<DefaultGraphToEpsTraits<G> >(DefaultGraphToEpsTraits<G>(g,os));

}

///Generates an EPS file from a graph

///\ingroup eps_io

///This function does the same as

///\ref graphToEps(G &g,std::ostream& os)

///but it writes its output into the file \c file_name

///instead of a stream.

///\sa graphToEps(G &g, std::ostream& os)

template<class G>

GraphToEps<DefaultGraphToEpsTraits<G> >

graphToEps(G &g,const char *file_name)

{

  std::ostream* os = new std::ofstream(file_name);

  if (!(*os)) {

    delete os;

  }

  return GraphToEps<DefaultGraphToEpsTraits<G> >

    (DefaultGraphToEpsTraits<G>(g,*os,true));

}

///Generates an EPS file from a graph

///\ingroup eps_io

///This function does the same as

///\ref graphToEps(G &g,std::ostream& os)

///but it writes its output into the file \c file_name

///instead of a stream.

///\sa graphToEps(G &g, std::ostream& os)

template<class G>

GraphToEps<DefaultGraphToEpsTraits<G> >

graphToEps(G &g,const std::string& file_name)

{

  std::ostream* os = new std::ofstream(file_name.c_str());

  if (!(*os)) {

    delete os;

  }

  return GraphToEps<DefaultGraphToEpsTraits<G> >

    (DefaultGraphToEpsTraits<G>(g,*os,true));

}

} //END OF NAMESPACE LEMON

#endif // LEMON_GRAPH_TO_EPS_H

  ///\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 functions is multipass reading, which is

  /// important if two \c \@arcs sections must be read from the

  /// file. In this case 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 to read this in

  /// a single pass, because the arcs are not constructed when the node

  /// maps are read.

  template <typename _Digraph>

  class DigraphReader {

  public:

    typedef _Digraph Digraph;

    TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);

  private:

    std::istream* _is;

    bool local_is;

    std::string _filename;

    Digraph& _digraph;

    std::string _nodes_caption;

    std::string _arcs_caption;

    std::string _attributes_caption;

    typedef std::map<std::string, Node> NodeIndex;

    NodeIndex _node_index;

    typedef std::map<std::string, Arc> ArcIndex;

    ArcIndex _arc_index;

    typedef std::vector<std::pair<std::string,

      _reader_bits::MapStorageBase<Node>*> > NodeMaps;

    NodeMaps _node_maps;

    typedef std::vector<std::pair<std::string,

      _reader_bits::MapStorageBase<Arc>*> >ArcMaps;

    ArcMaps _arc_maps;

    typedef std::multimap<std::string, _reader_bits::ValueStorageBase*>

      Attributes;

    Attributes _attributes;

    bool _use_nodes;

    bool _use_arcs;

    bool _skip_nodes;

    bool _skip_arcs;

    int line_num;

    std::istringstream line;

  public:

    /// \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),

        _skip_nodes(false), _skip_arcs(false) {}

    /// \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),

        _filename(fn), _digraph(digraph),

        _use_nodes(false), _use_arcs(false),

        _skip_nodes(false), _skip_arcs(false) {

    }

    /// \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),

        _filename(fn), _digraph(digraph),

        _use_nodes(false), _use_arcs(false),

        _skip_nodes(false), _skip_arcs(false) {

    }

    /// \brief Destructor

    ~DigraphReader() {

      for (typename NodeMaps::iterator it = _node_maps.begin();

           it != _node_maps.end(); ++it) {

        delete it->second;

      }

      for (typename ArcMaps::iterator it = _arc_maps.begin();

           it != _arc_maps.end(); ++it) {

        delete it->second;

      }

      for (typename Attributes::iterator it = _attributes.begin();

           it != _attributes.end(); ++it) {

        delete it->second;

      }

      if (local_is) {

        delete _is;

      }

    }

  private:

    friend DigraphReader<Digraph> digraphReader<>(std::istream& is,

                                                  Digraph& digraph);

    friend DigraphReader<Digraph> digraphReader<>(const std::string& fn,

                                                  Digraph& digraph);

    friend DigraphReader<Digraph> digraphReader<>(const char *fn,

                                                  Digraph& digraph);

    DigraphReader(DigraphReader& other)

      : _is(other._is), local_is(other.local_is), _digraph(other._digraph),

        _use_nodes(other._use_nodes), _use_arcs(other._use_arcs),

        _skip_nodes(other._skip_nodes), _skip_arcs(other._skip_arcs) {

      other._is = 0;

      other.local_is = false;

      _node_index.swap(other._node_index);

      _arc_index.swap(other._arc_index);

      _node_maps.swap(other._node_maps);

      _arc_maps.swap(other._arc_maps);

      _attributes.swap(other._attributes);

      _nodes_caption = other._nodes_caption;

      _arcs_caption = other._arcs_caption;

      _attributes_caption = other._attributes_caption;

    }

    DigraphReader& operator=(const DigraphReader&);

  public:

    /// \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>();

      _reader_bits::MapStorageBase<Node>* storage =

        new _reader_bits::MapStorage<Node, Map>(map);

      _node_maps.push_back(std::make_pair(caption, storage));

      return *this;

    }

    /// \brief Node map reading rule

    ///

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

    /// reader.

    template <typename Map, typename Converter>

    DigraphReader& nodeMap(const std::string& caption, Map& map,

                           const Converter& converter = Converter()) {

      checkConcept<concepts::WriteMap<Node, typename Map::Value>, Map>();

      _reader_bits::MapStorageBase<Node>* storage =

        new _reader_bits::MapStorage<Node, Map, Converter>(map, converter);

      _node_maps.push_back(std::make_pair(caption, storage));

      return *this;

    }

    /// \brief Arc map reading rule

    ///

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

    template <typename Map>

    DigraphReader& arcMap(const std::string& caption, Map& map) {

      checkConcept<concepts::WriteMap<Arc, typename Map::Value>, Map>();

      _reader_bits::MapStorageBase<Arc>* storage =

        new _reader_bits::MapStorage<Arc, Map>(map);

      LEMON_ASSERT(!_use_arcs, "Multiple usage of useArcs() member");

      _use_arcs = true;

      for (ArcIt a(_digraph); a != INVALID; ++a) {

        _arc_index.insert(std::make_pair(converter(map[a]), a));

      }

      return *this;

    }

    /// \brief Skips the reading of node section

    ///

    /// Omit the reading of the node section. This implies that each node

    /// map reading rule will be abandoned, and the nodes of the graph

    /// will not be constructed, which usually cause that the arc set

    /// could not be read due to lack of node name resolving.

    /// Therefore \c skipArcs() function should also be used, or

    /// \c useNodes() should be used to specify the label of the nodes.

    DigraphReader& skipNodes() {

      LEMON_ASSERT(!_skip_nodes, "Skip nodes already set");

      _skip_nodes = true;

      return *this;

    }

    /// \brief Skips the reading of arc section

    ///

    /// Omit the reading of the arc section. This implies that each arc

    /// map reading rule will be abandoned, and the arcs of the graph

    /// will not be constructed.

    DigraphReader& skipArcs() {

      LEMON_ASSERT(!_skip_arcs, "Skip arcs already set");

      _skip_arcs = true;

      return *this;

    }

    /// @}

  private:

    bool readLine() {

      std::string str;

      while(++line_num, std::getline(*_is, str)) {

        line.clear(); line.str(str);

        char c;

        if (line >> std::ws >> c && c != '#') {

          line.putback(c);

          return true;

        }

      }

      return false;

    }

    bool readSuccess() {

      return static_cast<bool>(*_is);

    }

    void skipSection() {

      char c;

      while (readSuccess() && line >> c && c != '@') {

        readLine();

      }

      line.putback(c);

    }

    void readNodes() {

      std::vector<int> map_index(_node_maps.size());

      int map_num, label_index;

      char c;

      if (!readLine() || !(line >> c) || c == '@') {

        if (readSuccess() && line) line.putback(c);

        if (!_node_maps.empty())

          throw FormatError("Cannot find map names");

        return;

      }

      line.putback(c);

      {

        std::map<std::string, int> maps;

        std::string map;

        int index = 0;

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

          if (maps.find(map) != maps.end()) {

            std::ostringstream msg;

            msg << "Multiple occurence of node map: " << map;

            throw FormatError(msg.str());

          }

          maps.insert(std::make_pair(map, index));

          ++index;

        }

        for (int i = 0; i < static_cast<int>(_node_maps.size()); ++i) {

          std::map<std::string, int>::iterator jt =

            maps.find(_node_maps[i].first);

          if (jt == maps.end()) {

            std::ostringstream msg;

            throw FormatError(msg.str());

          }

          map_index[i] = jt->second;

        }

        {

          std::map<std::string, int>::iterator jt = maps.find("label");

          if (jt != maps.end()) {

            label_index = jt->second;

          } else {

            label_index = -1;

          }

        }

        map_num = maps.size();

      }

      while (readLine() && line >> c && c != '@') {

        line.putback(c);

        std::vector<std::string> tokens(map_num);

        for (int i = 0; i < map_num; ++i) {

          if (!_reader_bits::readToken(line, tokens[i])) {

            std::ostringstream msg;

            msg << "Column not found (" << i + 1 << ")";

            throw FormatError(msg.str());

          }

        }

        if (line >> std::ws >> c)

        Node n;

        if (!_use_nodes) {

          n = _digraph.addNode();

          if (label_index != -1)

            _node_index.insert(std::make_pair(tokens[label_index], n));

        } else {

          if (label_index == -1)

          typename std::map<std::string, Node>::iterator it =

            _node_index.find(tokens[label_index]);

          if (it == _node_index.end()) {

            std::ostringstream msg;

            msg << "Node with label not found: " << tokens[label_index];

            throw FormatError(msg.str());

          }

          n = it->second;

        }

        for (int i = 0; i < static_cast<int>(_node_maps.size()); ++i) {

          _node_maps[i].second->set(n, tokens[map_index[i]]);

        }

      }

      if (readSuccess()) {

        line.putback(c);

      }

    }

    void readArcs() {

      std::vector<int> map_index(_arc_maps.size());

      int map_num, label_index;

      char c;

      if (!readLine() || !(line >> c) || c == '@') {

        if (readSuccess() && line) line.putback(c);

        if (!_arc_maps.empty())

          throw FormatError("Cannot find map names");

        return;

      }

      line.putback(c);

      {

        std::map<std::string, int> maps;

        std::string map;

        int index = 0;

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

          if (maps.find(map) != maps.end()) {

            std::ostringstream msg;

            msg << "Multiple occurence of arc map: " << map;

            throw FormatError(msg.str());

          }

          maps.insert(std::make_pair(map, index));

          ++index;

        }

        for (int i = 0; i < static_cast<int>(_arc_maps.size()); ++i) {

          std::map<std::string, int>::iterator jt =

            maps.find(_arc_maps[i].first);

          if (jt == maps.end()) {

            std::ostringstream msg;

            throw FormatError(msg.str());

          }

          map_index[i] = jt->second;

        }

        {

          std::map<std::string, int>::iterator jt = maps.find("label");

          if (jt != maps.end()) {

            label_index = jt->second;

          } else {

            label_index = -1;

          }

        }

        map_num = maps.size();

      }

      while (readLine() && line >> c && c != '@') {

        line.putback(c);

        std::string source_token;

        std::string target_token;

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

          throw FormatError("Source not found");

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

          throw FormatError("Target not found");

        std::vector<std::string> tokens(map_num);

        for (int i = 0; i < map_num; ++i) {

          if (!_reader_bits::readToken(line, tokens[i])) {

            std::ostringstream msg;

            msg << "Column not found (" << i + 1 << ")";

            throw FormatError(msg.str());

          }

        }

        if (line >> std::ws >> c)

        Arc a;

        if (!_use_arcs) {

          typename NodeIndex::iterator it;

          it = _node_index.find(source_token);

          if (it == _node_index.end()) {

            std::ostringstream msg;

            msg << "Item not found: " << source_token;

            throw FormatError(msg.str());

          }

          Node source = it->second;

          it = _node_index.find(target_token);

          if (it == _node_index.end()) {

            std::ostringstream msg;

            msg << "Item not found: " << target_token;

            throw FormatError(msg.str());

          }

          Node target = it->second;

          a = _digraph.addArc(source, target);

          if (label_index != -1)

            _arc_index.insert(std::make_pair(tokens[label_index], a));

        } else {

          if (label_index == -1)

          typename std::map<std::string, Arc>::iterator it =

            _arc_index.find(tokens[label_index]);

          if (it == _arc_index.end()) {

            std::ostringstream msg;

            msg << "Arc with label not found: " << tokens[label_index];

            throw FormatError(msg.str());

          }

          a = it->second;

        }

        for (int i = 0; i < static_cast<int>(_arc_maps.size()); ++i) {

          _arc_maps[i].second->set(a, tokens[map_index[i]]);

        }

      }

      if (readSuccess()) {

        line.putback(c);

      }

    }

    void readAttributes() {

      std::set<std::string> read_attr;

      char c;

      while (readLine() && line >> c && c != '@') {

        line.putback(c);

        std::string attr, token;

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

          throw FormatError("Attribute name not found");

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

          throw FormatError("Attribute value not found");

        if (line >> c)

        {

          std::set<std::string>::iterator it = read_attr.find(attr);

          if (it != read_attr.end()) {

            std::ostringstream msg;

            throw FormatError(msg.str());

          }

          read_attr.insert(attr);

        }

        {

          typename Attributes::iterator it = _attributes.lower_bound(attr);

          while (it != _attributes.end() && it->first == attr) {

            it->second->set(token);

            ++it;

          }

        }

      }

      if (readSuccess()) {

        line.putback(c);

      }

      for (typename Attributes::iterator it = _attributes.begin();

           it != _attributes.end(); ++it) {

        if (read_attr.find(it->first) == read_attr.end()) {

          std::ostringstream msg;

          throw FormatError(msg.str());

        }

      }

    }

  public:

    /// \name Execution of the reader

    /// @{

    /// \brief Start the batch processing

    ///

    /// This function starts the batch processing

    void run() {

      LEMON_ASSERT(_is != 0, "This reader assigned to an other reader");

      bool nodes_done = _skip_nodes;

      bool arcs_done = _skip_arcs;

      bool attributes_done = false;

      line_num = 0;

      readLine();

      skipSection();

      while (readSuccess()) {

        try {

          char c;

          std::string section, caption;

          line >> c;

          _reader_bits::readToken(line, section);

          _reader_bits::readToken(line, caption);

          if (line >> c)

          if (section == "nodes" && !nodes_done) {

            if (_nodes_caption.empty() || _nodes_caption == caption) {

              readNodes();

              nodes_done = true;

            }

          } else if ((section == "arcs" || section == "edges") &&

                     !arcs_done) {

            if (_arcs_caption.empty() || _arcs_caption == caption) {

              readArcs();

              arcs_done = true;

            }

          } else if (section == "attributes" && !attributes_done) {

            if (_attributes_caption.empty() || _attributes_caption == caption) {

              readAttributes();

              attributes_done = true;

            }

          } else {

            readLine();

            skipSection();

          }

        } catch (FormatError& error) {

          error.line(line_num);

          error.file(_filename);

          throw;

        }

      }

      if (!nodes_done) {

        throw FormatError("Section @nodes not found");

      }

      if (!arcs_done) {

        throw FormatError("Section @arcs not found");

      }

      if (!attributes_done && !_attributes.empty()) {

        throw FormatError("Section @attributes not found");

      }

    }

    /// @}

  };

  /// \brief Return a \ref DigraphReader class

  ///

  /// This function just returns a \ref DigraphReader class.

  /// \relates DigraphReader

  template <typename Digraph>

  DigraphReader<Digraph> digraphReader(std::istream& is, Digraph& digraph) {

    DigraphReader<Digraph> tmp(is, digraph);

    return tmp;

  }

  /// \brief Return a \ref DigraphReader class

  ///

  /// This function just returns a \ref DigraphReader class.

  /// \relates DigraphReader

  template <typename Digraph>

  DigraphReader<Digraph> digraphReader(const std::string& fn,

                                       Digraph& digraph) {

    DigraphReader<Digraph> tmp(fn, digraph);

    return tmp;

  }

  /// \brief Return a \ref DigraphReader class

  ///

  /// This function just returns a \ref DigraphReader class.

  /// \relates DigraphReader