include/wx/fileconf.h

   1 /*****************************************************************************\
   2  * Project:   CppLib: C++ library for Windows/UNIX platfroms                 *
   3  * File:      fileconf.h - file based implementation of Config               *
   4  *---------------------------------------------------------------------------*
   5  * Language:  C++                                                            *
   6  * Platfrom:  Any                                                            *
   7  *---------------------------------------------------------------------------*
   8  * Classes:                                                                  *
   9  *---------------------------------------------------------------------------*
  10  * Author:    Vadim Zeitlin zeitlin@dptmaths.ens-cachan.fr>                  *
  11  *            adapted from earlier class by VZ & Karsten Ballüder            *
  12  * History:                                                                  *
  13  *  27.04.98  created                                                        *
  14 \*****************************************************************************/
  15
  16 #ifndef   _FILECONF_H
  17 #define   _FILECONF_H
  18
  19 #ifdef __GNUG__
  20 #pragma interface "fileconf.h"
  21 #endif
  22
  23 // ----------------------------------------------------------------------------
  24 // compile options
  25 // ----------------------------------------------------------------------------
  26
  27 // it won't compile without it anyhow
  28 #ifndef USE_WXCONFIG
  29   #error "Please define USE_WXCONFIG or remove fileconf.cpp from your makefile"
  30 #endif // USE_WXCONFIG
  31
  32 // ----------------------------------------------------------------------------
  33 // wxFileConfig
  34 // ----------------------------------------------------------------------------
  35
  36 /*
  37   wxFileConfig derives from base Config and implements file based config class,
  38   i.e. it uses ASCII disk files to store the information. These files are
  39   alternatively called INI, .conf or .rc in the documentation. They are
  40   organized in groups or sections, which can nest (i.e. a group contains
  41   subgroups, which contain their own subgroups &c). Each group has some
  42   number of entries, which are "key = value" pairs. More precisely, the format
  43   is:
  44
  45   # comments are allowed after either ';' or '#' (Win/UNIX standard)
  46
  47   # blank lines (as above) are ignored
  48
  49   # global entries are members of special (no name) top group
  50   written_for = Windows
  51   platform    = Linux
  52
  53   # the start of the group 'Foo'
  54   [Foo]                           # may put comments like this also
  55   # following 3 lines are entries
  56   key = value
  57   another_key = "  strings with spaces in the beginning should be quoted, \
  58                    otherwise the spaces are lost"
  59   last_key = but you don't have to put " normally (nor quote them, like here)
  60
  61   # subgroup of the group 'Foo'
  62   # (order is not important, only the name is: separator is '/', as in paths)
  63   [Foo/Bar]
  64   # entries prefixed with "!" are immutable, i.e. can't be changed if they are
  65   # set in the system-wide config file
  66   !special_key = value
  67   bar_entry = whatever
  68
  69   [Foo/Bar/Fubar]   # depth is (theoretically :-) unlimited
  70   # may have the same name as key in another section
  71   bar_entry = whatever not
  72
  73   You have {read/write/delete}Entry functions (guess what they do) and also
  74   setCurrentPath to select current group. enum{Subgroups/Entries} allow you
  75   to get all entries in the config file (in the current group). Finally,
  76   flush() writes immediately all changed entries to disk (otherwise it would
  77   be done automatically in dtor)
  78
  79   wxFileConfig manages not less than 2 config files for each program: global
  80   and local (or system and user if you prefer). Entries are read from both of
  81   them and the local entries override the global ones unless the latter is
  82   immutable (prefixed with '!') in which case a warning message is generated
  83   and local value is ignored. Of course, the changes are always written to local
  84   file only.
  85
  86   @@@@ describe environment variable expansion
  87 */
  88
  89 class wxFileConfig : public wxConfig
  90 {
  91 public:
  92   // construct the "standard" full name for global (system-wide) and
  93   // local (user-specific) config files from the base file name.
  94   //
  95   // the following are the filenames returned by this functions:
  96   //            global                local
  97   // Unix   /etc/file.ext           ~/.file
  98   // Win    %windir%\file.ext   %USERPROFILE%\file.ext
  99   //
 100   // where file is the basename of szFile, ext is it's extension
 101   // or .conf (Unix) or .ini (Win) if it has none
 102   static wxString GetGlobalFileName(const char *szFile);
 103   static wxString GetLocalFileName(const char *szFile);
 104
 105   // ctor & dtor
 106     // if strGlobal is empty, only local config file is used
 107   wxFileConfig(const wxString& strLocal,
 108                const wxString& strGlobal = "");
 109     // dtor will save unsaved data
 110   virtual ~wxFileConfig();
 111
 112   // implement inherited pure virtual functions
 113   virtual void SetPath(const wxString& strPath);
 114   virtual const wxString& GetPath() const { return m_strPath; }
 115
 116   virtual bool GetFirstGroup(wxString& str, long& lIndex);
 117   virtual bool GetNextGroup (wxString& str, long& lIndex);
 118   virtual bool GetFirstEntry(wxString& str, long& lIndex);
 119   virtual bool GetNextEntry (wxString& str, long& lIndex);
 120
 121   virtual bool Read(wxString *pstr, const char *szKey,
 122                     const char *szDefault = 0) const;
 123   virtual const char *Read(const char *szKey,
 124                            const char *szDefault = 0) const;
 125   virtual bool Read(long *pl, const char *szKey, long lDefault) const;
 126   virtual bool Write(const char *szKey, const char *szValue);
 127   virtual bool Write(const char *szKey, long lValue);
 128   virtual bool Flush(bool bCurrentOnly = FALSE);
 129
 130   virtual bool DeleteEntry(const char *szKey, bool bGroupIfEmptyAlso);
 131   virtual bool DeleteGroup(const char *szKey);
 132   virtual bool DeleteAll();
 133
 134 public:
 135   // fwd decl
 136   class ConfigGroup;
 137   class ConfigEntry;
 138
 139   // we store all lines of the local config file as a linked list in memory
 140   class LineList
 141   {
 142   public:
 143     // ctor
 144     LineList(const wxString& str, LineList *pNext = NULL) : m_strLine(str)
 145       { SetNext(pNext); }
 146
 147     //
 148     LineList *Next() const              { return m_pNext;  }
 149     void      SetNext(LineList *pNext)  { m_pNext = pNext; }
 150
 151     //
 152     void SetText(const wxString& str) { m_strLine = str;  }
 153     const wxString& Text() const      { return m_strLine; }
 154
 155   private:
 156     wxString  m_strLine;      // line contents
 157     LineList *m_pNext;        // next node
 158   };
 159
 160   // functions to work with this list
 161   LineList *LineListAppend(const wxString& str);
 162   LineList *LineListInsert(const wxString& str,
 163                            LineList *pLine);    // NULL => Append()
 164   bool      LineListIsEmpty();
 165
 166 private:
 167   // put the object in the initial state
 168   void Init();
 169
 170   // parse the whole file
 171   void Parse(wxTextFile& file, bool bLocal);
 172
 173   // the same as SetPath("/")
 174   void SetRootPath();
 175
 176   // member variables
 177   // ----------------
 178   LineList   *m_linesHead,        // head of the linked list
 179              *m_linesTail;        // tail
 180
 181   wxString    m_strLocalFile,     // local  file name passed to ctor
 182               m_strGlobalFile;    // global
 183   wxString    m_strPath;          // current path (not '/' terminated)
 184
 185   ConfigGroup *m_pRootGroup,      // the top (unnamed) group
 186               *m_pCurrentGroup;   // the current group
 187
 188 //protected: --- if wxFileConfig::ConfigEntry is not public, functions in
 189 //               ConfigGroup such as Find/AddEntry can't return "ConfigEntry *"
 190 public:
 191   WX_DEFINE_ARRAY(ConfigEntry *, ArrayEntries);
 192   WX_DEFINE_ARRAY(ConfigGroup *, ArrayGroups);
 193
 194   class ConfigEntry
 195   {
 196   private:
 197     ConfigGroup  *m_pParent;      // group that contains us
 198     wxString      m_strName,      // entry name
 199                   m_strValue;     //       value
 200     bool          m_bDirty,       // changed since last read?
 201                   m_bImmutable;   // can be overriden locally?
 202     int           m_nLine;        // used if m_pLine == NULL only
 203     LineList     *m_pLine;        // pointer to our line in the linked list
 204                                   // or NULL if it was found in global file
 205
 206   public:
 207     ConfigEntry(ConfigGroup *pParent, const wxString& strName, int nLine);
 208
 209     // simple accessors
 210     const wxString& Name()        const { return m_strName;    }
 211     const wxString& Value()       const { return m_strValue;   }
 212     ConfigGroup    *Group()       const { return m_pParent;    }
 213     bool            IsDirty()     const { return m_bDirty;     }
 214     bool            IsImmutable() const { return m_bImmutable; }
 215     bool            IsLocal()     const { return m_pLine != 0; }
 216     int             Line()        const { return m_nLine;      }
 217     LineList       *GetLine()     const { return m_pLine;      }
 218
 219     // modify entry attributes
 220     void SetValue(const wxString& strValue, bool bUser = TRUE);
 221     void SetDirty();
 222     void SetLine(LineList *pLine);
 223   };
 224
 225 protected:
 226   class ConfigGroup
 227   {
 228   private:
 229     wxFileConfig *m_pConfig;      // config object we belong to
 230     ConfigGroup  *m_pParent;      // parent group (NULL for root group)
 231     ArrayEntries  m_aEntries;     // entries in this group
 232     ArrayGroups   m_aSubgroups;   // subgroups
 233     wxString      m_strName;      // group's name
 234     bool          m_bDirty;       // if FALSE => all subgroups are not dirty
 235     LineList     *m_pLine;        // pointer to our line in the linked list
 236     ConfigEntry  *m_pLastEntry;   // last entry of this group in the local file
 237     ConfigGroup  *m_pLastGroup;   // last subgroup
 238
 239   public:
 240     // ctor
 241     ConfigGroup(ConfigGroup *pParent, const wxString& strName, wxFileConfig *);
 242
 243     // dtor deletes all entries and subgroups also
 244     ~ConfigGroup();
 245
 246     // simple accessors
 247     const wxString& Name()    const { return m_strName; }
 248     ConfigGroup    *Parent()  const { return m_pParent; }
 249     wxFileConfig   *Config()  const { return m_pConfig; }
 250     bool            IsDirty() const { return m_bDirty;  }
 251
 252     bool  IsEmpty() const { return Entries().IsEmpty() && Groups().IsEmpty(); }
 253     const ArrayEntries& Entries() const { return m_aEntries;   }
 254     const ArrayGroups&  Groups()  const { return m_aSubgroups; }
 255
 256     // find entry/subgroup (NULL if not found)
 257     ConfigGroup *FindSubgroup(const char *szName) const;
 258     ConfigEntry *FindEntry   (const char *szName) const;
 259
 260     // delete entry/subgroup, return FALSE if doesn't exist
 261     bool DeleteSubgroup(const char *szName);
 262     bool DeleteEntry(const char *szName);
 263
 264     // create new entry/subgroup returning pointer to newly created element
 265     ConfigGroup *AddSubgroup(const wxString& strName);
 266     ConfigEntry *AddEntry   (const wxString& strName, int nLine = NOT_FOUND);
 267
 268     // will also recursively set parent's dirty flag
 269     void SetDirty();
 270     void SetLine(LineList *pLine);
 271
 272     // the new entries in this subgroup will be inserted after the last subgroup
 273     // or, if there is none, after the last entry
 274     void SetLastEntry(ConfigEntry *pLastEntry) { m_pLastEntry = pLastEntry; }
 275     void SetLastGroup(ConfigGroup *pLastGroup) { m_pLastGroup = pLastGroup; }
 276
 277     wxString GetFullName() const;
 278
 279     // get the last line belonging to an entry/subgroup of this group
 280     LineList *GetGroupLine();
 281     LineList *GetLastEntryLine();
 282     LineList *GetLastGroupLine();
 283   };
 284 };
 285
 286 #endif  //_FILECONF_H
 287