include/EDoc/TextPersistence.h

Go to the documentation of this file.

/*******************************************************************************

   Copyright (C) 2007 by Brendon Costa

   This library is free software; you can redistribute it and/or modify 
   it under the terms of the "LGPL Like" License defined in the file COPYING 
   that should have been distributed along with this source.

   This library is distributed in the hope that it will be useful, 
   but WITHOUT ANY WARRANTY; without even the implied warranty of 
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  

   You should have received a copy of the "LGPL Like" License 
   along with this library; see the file COPYING. if not, it can be 
   obtained from the EDoc++ website: 
   http://edoc.sourceforge.net/license.html

*******************************************************************************/
#ifndef EDOC_TEXTPERSISTENCE_H
#define EDOC_TEXTPERSISTENCE_H

#include "EDoc/stdint.h"
#include "EDoc/PersistenceIFace.h"

#include <string>
#include <fstream>

namespace EDoc
{
   //===========================================================================
   /** \brief An implementation of PersistenceIFace for writing to text files.
    *
    * This implementation of PersistenceIFace was created primarily for
    * debugging purposes. The files it generates are orders of magnitude larger
    * than the BinaryPersistence class, however the format it uses provides key
    * name, type and value validation upon reading. It also provides ability to
    * write in a highly verbose mode where whenever an integer index is written
    * to the file it will also write an un-used string that shows which data
    * type that integer indexes. This makes reading .edc files mush easier.
    *
    * From the persistence_data.h file this will use the macros:
    *    - BJC_PERSIST_START_KEY_CHAR '$'
    *    - BJC_PERSIST_FINISH_KEY_CHAR ':'
    *    - BJC_PERSIST_COMMENT_CHAR '#'
    *    .
    *
    * to define the delimiters to use for identifying the various fields of a
    * data item. The default format looks something like:
    *
    * \code
    * # Comment
    * $KeyName1: value
    * $KeyName2: int_value Ignored Debugging Text
    * \endcode
    *
    * This limits the string to be saved to string that only contain text values
    * and NOT CR/LF characters. This isnt a problem for EDoc currently but may
    * in the future be replaced with a format where the value is a string
    * escaped using standard unix like escape sequence conventions (i.e. based
    * on backslash char).
    */
   class TextPersistence : public PersistenceIFace
   {
   public:

      //------------------------------------------------------------------------
      /** \brief Create an instance that represents a text file for reading 
       * OR writing (But not both at once).
       *
       * Note: This does not open the file for reading/writing but just creates 
       * an instance of this class that is prepared for reading/writing to the
       * file.
       *
       * \param read If true then the file is considered an input file and can
       * only be used for reading. Otherwise it will be considered an output
       * file and will only be available for writing to.
       *
       * \param filename The name of the file to open.
       */
      TextPersistence(bool read, std::string filename);

      //------------------------------------------------------------------------
      /** \brief Closes the file upon destruction.
       */
      virtual ~TextPersistence();

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::Open()
       */
      virtual void Open();

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::Close()
       */
      virtual void Close();

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadString()
       */
      virtual std::string ReadString(const char* key);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadBoolean()
       */
      virtual bool ReadBoolean(const char* key);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadUInt8()
       */
      virtual uint8_t ReadUInt8(const char* key);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadInt32()
       */
      virtual int32_t ReadInt32(const char* key);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadUInt32()
       */
      virtual uint32_t ReadUInt32(const char* key);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadRecordType()
       */
      virtual uint8_t ReadRecordType();


      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteString()
       */
      virtual void WriteString(const char* key, std::string value);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteBoolean()
       */
      virtual void WriteBoolean(const char* key, bool value);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteUInt8()
       */
      virtual void WriteUInt8(const char* key, uint8_t value);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteInt32()
       */
      virtual void WriteInt32(const char* key, int32_t value);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteUInt32()
       */
      virtual void WriteUInt32(const char* key, uint32_t value);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteUInt32Debug()
       */
      virtual void WriteUInt32Debug(const char* key, uint32_t value, 
         std::string debug_text);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteInt32Debug()
       */
      virtual void WriteInt32Debug(const char* key, int32_t value, 
         std::string debug_text);

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteRecordType()
       */
      virtual void WriteRecordType(uint8_t value);

      //------------------------------------------------------------------------

   private:

      //------------------------------------------------------------------------
      /** \brief Returns true if the given string contains any characters that
       * are not whitespaces.
       */
      static bool ContainsData(const std::string& data);

      //------------------------------------------------------------------------
      /** \brief Reads a line of data extracting the value string for that
       * line.
       *
       * This will also validate the type and key throwing an exception if the
       * data is not valid.
       */
      std::string ReadValue(const char* key_in, const char* type_in);

      //------------------------------------------------------------------------
      /** \brief Reads the next line of data from the file.
       *
       * Performs no processing of the data but may use key_in and type_in for
       * debugging purposes if an EOF is encountered.
       */
      std::string GetNextLine(const char* key_in = "", 
         const char* type_in = "");

      //------------------------------------------------------------------------
      /** \brief The file stream used for writing/reading to/from.
       */
      std::fstream file;

      //------------------------------------------------------------------------
      /** \brief True if opened for reading.
       */
      bool reading;

      //------------------------------------------------------------------------
      /** \brief Current number of lines read from the file.
       *
       * Used primarily in providing more useful debugging information.
       */
      size_t line_count;

      //------------------------------------------------------------------------
      /** \brief Name of file being operated on.
       */
      std::string filename;

      //------------------------------------------------------------------------

   };
   //===========================================================================

}


#endif // EDOC_TEXTPERSISTENCE_H

---