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