include/wx/fileconf.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        fileconf.h
   3 // Purpose:     wxFileConfig derivation of wxConfigBase
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     07.04.98 (adapted from appconf.cpp)
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1997 Karsten Ballüder   &  Vadim Zeitlin
   9 //                       Ballueder@usa.net     <zeitlin@dptmaths.ens-cachan.fr>
  10 // Licence:     wxWindows license
  11 ///////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef   _FILECONF_H
  14 #define   _FILECONF_H
  15
  16 #ifdef __GNUG__
  17 #pragma interface "fileconf.h"
  18 #endif
  19
  20 #include "wx/defs.h"
  21
  22 #if wxUSE_CONFIG
  23
  24 #include "wx/textfile.h"
  25 #include "wx/string.h"
  26
  27 // ----------------------------------------------------------------------------
  28 // wxFileConfig
  29 // ----------------------------------------------------------------------------
  30
  31 /*
  32   wxFileConfig derives from base Config and implements file based config class,
  33   i.e. it uses ASCII disk files to store the information. These files are
  34   alternatively called INI, .conf or .rc in the documentation. They are
  35   organized in groups or sections, which can nest (i.e. a group contains
  36   subgroups, which contain their own subgroups &c). Each group has some
  37   number of entries, which are "key = value" pairs. More precisely, the format
  38   is:
  39
  40   # comments are allowed after either ';' or '#' (Win/UNIX standard)
  41
  42   # blank lines (as above) are ignored
  43
  44   # global entries are members of special (no name) top group
  45   written_for = Windows
  46   platform    = Linux
  47
  48   # the start of the group 'Foo'
  49   [Foo]                           # may put comments like this also
  50   # following 3 lines are entries
  51   key = value
  52   another_key = "  strings with spaces in the beginning should be quoted, \
  53                    otherwise the spaces are lost"
  54   last_key = but you don't have to put " normally (nor quote them, like here)
  55
  56   # subgroup of the group 'Foo'
  57   # (order is not important, only the name is: separator is '/', as in paths)
  58   [Foo/Bar]
  59   # entries prefixed with "!" are immutable, i.e. can't be changed if they are
  60   # set in the system-wide config file
  61   !special_key = value
  62   bar_entry = whatever
  63
  64   [Foo/Bar/Fubar]   # depth is (theoretically :-) unlimited
  65   # may have the same name as key in another section
  66   bar_entry = whatever not
  67
  68   You have {read/write/delete}Entry functions (guess what they do) and also
  69   setCurrentPath to select current group. enum{Subgroups/Entries} allow you
  70   to get all entries in the config file (in the current group). Finally,
  71   flush() writes immediately all changed entries to disk (otherwise it would
  72   be done automatically in dtor)
  73
  74   wxFileConfig manages not less than 2 config files for each program: global
  75   and local (or system and user if you prefer). Entries are read from both of
  76   them and the local entries override the global ones unless the latter is
  77   immutable (prefixed with '!') in which case a warning message is generated
  78   and local value is ignored. Of course, the changes are always written to local
  79   file only.
  80
  81   The names of these files can be specified in a number of ways. First of all,
  82   you can use the standard convention: using the ctor which takes 'strAppName'
  83   parameter will probably be sufficient for 90% of cases. If, for whatever
  84   reason you wish to use the files with some other names, you can always use the
  85   second ctor.
  86
  87   wxFileConfig also may automatically expand the values of environment variables
  88   in the entries it reads: for example, if you have an entry
  89     score_file = $HOME/.score
  90   a call to Read(&str, "score_file") will return a complete path to .score file
  91   unless the expansion was previousle disabled with SetExpandEnvVars(FALSE) call
  92   (it's on by default, the current status can be retrieved with
  93    IsExpandingEnvVars function).
  94 */
  95 class wxFileConfig;
  96 class ConfigGroup;
  97 class ConfigEntry;
  98
  99 // we store all lines of the local config file as a linked list in memory
 100 class LineList
 101 {
 102 public:
 103   void      SetNext(LineList *pNext)  { m_pNext = pNext; }
 104   void      SetPrev(LineList *pPrev)  { m_pPrev = pPrev; }
 105
 106   // ctor
 107   LineList(const wxString& str, LineList *pNext = (LineList *) NULL) : m_strLine(str)
 108     { SetNext(pNext); SetPrev((LineList *) NULL); }
 109
 110   //
 111   LineList *Next() const              { return m_pNext;  }
 112   LineList *Prev() const              { return m_pPrev;  }
 113
 114   //
 115   void SetText(const wxString& str) { m_strLine = str;  }
 116   const wxString& Text() const      { return m_strLine; }
 117
 118 private:
 119   wxString  m_strLine;      // line contents
 120   LineList *m_pNext,        // next node
 121            *m_pPrev;        // previous one
 122 };
 123
 124 class wxFileConfig : public wxConfigBase
 125 {
 126 public:
 127   // construct the "standard" full name for global (system-wide) and
 128   // local (user-specific) config files from the base file name.
 129   //
 130   // the following are the filenames returned by this functions:
 131   //            global                local
 132   // Unix   /etc/file.ext           ~/.file
 133   // Win    %windir%\file.ext   %USERPROFILE%\file.ext
 134   //
 135   // where file is the basename of szFile, ext is it's extension
 136   // or .conf (Unix) or .ini (Win) if it has none
 137   static wxString GetGlobalFileName(const wxChar *szFile);
 138   static wxString GetLocalFileName(const wxChar *szFile);
 139
 140   // ctor & dtor
 141     // New constructor: one size fits all. Specify wxCONFIG_USE_LOCAL_FILE or
 142     // wxCONFIG_USE_GLOBAL_FILE to say which files should be used.
 143   wxFileConfig(const wxString& appName,
 144                const wxString& vendorName = _T(""),
 145                const wxString& localFilename = _T(""),
 146                const wxString& globalFilename = _T(""),
 147                long style = wxCONFIG_USE_LOCAL_FILE);
 148
 149     // dtor will save unsaved data
 150   virtual ~wxFileConfig();
 151
 152   // implement inherited pure virtual functions
 153   virtual void SetPath(const wxString& strPath);
 154   virtual const wxString& GetPath() const { return m_strPath; }
 155
 156   virtual bool GetFirstGroup(wxString& str, long& lIndex) const;
 157   virtual bool GetNextGroup (wxString& str, long& lIndex) const;
 158   virtual bool GetFirstEntry(wxString& str, long& lIndex) const;
 159   virtual bool GetNextEntry (wxString& str, long& lIndex) const;
 160
 161   virtual size_t GetNumberOfEntries(bool bRecursive = FALSE) const;
 162   virtual size_t GetNumberOfGroups(bool bRecursive = FALSE) const;
 163
 164   virtual bool HasGroup(const wxString& strName) const;
 165   virtual bool HasEntry(const wxString& strName) const;
 166
 167   virtual bool Read(const wxString& key, wxString *pStr) const;
 168   virtual bool Read(const wxString& key, wxString *pStr, const wxString& defValue) const;
 169   virtual bool Read(const wxString& key, long *pl) const;
 170
 171   // The following are necessary to satisfy the compiler
 172   wxString Read(const wxString& key, const wxString& defVal) const
 173     { return wxConfigBase::Read(key, defVal); }
 174   bool Read(const wxString& key, long *pl, long defVal) const
 175     { return wxConfigBase::Read(key, pl, defVal); }
 176   long Read(const wxString& key, long defVal) const
 177     { return wxConfigBase::Read(key, defVal); }
 178   bool Read(const wxString& key, int *pi, int defVal) const
 179     { return wxConfigBase::Read(key, pi, defVal); }
 180   bool Read(const wxString& key, int *pi) const
 181     { return wxConfigBase::Read(key, pi); }
 182   bool Read(const wxString& key, double* val) const
 183     { return wxConfigBase::Read(key, val); }
 184   bool Read(const wxString& key, double* val, double defVal) const
 185     { return wxConfigBase::Read(key, val, defVal); }
 186   bool Read(const wxString& key, bool* val) const
 187     { return wxConfigBase::Read(key, val); }
 188   bool Read(const wxString& key, bool* val, bool defVal) const
 189     { return wxConfigBase::Read(key, val, defVal); }
 190
 191   virtual bool Write(const wxString& key, const wxString& szValue);
 192   virtual bool Write(const wxString& key, long lValue);
 193   bool Write(const wxString& key, double value)
 194     { return wxConfigBase::Write(key, value); }
 195   bool Write(const wxString& key, bool value)
 196     { return wxConfigBase::Write(key, value); }
 197
 198   virtual bool Flush(bool bCurrentOnly = FALSE);
 199
 200   virtual bool RenameEntry(const wxString& oldName, const wxString& newName);
 201   virtual bool RenameGroup(const wxString& oldName, const wxString& newName);
 202
 203   virtual bool DeleteEntry(const wxString& key, bool bGroupIfEmptyAlso);
 204   virtual bool DeleteGroup(const wxString& szKey);
 205   virtual bool DeleteAll();
 206
 207 public:
 208   // functions to work with this list
 209   LineList *LineListAppend(const wxString& str);
 210   LineList *LineListInsert(const wxString& str,
 211                            LineList *pLine);    // NULL => Prepend()
 212   void      LineListRemove(LineList *pLine);
 213   bool      LineListIsEmpty();
 214
 215 private:
 216   // GetXXXFileName helpers: return ('/' terminated) directory names
 217   static wxString GetGlobalDir();
 218   static wxString GetLocalDir();
 219
 220   // common part of all ctors (assumes that m_str{Local|Global}File are already
 221   // initialized
 222   void Init();
 223
 224   // common part of from dtor and DeleteAll
 225   void CleanUp();
 226
 227   // parse the whole file
 228   void Parse(wxTextFile& file, bool bLocal);
 229
 230   // the same as SetPath("/")
 231   void SetRootPath();
 232
 233   // member variables
 234   // ----------------
 235   LineList   *m_linesHead,        // head of the linked list
 236              *m_linesTail;        // tail
 237
 238   wxString    m_strLocalFile,     // local  file name passed to ctor
 239               m_strGlobalFile;    // global
 240   wxString    m_strPath;          // current path (not '/' terminated)
 241
 242   ConfigGroup *m_pRootGroup,      // the top (unnamed) group
 243               *m_pCurrentGroup;   // the current group
 244
 245 public:
 246   WX_DEFINE_SORTED_ARRAY(ConfigEntry *, ArrayEntries);
 247   WX_DEFINE_SORTED_ARRAY(ConfigGroup *, ArrayGroups);
 248 };
 249
 250 class ConfigEntry
 251 {
 252 private:
 253   ConfigGroup  *m_pParent;      // group that contains us
 254   wxString      m_strName,      // entry name
 255                 m_strValue;     //       value
 256   bool          m_bDirty,       // changed since last read?
 257                 m_bImmutable;   // can be overriden locally?
 258   int           m_nLine;        // used if m_pLine == NULL only
 259   LineList     *m_pLine;        // pointer to our line in the linked list
 260                                 // or NULL if it was found in global file
 261
 262 public:
 263   ConfigEntry(ConfigGroup *pParent, const wxString& strName, int nLine);
 264
 265   // simple accessors
 266   const wxString& Name()        const { return m_strName;    }
 267   const wxString& Value()       const { return m_strValue;   }
 268   ConfigGroup    *Group()       const { return m_pParent;    }
 269   bool            IsDirty()     const { return m_bDirty;     }
 270   bool            IsImmutable() const { return m_bImmutable; }
 271   bool            IsLocal()     const { return m_pLine != 0; }
 272   int             Line()        const { return m_nLine;      }
 273   LineList       *GetLine()     const { return m_pLine;      }
 274
 275   // modify entry attributes
 276   void SetValue(const wxString& strValue, bool bUser = TRUE);
 277   void SetDirty();
 278   void SetLine(LineList *pLine);
 279 };
 280
 281 class ConfigGroup
 282 {
 283 private:
 284   wxFileConfig *m_pConfig;        // config object we belong to
 285   ConfigGroup  *m_pParent;        // parent group (NULL for root group)
 286   wxFileConfig::ArrayEntries  m_aEntries;       // entries in this group
 287   wxFileConfig::ArrayGroups   m_aSubgroups;     // subgroups
 288   wxString      m_strName;        // group's name
 289   bool          m_bDirty;         // if FALSE => all subgroups are not dirty
 290   LineList     *m_pLine;          // pointer to our line in the linked list
 291   ConfigEntry  *m_pLastEntry;     // last entry/subgroup of this group in the
 292   ConfigGroup  *m_pLastGroup;     // local file (we insert new ones after it)
 293
 294   // DeleteSubgroupByName helper
 295   bool DeleteSubgroup(ConfigGroup *pGroup);
 296
 297 public:
 298   // ctor
 299   ConfigGroup(ConfigGroup *pParent, const wxString& strName, wxFileConfig *);
 300
 301   // dtor deletes all entries and subgroups also
 302   ~ConfigGroup();
 303
 304   // simple accessors
 305   const wxString& Name()    const { return m_strName; }
 306   ConfigGroup    *Parent()  const { return m_pParent; }
 307   wxFileConfig   *Config()  const { return m_pConfig; }
 308   bool            IsDirty() const { return m_bDirty;  }
 309
 310   const wxFileConfig::ArrayEntries& Entries() const { return m_aEntries;   }
 311   const wxFileConfig::ArrayGroups&  Groups()  const { return m_aSubgroups; }
 312   bool  IsEmpty() const { return Entries().IsEmpty() && Groups().IsEmpty(); }
 313
 314   // find entry/subgroup (NULL if not found)
 315   ConfigGroup *FindSubgroup(const wxChar *szName) const;
 316   ConfigEntry *FindEntry   (const wxChar *szName) const;
 317
 318   // delete entry/subgroup, return FALSE if doesn't exist
 319   bool DeleteSubgroupByName(const wxChar *szName);
 320   bool DeleteEntry(const wxChar *szName);
 321
 322   // create new entry/subgroup returning pointer to newly created element
 323   ConfigGroup *AddSubgroup(const wxString& strName);
 324   ConfigEntry *AddEntry   (const wxString& strName, int nLine = wxNOT_FOUND);
 325
 326   // will also recursively set parent's dirty flag
 327   void SetDirty();
 328   void SetLine(LineList *pLine);
 329
 330   // rename: no checks are done to ensure that the name is unique!
 331   void Rename(const wxString& newName);
 332
 333   //
 334   wxString GetFullName() const;
 335
 336   // get the last line belonging to an entry/subgroup of this group
 337   LineList *GetGroupLine();     // line which contains [group]
 338   LineList *GetLastEntryLine(); // after which our subgroups start
 339   LineList *GetLastGroupLine(); // after which the next group starts
 340
 341   // called by entries/subgroups when they're created/deleted
 342   void SetLastEntry(ConfigEntry *pEntry) { m_pLastEntry = pEntry; }
 343   void SetLastGroup(ConfigGroup *pGroup) { m_pLastGroup = pGroup; }
 344 };
 345
 346 #endif
 347   // wxUSE_CONFIG
 348
 349 #endif
 350   //_FILECONF_H
 351