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