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