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 char *szFile);
 144   static wxString GetLocalFileName(const char *szFile);
 145
 146   // ctor & dtor
 147
 148 #if 0
 149     // the names of local and global (if not disabled) config files are
 150     // constructed using Get{Local|Global}FileName functions described above
 151     // (szAppName is just the (short) name of your application)
 152   wxFileConfig(const char *szAppName, bool bLocalOnly = FALSE);
 153     // this ctor allows you to specify custom names for both files (if strGlobal
 154     // isn't a full path, it's considered to be relative to the standard
 155     // directory, i.e. /etc under Unix and %windir% under Windows, if strLocal
 156     // is not an absolute path, it's considered to be relative to the user's
 157     // directory). If either of strings is empty, the corresponding file is not
 158     // used.
 159   wxFileConfig(const wxString& strLocal, const wxString& strGlobal);
 160 #endif
 161
 162    // New constructor: one size fits all. Specify wxCONFIG_USE_LOCAL_FILE
 163    // or wxCONFIG_USE_GLOBAL_FILE to say which files should be used.
 164   wxFileConfig(const wxString& appName, const wxString& vendorName = "",
 165                const wxString& localFilename = "", const wxString& globalFilename = "",
 166                long style = wxCONFIG_USE_LOCAL_FILE);
 167
 168     // dtor will save unsaved data
 169   virtual ~wxFileConfig();
 170
 171   // implement inherited pure virtual functions
 172   virtual void SetPath(const wxString& strPath);
 173   virtual const wxString& GetPath() const { return m_strPath; }
 174
 175   virtual bool GetFirstGroup(wxString& str, long& lIndex) const;
 176   virtual bool GetNextGroup (wxString& str, long& lIndex) const;
 177   virtual bool GetFirstEntry(wxString& str, long& lIndex) const;
 178   virtual bool GetNextEntry (wxString& str, long& lIndex) const;
 179
 180   virtual size_t GetNumberOfEntries(bool bRecursive = FALSE) const;
 181   virtual size_t GetNumberOfGroups(bool bRecursive = FALSE) const;
 182
 183   virtual bool HasGroup(const wxString& strName) const;
 184   virtual bool HasEntry(const wxString& strName) const;
 185
 186   virtual bool Read(const wxString& key, wxString *pStr) const;
 187   virtual bool Read(const wxString& key, wxString *pStr, const wxString& defValue) const;
 188   virtual bool Read(const wxString& key, long *pl) const;
 189
 190   // The following are necessary to satisfy the compiler
 191   wxString Read(const wxString& key, const wxString& defVal) const
 192     { return wxConfigBase::Read(key, defVal); }
 193   bool Read(const wxString& key, long *pl, long defVal) const
 194     { return wxConfigBase::Read(key, pl, defVal); }
 195   long Read(const wxString& key, long defVal) const
 196     { return wxConfigBase::Read(key, defVal); }
 197   bool Read(const wxString& key, int *pi, int defVal) const
 198     { return wxConfigBase::Read(key, pi, defVal); }
 199   bool Read(const wxString& key, int *pi) const
 200     { return wxConfigBase::Read(key, pi); }
 201   bool Read(const wxString& key, double* val) const
 202     { return wxConfigBase::Read(key, val); }
 203   bool Read(const wxString& key, double* val, double defVal) const
 204     { return wxConfigBase::Read(key, val, defVal); }
 205   bool Read(const wxString& key, bool* val) const
 206     { return wxConfigBase::Read(key, val); }
 207   bool Read(const wxString& key, bool* val, bool defVal) const
 208     { return wxConfigBase::Read(key, val, defVal); }
 209
 210   virtual bool Write(const wxString& key, const wxString& szValue);
 211   virtual bool Write(const wxString& key, long lValue);
 212   bool Write(const wxString& key, double value)
 213     { return wxConfigBase::Write(key, value); }
 214   bool Write(const wxString& key, bool value)
 215     { return wxConfigBase::Write(key, value); }
 216
 217   virtual bool Flush(bool bCurrentOnly = FALSE);
 218
 219   virtual bool RenameEntry(const wxString& oldName, const wxString& newName);
 220   virtual bool RenameGroup(const wxString& oldName, const wxString& newName);
 221
 222   virtual bool DeleteEntry(const wxString& key, bool bGroupIfEmptyAlso);
 223   virtual bool DeleteGroup(const wxString& szKey);
 224   virtual bool DeleteAll();
 225
 226 public:
 227   // functions to work with this list
 228   LineList *LineListAppend(const wxString& str);
 229   LineList *LineListInsert(const wxString& str,
 230                            LineList *pLine);    // NULL => Prepend()
 231   void      LineListRemove(LineList *pLine);
 232   bool      LineListIsEmpty();
 233
 234 private:
 235   // GetXXXFileName helpers: return ('/' terminated) directory names
 236   static wxString GetGlobalDir();
 237   static wxString GetLocalDir();
 238
 239   // common part of all ctors (assumes that m_str{Local|Global}File are already
 240   // initialized
 241   void Init();
 242
 243   // common part of from dtor and DeleteAll
 244   void CleanUp();
 245
 246   // parse the whole file
 247   void Parse(wxTextFile& file, bool bLocal);
 248
 249   // the same as SetPath("/")
 250   void SetRootPath();
 251
 252   // member variables
 253   // ----------------
 254   LineList   *m_linesHead,        // head of the linked list
 255              *m_linesTail;        // tail
 256
 257   wxString    m_strLocalFile,     // local  file name passed to ctor
 258               m_strGlobalFile;    // global
 259   wxString    m_strPath;          // current path (not '/' terminated)
 260
 261   ConfigGroup *m_pRootGroup,      // the top (unnamed) group
 262               *m_pCurrentGroup;   // the current group
 263
 264 public:
 265   WX_DEFINE_SORTED_ARRAY(ConfigEntry *, ArrayEntries);
 266   WX_DEFINE_SORTED_ARRAY(ConfigGroup *, ArrayGroups);
 267 };
 268
 269 class ConfigEntry
 270 {
 271 private:
 272   ConfigGroup  *m_pParent;      // group that contains us
 273   wxString      m_strName,      // entry name
 274                 m_strValue;     //       value
 275   bool          m_bDirty,       // changed since last read?
 276                 m_bImmutable;   // can be overriden locally?
 277   int           m_nLine;        // used if m_pLine == NULL only
 278   LineList     *m_pLine;        // pointer to our line in the linked list
 279                                 // or NULL if it was found in global file
 280
 281 public:
 282   ConfigEntry(ConfigGroup *pParent, const wxString& strName, int nLine);
 283
 284   // simple accessors
 285   const wxString& Name()        const { return m_strName;    }
 286   const wxString& Value()       const { return m_strValue;   }
 287   ConfigGroup    *Group()       const { return m_pParent;    }
 288   bool            IsDirty()     const { return m_bDirty;     }
 289   bool            IsImmutable() const { return m_bImmutable; }
 290   bool            IsLocal()     const { return m_pLine != 0; }
 291   int             Line()        const { return m_nLine;      }
 292   LineList       *GetLine()     const { return m_pLine;      }
 293
 294   // modify entry attributes
 295   void SetValue(const wxString& strValue, bool bUser = TRUE);
 296   void SetDirty();
 297   void SetLine(LineList *pLine);
 298 };
 299
 300 class ConfigGroup
 301 {
 302 private:
 303   wxFileConfig *m_pConfig;        // config object we belong to
 304   ConfigGroup  *m_pParent;        // parent group (NULL for root group)
 305   wxFileConfig::ArrayEntries  m_aEntries;       // entries in this group
 306   wxFileConfig::ArrayGroups   m_aSubgroups;     // subgroups
 307   wxString      m_strName;        // group's name
 308   bool          m_bDirty;         // if FALSE => all subgroups are not dirty
 309   LineList     *m_pLine;          // pointer to our line in the linked list
 310   ConfigEntry  *m_pLastEntry;     // last entry/subgroup of this group in the
 311   ConfigGroup  *m_pLastGroup;     // local file (we insert new ones after it)
 312
 313   // DeleteSubgroupByName helper
 314   bool DeleteSubgroup(ConfigGroup *pGroup);
 315
 316 public:
 317   // ctor
 318   ConfigGroup(ConfigGroup *pParent, const wxString& strName, wxFileConfig *);
 319
 320   // dtor deletes all entries and subgroups also
 321   ~ConfigGroup();
 322
 323   // simple accessors
 324   const wxString& Name()    const { return m_strName; }
 325   ConfigGroup    *Parent()  const { return m_pParent; }
 326   wxFileConfig   *Config()  const { return m_pConfig; }
 327   bool            IsDirty() const { return m_bDirty;  }
 328
 329   const wxFileConfig::ArrayEntries& Entries() const { return m_aEntries;   }
 330   const wxFileConfig::ArrayGroups&  Groups()  const { return m_aSubgroups; }
 331   bool  IsEmpty() const { return Entries().IsEmpty() && Groups().IsEmpty(); }
 332
 333   // find entry/subgroup (NULL if not found)
 334   ConfigGroup *FindSubgroup(const char *szName) const;
 335   ConfigEntry *FindEntry   (const char *szName) const;
 336
 337   // delete entry/subgroup, return FALSE if doesn't exist
 338   bool DeleteSubgroupByName(const char *szName);
 339   bool DeleteEntry(const char *szName);
 340
 341   // create new entry/subgroup returning pointer to newly created element
 342   ConfigGroup *AddSubgroup(const wxString& strName);
 343   ConfigEntry *AddEntry   (const wxString& strName, int nLine = wxNOT_FOUND);
 344
 345   // will also recursively set parent's dirty flag
 346   void SetDirty();
 347   void SetLine(LineList *pLine);
 348
 349   // rename: no checks are done to ensure that the name is unique!
 350   void Rename(const wxString& newName);
 351
 352   //
 353   wxString GetFullName() const;
 354
 355   // get the last line belonging to an entry/subgroup of this group
 356   LineList *GetGroupLine();     // line which contains [group]
 357   LineList *GetLastEntryLine(); // after which our subgroups start
 358   LineList *GetLastGroupLine(); // after which the next group starts
 359
 360   // called by entries/subgroups when they're created/deleted
 361   void SetLastEntry(ConfigEntry *pEntry) { m_pLastEntry = pEntry; }
 362   void SetLastGroup(ConfigGroup *pGroup) { m_pLastGroup = pGroup; }
 363 };
 364
 365 #endif  //_FILECONF_H
 366