include/wx/config.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        config.h
   3 // Purpose:     declaration of the base class of all config implementations
   4 //              (see also: fileconf.h and msw/regconf.h)
   5 // Author:      Karsten Ballüder & Vadim Zeitlin
   6 // Modified by:
   7 // Created:     07.04.98 (adapted from appconf.h)
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 1997 Karsten Ballüder   Ballueder@usa.net
  10 //                       Vadim Zeitlin      <zeitlin@dptmaths.ens-cachan.fr>
  11 // Licence:     wxWindows license
  12 ///////////////////////////////////////////////////////////////////////////////
  13
  14 #ifndef   _APPCONF_H
  15 #define   _APPCONF_H
  16
  17 #ifdef __GNUG__
  18 #pragma interface "config.h"
  19 #endif
  20
  21 // ----------------------------------------------------------------------------
  22 // compile options
  23 // ----------------------------------------------------------------------------
  24
  25 // it won't compile without it anyhow
  26 #ifndef USE_WXCONFIG
  27   #error "Please define USE_WXCONFIG or remove config.cpp from your makefile"
  28 #endif // USE_WXCONFIG
  29
  30 // ----------------------------------------------------------------------------
  31 // constants
  32 // ----------------------------------------------------------------------------
  33
  34 /// shall we be case sensitive in parsing variable names?
  35 #ifndef APPCONF_CASE_SENSITIVE
  36   #define  APPCONF_CASE_SENSITIVE       FALSE
  37 #endif
  38
  39 /// separates group and entry names
  40 #ifndef APPCONF_PATH_SEPARATOR
  41   #define   APPCONF_PATH_SEPARATOR     '/'
  42 #endif
  43
  44 /// introduces immutable entries
  45 #ifndef APPCONF_IMMUTABLE_PREFIX
  46   #define   APPCONF_IMMUTABLE_PREFIX   '!'
  47 #endif
  48
  49 /// should we use registry instead of configuration files under Win32?
  50 #ifndef   APPCONF_WIN32_NATIVE
  51   #define APPCONF_WIN32_NATIVE          TRUE
  52 #endif
  53
  54 // ----------------------------------------------------------------------------
  55 // various helper global functions
  56 // ----------------------------------------------------------------------------
  57
  58 /*
  59   Replace environment variables ($SOMETHING) with their values. The format is
  60   $VARNAME or ${VARNAME} where VARNAME contains alphanumeric characters and
  61   '_' only. '$' must be escaped ('\$') in order to be taken literally.
  62  */
  63 extern wxString wxExpandEnvVars(const char *sz);
  64
  65 /*
  66   Split path into parts removing '..' in progress
  67  */
  68 extern void wxSplitPath(wxArrayString& aParts, const char *sz);
  69
  70 // ----------------------------------------------------------------------------
  71 // abstract base class wxConfig which defines the interface for derived classes
  72 //
  73 // wxConfig organizes the items in a tree-like structure (modeled after the
  74 // Unix/Dos filesystem). There are groups (directories) and keys (files).
  75 // There is always one current group given by the current path.
  76 //
  77 // Keys are pairs "key_name = value" where value may be of string or integer
  78 // (long) type (@@@ doubles and other types such as wxDate coming soon).
  79 // ----------------------------------------------------------------------------
  80 class wxConfig
  81 {
  82 public:
  83   // static functions
  84     // sets the config object, returns the previous pointer
  85   static wxConfig *Set(wxConfig *pConfig);
  86     // get the config object, creates it on demand
  87   static wxConfig *Get() { if ( !ms_pConfig ) Create(); return ms_pConfig; }
  88     // create a new config object
  89   static void Create();
  90
  91   // ctor & virtual dtor
  92   wxConfig() { m_bExpandEnvVars = TRUE; }
  93   virtual ~wxConfig();
  94
  95   // path management
  96     // set current path: if the first character is '/', it's the absolute path,
  97     // otherwise it's a relative path. '..' is supported. If the strPath
  98     // doesn't exist it is created.
  99   virtual void SetPath(const wxString& strPath) = 0;
 100     // retrieve the current path (always as absolute path)
 101   virtual const wxString& GetPath() const = 0;
 102
 103   // enumeration: all functions here return false when there are no more items.
 104   // you must pass the same lIndex to GetNext and GetFirst (don't modify it)
 105     // enumerate subgroups
 106   virtual bool GetFirstGroup(wxString& str, long& lIndex) = 0;
 107   virtual bool GetNextGroup (wxString& str, long& lIndex) = 0;
 108     // enumerate entries
 109   virtual bool GetFirstEntry(wxString& str, long& lIndex) = 0;
 110   virtual bool GetNextEntry (wxString& str, long& lIndex) = 0;
 111     // get number of entries/subgroups in the current group, with or without
 112     // it's subgroups
 113   virtual uint GetNumberOfEntries(bool bRecursive = FALSE) const = 0;
 114   virtual uint GetNumberOfGroups(bool bRecursive = FALSE) const = 0;
 115
 116   // tests of existence
 117     // returns TRUE if the group by this name exists
 118   virtual bool HasGroup(const wxString& strName) const = 0;
 119     // same as above, but for an entry
 120   virtual bool HasEntry(const wxString& strName) const = 0;
 121     // returns TRUE if either a group or an entry with a given name exist
 122   bool Exists(const wxString& strName) const
 123     { return HasGroup(strName) || HasEntry(strName); }
 124
 125   // key access: returns TRUE if value was really read, FALSE if default used
 126   // (and if the key is not found the default value is returned.)
 127     // read a string from the key
 128   virtual bool Read(wxString *pStr, const char *szKey,
 129                     const char *szDefault = NULL) const = 0;
 130     // another version using statis buffer - it means it will be overwritten
 131     // after each call to this function!
 132   virtual const char *Read(const char *szKey,
 133                            const char *szDefault = NULL) const;
 134     // the same for longs
 135   virtual long Read(const char *szKey, long lDefault) const
 136     { long l; Read(&l, szKey, lDefault); return l; }
 137     // and another version: returns true if default value is returned
 138   virtual bool Read(long *pl, const char *szKey, long lDefault = 0) const = 0;
 139
 140     // write the value (return true on success)
 141   virtual bool Write(const char *szKey, const char *szValue) = 0;
 142   virtual bool Write(const char *szKey, long lValue) = 0;
 143     // permanently writes all changes
 144   virtual bool Flush(bool bCurrentOnly = FALSE) = 0;
 145
 146   // delete entries/groups
 147     // deletes the specified entry and the group it belongs to if
 148     // it was the last key in it and the second parameter is true
 149   virtual bool DeleteEntry(const char *szKey,
 150                            bool bDeleteGroupIfEmpty = TRUE) = 0;
 151     // delete the group (with all subgroups)
 152   virtual bool DeleteGroup(const char *szKey) = 0;
 153     // delete the whole underlying object (disk file, registry key, ...)
 154     // primarly for use by desinstallation routine.
 155   virtual bool DeleteAll() = 0;
 156
 157   // options
 158     // we can automatically expand environment variables in the config entries
 159     // (this option is on by default, you can turn it on/off at any time)
 160   bool IsExpandingEnvVars() const { return m_bExpandEnvVars; }
 161   void SetExpandEnvVars(bool bDoIt = TRUE) { m_bExpandEnvVars = bDoIt; }
 162     // does expansion only if needed
 163   wxString ExpandEnvVars(const wxString& str) const
 164     { return IsExpandingEnvVars() ? wxExpandEnvVars(str) : str; }
 165
 166 protected:
 167   static bool IsImmutable(const char *szKey)
 168     { return *szKey == APPCONF_IMMUTABLE_PREFIX; }
 169
 170   // a handy little class which changes current path to the path of given entry
 171   // and restores it in dtor: so if you declare a local variable of this type,
 172   // you work in the entry directory and the path is automatically restored
 173   // when the function returns
 174   class PathChanger
 175   {
 176   public:
 177     // ctor/dtor do path changing/restorin
 178     PathChanger(const wxConfig *pContainer, const wxString& strEntry);
 179    ~PathChanger();
 180
 181     // get the key name
 182    const wxString& Name() const { return m_strName; }
 183
 184   private:
 185     wxConfig *m_pContainer;   // object we live in
 186     wxString  m_strName,      // name of entry (i.e. name only)
 187               m_strOldPath;   // saved path
 188     bool      m_bChanged;     // was the path changed?
 189   };
 190
 191 private:
 192   // are we doing automatic environment variable expansion?
 193   bool m_bExpandEnvVars;
 194
 195   // static variables
 196   static wxConfig *ms_pConfig;
 197 };
 198
 199 #endif  //_APPCONF_H
 200