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