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 // ----------------------------------------------------------------------------
  21 // compile options
  22 // ----------------------------------------------------------------------------
  23
  24 // it won't compile without it anyhow
  25 #ifndef USE_WXCONFIG
  26   #error "Please define USE_WXCONFIG or remove fileconf.cpp from your makefile"
  27 #endif // USE_WXCONFIG
  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 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     // the names of local and global (if not disabled) config files are
 116     // constructed using Get{Local|Global}FileName functions described above
 117     // (szAppName is just the (short) name of your application)
 118   wxFileConfig(const char *szAppName, bool bLocalOnly = FALSE);
 119     // this ctor allows you to specify custom names for both files (if strGlobal
 120     // isn't a full path, it's considered to be relative to the standard
 121     // directory, i.e. /etc under Unix and %windir% under Windows, if strLocal
 122     // is not an absolute path, it's considered to be relative to the user's
 123     // directory). If either of strings is empty, the corresponding file is not
 124     // used.
 125   wxFileConfig(const wxString& strLocal, const wxString& strGlobal);
 126     // dtor will save unsaved data
 127   virtual ~wxFileConfig();
 128
 129   // implement inherited pure virtual functions
 130   virtual void SetPath(const wxString& strPath);
 131   virtual const wxString& GetPath() const { return m_strPath; }
 132
 133   virtual bool GetFirstGroup(wxString& str, long& lIndex) const;
 134   virtual bool GetNextGroup (wxString& str, long& lIndex) const;
 135   virtual bool GetFirstEntry(wxString& str, long& lIndex) const;
 136   virtual bool GetNextEntry (wxString& str, long& lIndex) const;
 137
 138   virtual size_t GetNumberOfEntries(bool bRecursive = FALSE) const;
 139   virtual size_t GetNumberOfGroups(bool bRecursive = FALSE) const;
 140
 141   virtual bool HasGroup(const wxString& strName) const;
 142   virtual bool HasEntry(const wxString& strName) const;
 143
 144   virtual bool Read(wxString *pstr, const char *szKey,
 145                     const char *szDefault = 0) const;
 146   virtual const char *Read(const char *szKey,
 147                            const char *szDefault = 0) const;
 148   virtual bool Read(long *pl, const char *szKey, long lDefault) const;
 149   virtual long Read(const char *szKey, long lDefault) const
 150     { return wxConfigBase::Read(szKey, lDefault); }
 151   virtual bool Write(const char *szKey, const char *szValue);
 152   virtual bool Write(const char *szKey, long lValue);
 153   virtual bool Flush(bool bCurrentOnly = FALSE);
 154
 155   virtual bool DeleteEntry(const char *szKey, bool bGroupIfEmptyAlso);
 156   virtual bool DeleteGroup(const char *szKey);
 157   virtual bool DeleteAll();
 158
 159 public:
 160   // fwd decl
 161   class ConfigGroup;
 162   class ConfigEntry;
 163
 164   // we store all lines of the local config file as a linked list in memory
 165   class LineList
 166   {
 167   public:
 168     // ctor
 169     LineList(const wxString& str, LineList *pNext = NULL) : m_strLine(str)
 170       { SetNext(pNext); SetPrev(NULL); }
 171
 172     //
 173     LineList *Next() const              { return m_pNext;  }
 174     LineList *Prev() const              { return m_pPrev;  }
 175     void      SetNext(LineList *pNext)  { m_pNext = pNext; }
 176     void      SetPrev(LineList *pPrev)  { m_pPrev = pPrev; }
 177
 178     //
 179     void SetText(const wxString& str) { m_strLine = str;  }
 180     const wxString& Text() const      { return m_strLine; }
 181
 182   private:
 183     wxString  m_strLine;      // line contents
 184     LineList *m_pNext,        // next node
 185              *m_pPrev;        // previous one
 186   };
 187
 188   // functions to work with this list
 189   LineList *LineListAppend(const wxString& str);
 190   LineList *LineListInsert(const wxString& str,
 191                            LineList *pLine);    // NULL => Prepend()
 192   void      LineListRemove(LineList *pLine);
 193   bool      LineListIsEmpty();
 194
 195 private:
 196   // GetXXXFileame helpers: return ('/' terminated) directory names
 197   static wxString GetGlobalDir();
 198   static wxString GetLocalDir();
 199
 200   // common part of all ctors (assumes that m_str{Local|Global}File are already
 201   // initialized
 202   void Init();
 203
 204   // common part of from dtor and DeleteAll
 205   void CleanUp();
 206
 207   // parse the whole file
 208   void Parse(wxTextFile& file, bool bLocal);
 209
 210   // the same as SetPath("/")
 211   void SetRootPath();
 212
 213   // member variables
 214   // ----------------
 215   LineList   *m_linesHead,        // head of the linked list
 216              *m_linesTail;        // tail
 217
 218   wxString    m_strLocalFile,     // local  file name passed to ctor
 219               m_strGlobalFile;    // global
 220   wxString    m_strPath;          // current path (not '/' terminated)
 221
 222   ConfigGroup *m_pRootGroup,      // the top (unnamed) group
 223               *m_pCurrentGroup;   // the current group
 224
 225 //protected: --- if wxFileConfig::ConfigEntry is not public, functions in
 226 //               ConfigGroup such as Find/AddEntry can't return "ConfigEntry *"
 227 public:
 228   WX_DEFINE_SORTED_ARRAY(ConfigEntry *, ArrayEntries);
 229   WX_DEFINE_SORTED_ARRAY(ConfigGroup *, ArrayGroups);
 230
 231   class ConfigEntry
 232   {
 233   private:
 234     ConfigGroup  *m_pParent;      // group that contains us
 235     wxString      m_strName,      // entry name
 236                   m_strValue;     //       value
 237     bool          m_bDirty,       // changed since last read?
 238                   m_bImmutable;   // can be overriden locally?
 239     int           m_nLine;        // used if m_pLine == NULL only
 240     LineList     *m_pLine;        // pointer to our line in the linked list
 241                                   // or NULL if it was found in global file
 242
 243   public:
 244     ConfigEntry(ConfigGroup *pParent, const wxString& strName, int nLine);
 245
 246     // simple accessors
 247     const wxString& Name()        const { return m_strName;    }
 248     const wxString& Value()       const { return m_strValue;   }
 249     ConfigGroup    *Group()       const { return m_pParent;    }
 250     bool            IsDirty()     const { return m_bDirty;     }
 251     bool            IsImmutable() const { return m_bImmutable; }
 252     bool            IsLocal()     const { return m_pLine != 0; }
 253     int             Line()        const { return m_nLine;      }
 254     LineList       *GetLine()     const { return m_pLine;      }
 255
 256     // modify entry attributes
 257     void SetValue(const wxString& strValue, bool bUser = TRUE);
 258     void SetDirty();
 259     void SetLine(LineList *pLine);
 260   };
 261
 262   class ConfigGroup
 263   {
 264   private:
 265     wxFileConfig *m_pConfig;        // config object we belong to
 266     ConfigGroup  *m_pParent;        // parent group (NULL for root group)
 267     ArrayEntries  m_aEntries;       // entries in this group
 268     ArrayGroups   m_aSubgroups;     // subgroups
 269     wxString      m_strName;        // group's name
 270     bool          m_bDirty;         // if FALSE => all subgroups are not dirty
 271     LineList     *m_pLine;          // pointer to our line in the linked list
 272     ConfigEntry  *m_pLastEntry;     // last entry/subgroup of this group in the
 273     ConfigGroup  *m_pLastGroup;     // local file (we insert new ones after it)
 274
 275     // DeleteSubgroupByName helper
 276     bool DeleteSubgroup(ConfigGroup *pGroup);
 277
 278   public:
 279     // ctor
 280     ConfigGroup(ConfigGroup *pParent, const wxString& strName, wxFileConfig *);
 281
 282     // dtor deletes all entries and subgroups also
 283     ~ConfigGroup();
 284
 285     // simple accessors
 286     const wxString& Name()    const { return m_strName; }
 287     ConfigGroup    *Parent()  const { return m_pParent; }
 288     wxFileConfig   *Config()  const { return m_pConfig; }
 289     bool            IsDirty() const { return m_bDirty;  }
 290
 291     bool  IsEmpty() const { return Entries().IsEmpty() && Groups().IsEmpty(); }
 292     const ArrayEntries& Entries() const { return m_aEntries;   }
 293     const ArrayGroups&  Groups()  const { return m_aSubgroups; }
 294
 295     // find entry/subgroup (NULL if not found)
 296     ConfigGroup *FindSubgroup(const char *szName) const;
 297     ConfigEntry *FindEntry   (const char *szName) const;
 298
 299     // delete entry/subgroup, return FALSE if doesn't exist
 300     bool DeleteSubgroupByName(const char *szName);
 301     bool DeleteEntry(const char *szName);
 302
 303     // create new entry/subgroup returning pointer to newly created element
 304     ConfigGroup *AddSubgroup(const wxString& strName);
 305     ConfigEntry *AddEntry   (const wxString& strName, int nLine = NOT_FOUND);
 306
 307     // will also recursively set parent's dirty flag
 308     void SetDirty();
 309     void SetLine(LineList *pLine);
 310
 311     //
 312     wxString GetFullName() const;
 313
 314     // get the last line belonging to an entry/subgroup of this group
 315     LineList *GetGroupLine();     // line which contains [group]
 316     LineList *GetLastEntryLine(); // after which our subgroups start
 317     LineList *GetLastGroupLine(); // after which the next group starts
 318
 319     // called by entries/subgroups when they're created/deleted
 320     void SetLastEntry(ConfigEntry *pEntry) { m_pLastEntry = pEntry; }
 321     void SetLastGroup(ConfigGroup *pGroup) { m_pLastGroup = pGroup; }
 322   };
 323 };
 324
 325 #endif  //_FILECONF_H
 326