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