/*-*- c++ -*-*****************************************************************\
 * Project:   CppLib: C++ library for Windows/UNIX platfroms                 *
 * File:      config.h - Config class, .INI/.rc file manager                 *
 *---------------------------------------------------------------------------*
 * Language:  C++                                                            *
 * Platfrom:  any (tested under Windows NT)                                  *
 *---------------------------------------------------------------------------*
 * (c) Karsten Ball黡er & Vadim Zeitlin                                      *
 *     Ballueder@usa.net  Vadim.zeitlin@dptmaths.ens-cachan.fr               *
 *---------------------------------------------------------------------------*
 * $Id: appconf.h,v 1.2 2000/05/03 18:29:00 mbn Exp $                    *
 *---------------------------------------------------------------------------*
 * Classes:                                                                  *
 *  BaseConfig      - ABC for class that manage tree organized config info   *
 *  FileConfig      - implementation of BaseConfig based on disk files       *
 *  RegistryConfig  - implementation of BaseConfig based Win32 registry      *
 *---------------------------------------------------------------------------*
 * To do:                                                                    *
 *  - derive wxConfig                                                        *
 *  - EXTENSIVE ERROR CHECKING (none done actually)                          *
 *  - derive IniConfig for standard dumb Windows INI files using Win APIs    *
 *---------------------------------------------------------------------------*
 * History:                                                                  *
 *  25.10.97  adapted from wxConfig by Karsten Ball黡er                      *
 *  29.10.97  FileConfig now saves comments back (VZ)                        *
 *  30.10.97  Immutable entries support added (KB)                           *
 *  01.11.97  Fixed NULL pointer access in BaseConfig::setCurrentPath (KB)   *
 *            Replaced filterIn() with original function from wxConfig,      *
 *            doing environment variable expansion, too (KB)                 *
 *            Made parsing case insensitive (Compile time option) (KB)       *
 *  02.11.97  Added deleteEntry function (VZ)                                *
 *  08.11.97  Environment variable expansion on demand (VZ)                  *
 *            RegistryConfig::changeCurrentPath added (VZ)                   *
 *            AppConf defined to be used instead of File/RegistryConfig      *
 *  18.01.98  Several fixes and changes to FileConfig (KB)                   *
 *            Added recordDefaults() method (KB)                             *
\*****************************************************************************/

#ifndef   _APPCONF_H
#define   _APPCONF_H


/**@name AppConf - Configuration entry management 
 * 
 *
 * <b>Copyright</b><br>
 * This library is free software; you can redistribute it and/or      
 * modify it under the terms of the GNU Library General Public        
 * License as published by the Free Software Foundation; either       
 * version 2 of the License, or (at your option) any later version.   
 * <p>                                                                   
 * 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.  See the GNU  
 * Library General Public License for more details.                   
 * <p>                                                                   
 * You should have received a copy of the GNU Library General Public  
 * License along with this library; if not, write to the Free         
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 
 * <p>                                                                   
 *
 *These classes support easy to use management of configuration settings.
 *On Unix systems these settings get written to configuration files, of the
 *type used by Windows (.INI) and KDE (.lnk). On Win32 systems (Windows NT
 *or 95), the settings get written to the registry database.<br>
 *Therefor AppConfig provides a consistent API for configuration management
 *across both platforms. The API is defined by the BaseConfig virtual base
 *class and two implemenations, FileConfig and RegistryConfig are derived
 *from this. Nevertheless, you can also use FileConfig under Windows if
 *you need it for some special purpose.
 *<p>
 *The class AppConfig is defined which is the 'native' implementation on
 *each platform. 
 *<p>
 *Also, if the gettext() library function is available (use -lintl on
 *Unix systems), AppConfig can be compiled with -DAPPCONF_USE_GETTEXT=1
 *to support multiple languages in its error messages.
 *Precompiled message catalogues for German and French are included,
 *copy them to the appropriate directories under Unix 
 *(e.g. /usr/share/locale/fr/LC_MESSAGES/appconf.mo or
 * /usr/share/locale/de/LC_MESSAGES/appconf.mo).
 *<p>
 *Two simple programs demonstrating the use of AppConfig are included.
 *<p>
 *Full documentation of the classes is included in HTML format in the
 *doc directory. Please use your web browser to view it.<br>
 *The LaTeX documentation appconf.tex in the same directory contains a
 *few errors (because it was auto-generated with doc++), but is usable.
 *Just keep pressing Enter when LaTeX complains. An A4 PostScript version
 *is also included.
 *<p>
 *Feel free to contact us with any questions or suggestions. If you use
 *it in your programs, we would be pleased to hear about it.
 * @memo	A configuration management system for Unix and Windows.
 * @author	Karsten Ball&uuml;der and Vadim Zeitlin
 */
//@{

#if APPCONF_USE_CONFIG_H
# include <config.h>
#endif

#include  <iostream>
#include  <stdlib.h>

// make sure we have a Bool type
typedef   int Bool;
#ifndef    TRUE
# define    TRUE  1
# define    FALSE 0
#endif

// make sure we have NULL defined properly
// #undef  NULL
// #define NULL 0

// ----------------------------------------------------------------------------
// constants
// ----------------------------------------------------------------------------


/**@name configuration options */
//@{

/// can we use gettext() for multi language support?

#ifndef	APPCONF_USE_GETTEXT
#		define	APPCONF_USE_GETTEXT	0
#else
#		define	APPCONF_DOMAIN	"appconf"
#endif

/// shall we be case sensitive in parsing variable names?
#ifndef APPCONF_CASE_SENSITIVE
#	define	APPCONF_CASE_SENSITIVE	0
#endif

/// separates group and entry names
#ifndef APPCONF_PATH_SEPARATOR
#	define   APPCONF_PATH_SEPARATOR     '/'
#endif

/// introduces immutable entries
#ifndef APPCONF_IMMUTABLE_PREFIX
#	define   APPCONF_IMMUTABLE_PREFIX   '!'
#endif

/// length for internal character array for expansion (e.g. for gcvt())
#ifndef APPCONF_STRBUFLEN
#	define   APPCONF_STRBUFLEN          1024
#endif

/// should we use registry instead of configuration files under Win32?
#ifndef	  APPCONF_WIN32_NATIVE
#	define APPCONF_WIN32_NATIVE 		1 	// default: TRUE
#endif

//@}

/**@name helper functions */
//@{
// ----------------------------------------------------------------------------
// global functions
// ----------------------------------------------------------------------------
/** Replace environment variables ($SOMETHING) with their values.  The
   format is $VARNAME or ${VARNAME} where VARNAME contains
   alphanumeric characters and '_' only. '$' must be escaped ('\$') in
   order to be taken literally.
  @param  pointer to the string possibly contianing $VAR and/or ${VAR}
  @return the resulting string, caller must 'delete []' it
  @memo Performs environment variable substitution.  */
char *ExpandEnvVars(const char *psz);
//@}

/**@name Configuration Management Classes */
//@{

// ----------------------------------------------------------------------------
///	abstract base class config
// ----------------------------------------------------------------------------
class BaseConfig
{
public:
  /** @name Constructors and destructor */
  //@{
    /// default ctor
  BaseConfig();
    /// dtor
  virtual ~BaseConfig();
  //@}

  /** @name Set and retrieve current path */
  //@{
  /**
    Specify the new current path by its absolute name.
    @param szPath name of the group to search by default (created if !exists)
  */
  virtual void setCurrentPath(const char *szPath = "");

     /**
	Change the current path.
	Works like 'cd' and supports "..".
    @param szPath name of the group to search by default (created if !exists)
  */
  virtual void changeCurrentPath(const char *szPath = "");

  /**
    Query the current path.
    @return current '/' separated path
  */
  const char *getCurrentPath() const;
  /** 
    Resolve ".." and "/" in the path.
    @param  Start path (i.e. current directory)
    @param  Relative path (".." allowed) from start path
    @return Pointer to normalized path (caller should "delete []" it)
  */
  static char *normalizePath(const char *szStartPath, const char *szPath);
  //@}

   /** activates recording of default values
       @param enable TRUE to activate, FALSE to deactivate
   */
   void recordDefaults(Bool enable = TRUE);

  /**@name Enumeration of subgroups/entries */
  //@{
   /**
      This class allows access to an array of strings, which are entries or group names.
      @memo Class that supports enumeration.
      @see  enumSubgroups, enumEntries
    */
  class Enumerator
  {
  public:
    // if bOwnsStrings, it will delete them in dtor
    Enumerator(size_t nCount, Bool bOwnsStrings);
    ~Enumerator();

    // add a string
      // this one may be used only if bOwnsString was TRUE in ctor
    void AddString(const char *sz);
      // 
    void AddString(char *sz);
    
    // kludge: eliminate duplicate strings
    void MakeUnique();

    // accessors
      /// return number of elements
    size_t      Count()                   const { return m_nCount;          }
      /// return the element #nIndex
    const char *operator[](size_t nIndex) const { return m_aszData[nIndex]; }

  private:
    char    **m_aszData;
    size_t    m_nCount;
    Bool      m_bOwnsStrings;
  };
    /**
      Enumerate subgroups of the current group.
      Caller must delete the returned pointer.
      Example of usage:
      <br><pre>
      char **aszGroups;
      config.setCurrentPath("mygroup");
      BaseConfig::Enumerator *pEnum = config.enumSubgroups();
      size_t nGroups = pEnum->Count();
      for ( size_t n = 0; n < nGroups; n++ )
        cout << "Name of subgorup #" << n << " is " << (*pEnum)[n] << endl;
      delete pEnum;
      </pre>
      @param  Pointer to an array of strings which is allocated by the function
      @return Number of subgroups
      @see    Enumerator, setCurrentPath, enumEntries 
    */
  virtual Enumerator *enumSubgroups() const = 0;
    /** 
      Enumerate entries of the current group.
      @return Number of entries
      @see    Enumerator, enumSubgroups
    */
  virtual Enumerator *enumEntries() const = 0;
  //@}

  /** @name Key access */
  //@{
  /**
    Get the value of an entry, or the default value.
    @param szKey      The key to search for.
    @param szDefault  The default value to return if not found.
    @return The value of the key, or defval if not found
  */
  virtual const char *readEntry(const char *szKey, 
                                const char *szDefault = NULL) const = 0;

   /**
     Get the value of an entry, or the default value, interpreted as a
     long integer.
     @param szKey	The key to search for.
     @param Default	The default value to return if not found.
     @return The value of the key converted to long int or the default value.
   */
   long int readEntry(const char *szKey, long int Default) const;

   /**
     Get the value of an entry, or the default value, interpreted as a
     double value.
     @param szKey	The key to search for.
     @param Default	The default value to return if not found.
     @return The value of the key converted to double or the default value.
   */
   double readEntry(const char *szKey, double Default) const;

   /**
    Set the value of an entry.
    @param szKey    The key whose value to change.
    @param szValue	The new value.
    @return TRUE on success, FALSE on failure
  */
  virtual Bool writeEntry(const char *szKey, const char *szValue) = 0;

   /**
    Set the value of an entry to a long int value.
    @param szKey    The key whose value to change.
    @param Value	The new value.
    @return TRUE on success, FALSE on failure
  */
   Bool writeEntry(const char *szKey, long int Value);

   /**
    Set the value of an entry to a double value.
    @param szKey    The key whose value to change.
    @param Value	The new value.
    @return TRUE on success, FALSE on failure
  */
  Bool writeEntry(const char *szKey, double Value);

   /**
    Delets the entry. Notice that there is intentionally no such function 
    as deleteGroup: the group is automatically deleted when it's last entry 
    is deleted.

    @memo   Deletes the entry.
    @param  szKey    The key to delete
    @return TRUE on success, FALSE on failure
  */
  virtual Bool deleteEntry(const char *szKey) = 0;
  //@}

  /** @name Other functions */
  //@{
    /// permanently writes changes, returns TRUE on success
  virtual Bool flush(Bool /* bCurrentOnly */ = FALSE) { return TRUE; }
    /// returns TRUE if object was correctly initialized
  Bool isInitialized() const { return m_bOk; }
  //@}

  /** 
    @name Filter functions.
    All key values should pass by these functions, derived classes should
    call them in their read/writeEntry functions.
    Currently, these functions only escape meta-characters (mainly spaces
    which would otherwise confuse the parser), but they could also be used 
    to encode/decode key values.
  */
  //@{
    /// should be called from writeEntry, returns pointer to dynamic buffer
  static char *filterOut(const char *szValue);
    /// should be called from readEntry, returns pointer to dynamic buffer
  static char *filterIn(const char *szValue);