// Text.h

// Class to represent a named block of text.
// Provides methods to read from or write to a file.
//
// Uses WorkingDirectory to take ownership of the working directory
// when reading or writing a file with a relative name.
//
// XML representation
//
// Text
//   name = mydata.dat
//   nline = 2
//   Line
//     number = 0
//     text = Line 1
//   Line
//     number = 1
//     text = Line two

#ifndef Text_H
#define Text_H

#include <string>
#include <vector>
#include <iosfwd>

class XmlElement;

class Text {

public:  // typedefs

  typedef std::string Name;
  typedef std::string Line;
  typedef std::vector<Line> LineList;
  typedef std::string Word;
  typedef std::vector<Word> WordList;
  typedef LineList::size_type size_type;

private:  // data

  // Name.
  Name m_name;

  // File text.
  LineList m_lines;

  // Validity.
  bool m_valid;

public:  // static functions

  // XML name.
  static const char* xml_name() { return "Text"; }

  // DTD.
  static const Text& dtd();

  // Split a line up into words and append to an exiting list.
  // Returns the number of words appended.
  // Delimiters between words are any of the characters in delimiters.
  static int split(Line line, WordList& words, Line delimiters =" ",
                   bool skipblanks =true);

  // Split a line into a new list of words.
  // If skipblanks is true then consecutive delimiters are treated
  // as a single delimiter. Otherwise a blank is returned as the word
  // between adjacent delimiters.
  static WordList split(Line line, Line delimiters = " ",
                        bool skipblanks =true);

  // Replace special characters with their XML representations.
  static void text_to_xml(Line& line);

  // Replace special characters with their XML representations.
  static void xml_to_text(Line& line);

  // Set flag to print warnings when a file cannot be read.
  static void set_warn(bool flag =true);

  // Return the above flag.
  static bool warn();

public:  // functions

  // Default constructor.
  // Creates an unnamed empty text block.
  Text();

  // Constructor which creates a named text block.
  // If read is true, the object is filled from that file if the
  // following conditions are met:
  //   1. The file is regular
  //   2. The file is readable
  //   3. The file only contains printable characters:
  //      ascii ' ' through '~'.
  // If read is false or the above conditions are not met, the object
  // is left empty.
  // If read and check_file are both true and the above conditions are
  // not met, the object is marked invalid.
  // If warn() is set, then a message is sent to cerr when an invalid
  // object is created.
  explicit Text(Name name, bool read =true, bool check_file =false);

  // Constructor from XML.
  explicit Text(const XmlElement& ele);

  // Validity.
  bool is_valid() const;

  // Change the name.
  // Object must be valid.
  // Returns 0 for success.
  int set_name(Name name);

  // Append a line.
  void append(Line line);

  // Append text.
  void append(const Text& txt);

  // Name.
  Name name() const { return m_name; }

  // Number of lines.
  size_type size() const;

  // Return a line. Valid values are 0 - size()-1.
  // Blank if invalid.
  Line line(size_type iline) const;

  // Write contents to a file.
  // If the argument is blank and the object has a name, then that
  // name is used for the output file.
  // Returns 0 for success.
  int write(Name name ="") const;

  // Write to XML.
  XmlElement* xml() const;

};

// Output stream
std::ostream& operator<<(std::ostream& lhs, const Text& rhs);

// Equality.
bool operator==(const Text& lhs, const Text& rhs);

// Inequality.
bool operator!=(const Text& lhs, const Text& rhs);

#endif