/// should environment variables be automatically expanded?
  void expandVariables(Bool bExpand = TRUE) { m_bExpandVariables = bExpand; }
   /// do environment variables get automatically expanded?
  Bool doesExpandVariables(void) const { return m_bExpandVariables; }
   //@}

protected:
  /// TRUE if ctor successfully initialized the object
  Bool  m_bOk;
  /// TRUE if environment variables are to be auto-expanded
  Bool  m_bExpandVariables;
  /// TRUE if default values are to be recorded
  Bool	m_bRecordDefaults; 
private:
  char *m_szCurrentPath;
};

// ----------------------------------------------------------------------------
/**
  FileConfig derives from BaseConfig and implements file based config class, 
  i.e. it uses ASCII disk files to store the information. These files are
  alternatively called INI, .conf or .rc in the documentation. They are 
  organized in groups or sections, which can nest (i.e. a group contains
  subgroups, which contain their own subgroups &c). Each group has some
  number of entries, which are "key = value" pairs. More precisely, the format 
  is: 
  <pre>
  # comments are allowed after either ';' or '#' (Win/UNIX standard)
  # blank lines (as above) are ignored
  # global entries are members of special (no name) top group
  written_for = wxWindows
  platform    = Linux
  # the start of the group 'Foo'
  [Foo]                           # may put comments like this also
  # following 3 lines are entries
  key = value
  another_key = "  strings with spaces in the beginning should be quoted, \
                   otherwise the spaces are lost"
  last_key = but you don't have to put " normally (nor quote them, like here)
  # subgroup of the group 'Foo'
  # (order is not important, only the name is: separator is '/', as in paths)
  [Foo/Bar]
  # entries prefixed with "!" are immutable, i.e. can't be changed if they are
  # set in the system wide .conf file
  !special_key = value
  bar_entry = whatever
  [Foo/Bar/Fubar]   # depth is (theoretically :-) unlimited
  # may have the same name as key in another section
  bar_entry = whatever not
  </pre>
  You {have read/write/delete}Entry functions (guess what they do) and also
  setCurrentPath to select current group. enum{Subgroups/Entries} allow you
  to get all entries in the config file (in the current group). Finally,
  flush() writes immediately all changed entries to disk (otherwise it would
  be done automatically in dtor)
  FileConfig manages not less than 2 config files for each program: global
  and local (or system and user if you prefer). Entries are read from both of
  them and the local entries override the global ones unless the latter is
  immutable (prefixed with '!') in which case a warning message is generated
  and local value is ignored. Of course, the changes are always written to local
  file only.
*/
// ----------------------------------------------------------------------------

class FileConfig : public BaseConfig
{
public:
  /** @name Constructors and destructor */
  //@{
    /**
      FileConfig will
      <ll>
      <li>1) read global config file (/etc/appname.conf under UNIX or 
             windir\<file>.ini under Windows) unless bLocalOnly is TRUE
      <li>2) read user's config file ($HOME/.appname or $HOME/.appname/config or %USERPROFILE%/file.ini
             under NT, same as global otherwise)
      <li>3) write changed entries to user's file, never to the system one.
      </ll>
      @memo   Ctor for FileConfig takes file name argument.
      @param  szFileName  Config file, default extension appended if not given
      @param  bLocalOnly  TRUE => don't look for system-wide config file
      @param  bUseSubDir  TRUE => filename is not called $HOME/.<appname> but $HOME/.<appname>/config
    */
   FileConfig(const char *szFileName, Bool bLocalOnly = FALSE,
	      Bool bUseSubDir = FALSE);
   /**
      @memo   Ctor for FileConfig for reading from a stream
      @param  input stream to read from
    */
  
   FileConfig(std::istream *iStream);
   /**
      Another constructor, creating an empty object. For use with the
      readFile() method.
   */
   FileConfig(void);

  /**
      Notice that if you're interested in error code, you should use
      flush() function.
      @memo Dtor will save unsaved data.
    */
 ~FileConfig();
  //@}

   /**
      Like reading from a local configuration file, but takes a whole
      path as argument. No default configuration files used. Use with
      FileConfig() constructor.
   */
   void readFile(const char *szFileName);
   
  /** @name Implementation of inherited pure virtual functions */
  //@{
    ///
  const char *readEntry(const char *szKey, const char *szDefault = NULL) const;
    ///
  long int readEntry(const char *szKey, long int Default) const
       { return BaseConfig::readEntry(szKey, Default); }
    ///
  double readEntry(const char *szKey, double Default) const
      { return BaseConfig::readEntry(szKey, Default); }
   ///
  Bool writeEntry(const char *szKey, const char *szValue);
   ///
  Bool writeEntry(const char *szKey, long int Value)
     { return BaseConfig::writeEntry(szKey, Value);}
   ///
  Bool writeEntry(const char *szKey, double Value)
     { return BaseConfig::writeEntry(szKey, Value); }
   ///
  Bool deleteEntry(const char *szKey);
    ///
  Bool flush(Bool bCurrentOnly = FALSE);
   /// writes changes to ostream, returns TRUE on success
  Bool flush(std::ostream *oStream, Bool /* bCurrentOnly */ = FALSE);

   /// parses one line of config file
  Bool parseLine(const char *psz);

   
    ///
  void changeCurrentPath(const char *szPath = "");
  //@}

  /** 
    @name Enumeration 
    @see  BaseConfig::enumSubgroups, BaseConfig::enumEntries
  */
  //@{
    /// Enumerate subgroups of the current group
  Enumerator *enumSubgroups() const;
    /// Enumerate entries of the current group
  Enumerator *enumEntries() const;
  //@}

//protected: --- if FileConfig::ConfigEntry is not public, functions in
//               ConfigGroup such as Find/AddEntry can't return ConfigEntry*!
  class ConfigGroup;
  class ConfigEntry
  {
  private:
    ConfigGroup *m_pParent;     // group that contains us
    ConfigEntry *m_pNext;       // next entry (in linked list)
    char        *m_szName,      // entry name
                *m_szValue,     //       value
                *m_szExpValue,  // value with expanded env variables
                *m_szComment;   // optional comment preceding the entry
    Bool         m_bDirty,      // changed since last read?
                 m_bLocal,      // read from user's file or global one?
                 m_bImmutable;  // can be overriden locally?

  public:
    ConfigEntry(ConfigGroup *pParent, ConfigEntry *pNext, const char *szName);
   ~ConfigEntry();

    // simple accessors
    const char  *Name()         const { return m_szName;     }
    const char  *Value()        const { return m_szValue;    }
    const char  *Comment()      const { return m_szComment;  }
    ConfigEntry *Next()         const { return m_pNext;      }
    Bool         IsDirty()      const { return m_bDirty;     }

    // expand environment variables and return the resulting string
    const char *ExpandedValue();

    // modify entry attributes
    void SetValue(const char *szValue, 
                  Bool bLocal = TRUE, 
                  Bool bFromFile = FALSE);
    void SetComment(char *szComment);
    void SetDirty(Bool bDirty = TRUE);
    void SetNext(ConfigEntry *pNext) { m_pNext = pNext; }
  };

protected:
  class ConfigGroup
  {
  private:
    ConfigEntry *m_pEntries,    // list of entries in this group
                *m_pLastEntry;  // last entry
    ConfigGroup *m_pSubgroups,  // list of subgroups
                *m_pLastGroup,  // last subgroup
                *m_pNext,       // next group at the same level as this one
                *m_pParent;     // parent group
    char        *m_szName,      // group's name
                *m_szComment;   // optional comment preceding this group
    Bool         m_bDirty;      // if FALSE => all subgroups are not dirty

  public:
    // ctors
    ConfigGroup(ConfigGroup *pParent, ConfigGroup *pNext, const char *szName);

    // dtor deletes all entries and subgroups also
    ~ConfigGroup();

    // simple accessors
    const char  *Name()     const { return m_szName;      }
    const char  *Comment()  const { return m_szComment;   }
    ConfigGroup *Next()     const { return m_pNext;       }
    ConfigGroup *Parent()   const { return m_pParent;     }
    ConfigGroup *Subgroup() const { return m_pSubgroups;  }
    ConfigEntry *Entries()  const { return m_pEntries;    }
    Bool         IsDirty()  const { return m_bDirty;      }

    // full name ('/' separated path from top)
    // caller must free buffer
    char *FullName() const;

    // find entry/subgroup (NULL if not found)
    ConfigGroup *FindSubgroup(const char *szName) const;
    ConfigEntry *FindEntry   (const char *szName) const;

    // delete entry/subgroup, return FALSE if doesn't exist
    Bool DeleteSubgroup(const char *szName);
    Bool DeleteEntry   (const char *szName);

    // create new entry/subgroup returning pointer to newly created element
    ConfigGroup *AddSubgroup(const char *szName);
    ConfigEntry *AddEntry   (const char *szName);

    // will also recursively call parent's dirty flag
    void SetDirty(Bool bDirty = TRUE);
    
    // comment shouldn't be empty if this function is used
    void SetComment(char *szComment);
    
    // write dirty data
    Bool flush(std::ostream *ostr);
  };

  // delete current group if has no more entries/subgroups
  // NB: changes m_pCurGroup is returns TRUE (i.e. the group was deleted)
  Bool DeleteIfEmpty();

  ConfigGroup *m_pRootGroup,  // there is one and only one root group
              *m_pCurGroup;   // and also unique current (default) one

  // create all groups found in the strem under group pRootGroup or
  // m_pRootGroup if parameter is NULL
  // returns TRUE on success
  Bool readStream(std::istream *istr, ConfigGroup *pRootGroup = NULL);

  // construct global and local filenames based on the base file name
  // (which nevertheless may contain "/")
    // get the name of system-wide config file
  const char *GlobalConfigFile() const;
    // get the name of user's config file
  const char *LocalConfigFile() const;

  /// trivial initialization of member variables (common to all ctors)
  void Init();

private:
  char     *m_szFileName;        // config file name
 
  const char *m_szFullFileName;  // full file name for error messages
  unsigned  m_uiLine;            // line number for error messages
  Bool      m_bParsingLocal;     // TRUE while parsing user's config file
  Bool      m_bUseSubDir;	// shall we use a subdirectory for config file?  
  // we store in a variable all comments + whitespace preceding the
  // current entry or group in order to be able to store it later
  void      AppendCommentLine(const char *psz = NULL);
  char     *m_szComment;
};

// ----------------------------------------------------------------------------
/// RegistryConfig uses Win32 registry API to store configuration info
// ----------------------------------------------------------------------------
#ifdef  __WIN32__

class RegistryConfig : public BaseConfig
{
public:
  /** @name Constructors and destructor */
  //@{
    /** 
      szRootKey is the name of the top registry key (relative to HKLM\Software
      for system-wide settings and to HKCU\Software for user settings)
      @memo Ctor takes a string - root for our keys in registry.
     */
  RegistryConfig(const char *szRootKey);
    /// dtor frees the resources
 ~RegistryConfig();
  //@}

  /** @name Implementation of inherited pure virtual functions */
  //@{
    ///
   const char *readEntry(const char *szKey, const char *szDefault = NULL) const;
   ///
   long int readEntry(const char *szKey, long int Default) const
      { return BaseConfig::readEntry(szKey, Default); }
    ///
   double readEntry(const char *szKey, double Default) const
      { return BaseConfig::readEntry(szKey, Default); }

    ///
   Bool writeEntry(const char *szKey, const char *szValue);
    ///
   Bool writeEntry(const char *szKey, long int Value)
     { return BaseConfig::writeEntry(szKey, Default);}
   ///
   Bool writeEntry(const char *szKey, double Value)
     { return BaseConfig::writeEntry(szKey, Default); }

    ///
  Bool deleteEntry(const char *szKey);
  //@}

  /** 
    @name Enumeration 
    @see  Enumerator, BaseConfig::enumSubgroups, BaseConfig::enumEntries
  */
  //@{
    /// Enumerate subgroups of the current group
  Enumerator *enumSubgroups() const;
    /// Enumerate entries of the current group
  Enumerator *enumEntries() const;
  //@}

  // intercept this function and change m_hCurrentKey
  virtual void changeCurrentPath(const char *szPath = "");

private:
  const char *ReadValue(void *hKey, const char *szValue) const;
  static Bool KeyIsEmpty(void *hKey);

  void *m_hGlobalRootKey,       // top of system settings
       *m_hLocalRootKey,        // top of user settings
       *m_hGlobalCurKey,        // current registry key (child of global root)
       *m_hLocalCurKey;         //                                local

  char *m_pLastRead;      // pointer to last read value (###)
};

#endif  // WIN32

/// AppConfig is mapped on the class most appropriate for the target platform
#if	  APPCONF_WIN32_NATIVE && defined(__WIN32__)
  typedef class RegistryConfig AppConfig;
#else
  typedef class FileConfig     AppConfig;
#endif

//@}

//@}
#endif  //_APPCONF_H