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