// src/backend/key_file.hh - Copyright 2005, 2006, University
//               of Padova, dept. of Pure and Applied
//               Mathematics
//
// This file is part of SGPEMv2.
//
// This is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
//
// SGPEMv2 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. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with SGPEMv2; if not, write to the Free Software
// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

#ifndef KEY_FILE_HH
#define KEY_FILE_HH 1

#define KEY_FILE_BUF_LEN 1000

#include <glibmm/ustring.h>
#include <iostream>
#include <map>
#include "config.h"

namespace sgpem
{
  class KeyFile;
  
  /** \brief Save and retrieve configuration files formatted as key=value rows.
   *
   * This class handles files to store and retrieve configuration preferences
   * in the form of: key=value rows.
   *
   * The methods exposed allow to insert a key/value pair,
   * get a value by its corresponding key, write all pairs to a file,
   * read pairs from a file.
   *
   * Key values cannot contain the equal to (=) char nor start with pound (#).
   * Reading files, empty lines and lines starting with # are ignored.
   *
   */
  class SG_DLLEXPORT KeyFile
  {

  public:
    /** \brief Elements iterator type definition. */
    typedef std::map<Glib::ustring, Glib::ustring>::const_iterator elements_iterator;

    /** \brief Object constructor */
    KeyFile();

    /** \brief Elements iterator (begin of container) initializer. */
    elements_iterator elements_begin() const;
    
    /** \brief Elements iterator (end of container) initializer */
    elements_iterator elements_end() const;

    /** \brief Insert a new key/value pair.
     *
     * \param key The key value to insert.
     * \param value The value associated to the key inserted.
     */
    void insert_key_value(const Glib::ustring& key, const Glib::ustring& value);
    
    /** \brief Insert a new key/value pair.
     *
     * \param key The key value to insert.
     * \return A pointer to the value associated to the searched key or 0 if not found.
     */
    const Glib::ustring* search_value(const Glib::ustring& key);


    /** \brief Read a file into this object.
     *
     * \param filename The file to read from.
     */
    void file_read(const Glib::ustring& filename);
  

    /** \brief Read a stream into this object.
     *
     * \param is the stream to read from.
     */
    void file_read(std::istream& is);
    
    /** \brief Write into a file from this object.
     *
     * \param filename The file to write to.
     */
    void file_write(const Glib::ustring& filename);
    
    /** \brief Write into a stream from this object.
     *
     * \param os the stream to write to.
     */
    void file_write(std::ostream& os);
  private:

    std::map<Glib::ustring, Glib::ustring>  _elements;
  };
}

#endif