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