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 = wxT(""),
 145                const wxString& localFilename = wxT(""),
 146                const wxString& globalFilename = wxT(""),
 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   bool Write(const wxString& key, const wxChar* value)
 198     { return wxConfigBase::Write(key, value); }
 199
 200   virtual bool Flush(bool bCurrentOnly = FALSE);
 201
 202   virtual bool RenameEntry(const wxString& oldName, const wxString& newName);
 203   virtual bool RenameGroup(const wxString& oldName, const wxString& newName);
 204
 205   virtual bool DeleteEntry(const wxString& key, bool bGroupIfEmptyAlso);
 206   virtual bool DeleteGroup(const wxString& szKey);
 207   virtual bool DeleteAll();
 208
 209 public:
 210   // functions to work with this list
 211   LineList *LineListAppend(const wxString& str);
 212   LineList *LineListInsert(const wxString& str,
 213                            LineList *pLine);    // NULL => Prepend()
 214   void      LineListRemove(LineList *pLine);
 215   bool      LineListIsEmpty();
 216
 217 private:
 218   // GetXXXFileName helpers: return ('/' terminated) directory names
 219   static wxString GetGlobalDir();
 220   static wxString GetLocalDir();
 221
 222   // common part of all ctors (assumes that m_str{Local|Global}File are already
 223   // initialized
 224   void Init();
 225
 226   // common part of from dtor and DeleteAll
 227   void CleanUp();
 228
 229   // parse the whole file
 230   void Parse(wxTextFile& file, bool bLocal);
 231
 232   // the same as SetPath("/")
 233   void SetRootPath();
 234
 235   // member variables
 236   // ----------------
 237   LineList   *m_linesHead,        // head of the linked list
 238              *m_linesTail;        // tail
 239
 240   wxString    m_strLocalFile,     // local  file name passed to ctor
 241               m_strGlobalFile;    // global
 242   wxString    m_strPath;          // current path (not '/' terminated)
 243
 244   ConfigGroup *m_pRootGroup,      // the top (unnamed) group
 245               *m_pCurrentGroup;   // the current group
 246
 247 public:
 248   WX_DEFINE_SORTED_ARRAY(ConfigEntry *, ArrayEntries);
 249   WX_DEFINE_SORTED_ARRAY(ConfigGroup *, ArrayGroups);
 250 };
 251
 252 class ConfigEntry
 253 {
 254 private:
 255   ConfigGroup  *m_pParent;      // group that contains us
 256   wxString      m_strName,      // entry name
 257                 m_strValue;     //       value
 258   bool          m_bDirty,       // changed since last read?
 259                 m_bImmutable;   // can be overriden locally?
 260   int           m_nLine;        // used if m_pLine == NULL only
 261   LineList     *m_pLine;        // pointer to our line in the linked list
 262                                 // or NULL if it was found in global file
 263
 264 public:
 265   ConfigEntry(ConfigGroup *pParent, const wxString& strName, int nLine);
 266
 267   // simple accessors
 268   const wxString& Name()        const { return m_strName;    }
 269   const wxString& Value()       const { return m_strValue;   }
 270   ConfigGroup    *Group()       const { return m_pParent;    }
 271   bool            IsDirty()     const { return m_bDirty;     }
 272   bool            IsImmutable() const { return m_bImmutable; }
 273   bool            IsLocal()     const { return m_pLine != 0; }
 274   int             Line()        const { return m_nLine;      }
 275   LineList       *GetLine()     const { return m_pLine;      }
 276
 277   // modify entry attributes
 278   void SetValue(const wxString& strValue, bool bUser = TRUE);
 279   void SetDirty();
 280   void SetLine(LineList *pLine);
 281 };
 282
 283 class ConfigGroup
 284 {
 285 private:
 286   wxFileConfig *m_pConfig;        // config object we belong to
 287   ConfigGroup  *m_pParent;        // parent group (NULL for root group)
 288   wxFileConfig::ArrayEntries  m_aEntries;       // entries in this group
 289   wxFileConfig::ArrayGroups   m_aSubgroups;     // subgroups
 290   wxString      m_strName;        // group's name
 291   bool          m_bDirty;         // if FALSE => all subgroups are not dirty
 292   LineList     *m_pLine;          // pointer to our line in the linked list
 293   ConfigEntry  *m_pLastEntry;     // last entry/subgroup of this group in the
 294   ConfigGroup  *m_pLastGroup;     // local file (we insert new ones after it)
 295
 296   // DeleteSubgroupByName helper
 297   bool DeleteSubgroup(ConfigGroup *pGroup);
 298
 299 public:
 300   // ctor
 301   ConfigGroup(ConfigGroup *pParent, const wxString& strName, wxFileConfig *);
 302
 303   // dtor deletes all entries and subgroups also
 304   ~ConfigGroup();
 305
 306   // simple accessors
 307   const wxString& Name()    const { return m_strName; }
 308   ConfigGroup    *Parent()  const { return m_pParent; }
 309   wxFileConfig   *Config()  const { return m_pConfig; }
 310   bool            IsDirty() const { return m_bDirty;  }
 311
 312   const wxFileConfig::ArrayEntries& Entries() const { return m_aEntries;   }
 313   const wxFileConfig::ArrayGroups&  Groups()  const { return m_aSubgroups; }
 314   bool  IsEmpty() const { return Entries().IsEmpty() && Groups().IsEmpty(); }
 315
 316   // find entry/subgroup (NULL if not found)
 317   ConfigGroup *FindSubgroup(const wxChar *szName) const;
 318   ConfigEntry *FindEntry   (const wxChar *szName) const;
 319
 320   // delete entry/subgroup, return FALSE if doesn't exist
 321   bool DeleteSubgroupByName(const wxChar *szName);
 322   bool DeleteEntry(const wxChar *szName);
 323
 324   // create new entry/subgroup returning pointer to newly created element
 325   ConfigGroup *AddSubgroup(const wxString& strName);
 326   ConfigEntry *AddEntry   (const wxString& strName, int nLine = wxNOT_FOUND);
 327
 328   // will also recursively set parent's dirty flag
 329   void SetDirty();
 330   void SetLine(LineList *pLine);
 331
 332   // rename: no checks are done to ensure that the name is unique!
 333   void Rename(const wxString& newName);
 334
 335   //
 336   wxString GetFullName() const;
 337
 338   // get the last line belonging to an entry/subgroup of this group
 339   LineList *GetGroupLine();     // line which contains [group]
 340   LineList *GetLastEntryLine(); // after which our subgroups start
 341   LineList *GetLastGroupLine(); // after which the next group starts
 342
 343   // called by entries/subgroups when they're created/deleted
 344   void SetLastEntry(ConfigEntry *pEntry) { m_pLastEntry = pEntry; }
 345   void SetLastGroup(ConfigGroup *pGroup) { m_pLastGroup = pGroup; }
 346 };
 347
 348 #endif
 349   // wxUSE_CONFIG
 350
 351 #endif
 352   //_FILECONF_H
 353