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 ExpandEnvVars(const wxString& str);
  64
  65 /*
  66   Split path into parts removing '..' in progress
  67  */
  68 extern void SplitPath(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() { }
  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
 112   // tests of existence
 113     // returns TRUE if the group by this name exists
 114   virtual bool HasGroup(const wxString& strName) const = 0;
 115     // same as above, but for an entry
 116   virtual bool HasEntry(const wxString& strName) const = 0;
 117     // returns TRUE if either a group or an entry with a given name exist
 118   bool Exists(const wxString& strName) const
 119     { return HasGroup(strName) || HasEntry(strName); }
 120
 121   // key access: returns TRUE if value was really read, FALSE if default used
 122   // (and if the key is not found the default value is returned.)
 123     // read a string from the key
 124   virtual bool Read(wxString *pStr, const char *szKey,
 125                     const char *szDefault = NULL) const = 0;
 126     // another version using statis buffer - it means it will be overwritten
 127     // after each call to this function!
 128   virtual const char *Read(const char *szKey,
 129                            const char *szDefault = NULL) const;
 130     // the same for longs
 131   virtual long Read(const char *szKey, long lDefault) const
 132     { long l; Read(&l, szKey, lDefault); return l; }
 133     // and another version: returns true if default value is returned
 134   virtual bool Read(long *pl, const char *szKey, long lDefault = 0) const = 0;
 135
 136     // write the value (return true on success)
 137   virtual bool Write(const char *szKey, const char *szValue) = 0;
 138   virtual bool Write(const char *szKey, long lValue) = 0;
 139     // permanently writes all changes
 140   virtual bool Flush(bool bCurrentOnly = FALSE) = 0;
 141
 142   // delete entries/groups
 143     // deletes the specified entry and the group it belongs to if
 144     // it was the last key in it and the second parameter is true
 145   virtual bool DeleteEntry(const char *szKey,
 146                            bool bDeleteGroupIfEmpty = TRUE) = 0;
 147     // delete the group (with all subgroups)
 148   virtual bool DeleteGroup(const char *szKey) = 0;
 149     // delete the whole underlying object (disk file, registry key, ...)
 150     // primarly for use by desinstallation routine.
 151   virtual bool DeleteAll() = 0;
 152
 153 protected:
 154   static bool IsImmutable(const char *szKey)
 155     { return *szKey == APPCONF_IMMUTABLE_PREFIX; }
 156
 157   // a handy little class which changes current path to the path of given entry
 158   // and restores it in dtor: so if you declare a local variable of this type,
 159   // you work in the entry directory and the path is automatically restored
 160   // when function returns
 161   class PathChanger
 162   {
 163   public:
 164     // ctor/dtor do path changing/restorin
 165     PathChanger(const wxConfig *pContainer, const wxString& strEntry);
 166    ~PathChanger();
 167
 168     // get the key name
 169    const wxString& Name() const { return m_strName; }
 170
 171   private:
 172     wxConfig *m_pContainer;   // object we live in
 173     wxString  m_strName,      // name of entry (i.e. name only)
 174               m_strOldPath;   // saved path
 175     bool      m_bChanged;     // was the path changed?
 176   };
 177
 178   // are we doing automatic environment variable expansion?
 179   bool m_bExpandEnvVars;
 180
 181   // static variables
 182   static wxConfig *ms_pConfig;
 183 };
 184
 185 #endif  //_APPCONF_H
 186