include/wx/fileconf.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/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
  22 #if wxUSE_CONFIG
  23
  24 #include "wx/textfile.h"
  25 #include "wx/string.h"
  26
  27 // ----------------------------------------------------------------------------
  28 // wxFileConfig
  29 // ----------------------------------------------------------------------------
  30
  31 /*
  32   wxFileConfig derives from base Config and implements file based config class,
  33   i.e. it uses ASCII disk files to store the information. These files are
  34   alternatively called INI, .conf or .rc in the documentation. They are
  35   organized in groups or sections, which can nest (i.e. a group contains
  36   subgroups, which contain their own subgroups &c). Each group has some
  37   number of entries, which are "key = value" pairs. More precisely, the format
  38   is:
  39
  40   # comments are allowed after either ';' or '#' (Win/UNIX standard)
  41
  42   # blank lines (as above) are ignored
  43
  44   # global entries are members of special (no name) top group
  45   written_for = Windows
  46   platform    = Linux
  47
  48   # the start of the group 'Foo'
  49   [Foo]                           # may put comments like this also
  50   # following 3 lines are entries
  51   key = value
  52   another_key = "  strings with spaces in the beginning should be quoted, \
  53                    otherwise the spaces are lost"
  54   last_key = but you don't have to put " normally (nor quote them, like here)
  55
  56   # subgroup of the group 'Foo'
  57   # (order is not important, only the name is: separator is '/', as in paths)
  58   [Foo/Bar]
  59   # entries prefixed with "!" are immutable, i.e. can't be changed if they are
  60   # set in the system-wide config file
  61   !special_key = value
  62   bar_entry = whatever
  63
  64   [Foo/Bar/Fubar]   # depth is (theoretically :-) unlimited
  65   # may have the same name as key in another section
  66   bar_entry = whatever not
  67
  68   You have {read/write/delete}Entry functions (guess what they do) and also
  69   setCurrentPath to select current group. enum{Subgroups/Entries} allow you
  70   to get all entries in the config file (in the current group). Finally,
  71   flush() writes immediately all changed entries to disk (otherwise it would
  72   be done automatically in dtor)
  73
  74   wxFileConfig manages not less than 2 config files for each program: global
  75   and local (or system and user if you prefer). Entries are read from both of
  76   them and the local entries override the global ones unless the latter is
  77   immutable (prefixed with '!') in which case a warning message is generated
  78   and local value is ignored. Of course, the changes are always written to local
  79   file only.
  80
  81   The names of these files can be specified in a number of ways. First of all,
  82   you can use the standard convention: using the ctor which takes 'strAppName'
  83   parameter will probably be sufficient for 90% of cases. If, for whatever
  84   reason you wish to use the files with some other names, you can always use the
  85   second ctor.
  86
  87   wxFileConfig also may automatically expand the values of environment variables
  88   in the entries it reads: for example, if you have an entry
  89     score_file = $HOME/.score
  90   a call to Read(&str, "score_file") will return a complete path to .score file
  91   unless the expansion was previousle disabled with SetExpandEnvVars(FALSE) call
  92   (it's on by default, the current status can be retrieved with
  93    IsExpandingEnvVars function).
  94 */
  95 class WXDLLEXPORT wxFileConfigGroup;
  96 class WXDLLEXPORT wxFileConfigEntry;
  97 class WXDLLEXPORT wxFileConfigLineList;
  98
  99 class WXDLLEXPORT wxFileConfig : public wxConfigBase
 100 {
 101 public:
 102   // construct the "standard" full name for global (system-wide) and
 103   // local (user-specific) config files from the base file name.
 104   //
 105   // the following are the filenames returned by this functions:
 106   //            global                local
 107   // Unix   /etc/file.ext           ~/.file
 108   // Win    %windir%\file.ext   %USERPROFILE%\file.ext
 109   //
 110   // where file is the basename of szFile, ext is it's extension
 111   // or .conf (Unix) or .ini (Win) if it has none
 112   static wxString GetGlobalFileName(const wxChar *szFile);
 113   static wxString GetLocalFileName(const wxChar *szFile);
 114
 115   // ctor & dtor
 116     // New constructor: one size fits all. Specify wxCONFIG_USE_LOCAL_FILE or
 117     // wxCONFIG_USE_GLOBAL_FILE to say which files should be used.
 118   wxFileConfig(const wxString& appName,
 119                const wxString& vendorName = wxT(""),
 120                const wxString& localFilename = wxT(""),
 121                const wxString& globalFilename = wxT(""),
 122                long style = wxCONFIG_USE_LOCAL_FILE);
 123
 124 #if wxUSE_STREAMS
 125     // ctor that takes an input stream.
 126   wxFileConfig(wxInputStream &inStream);
 127 #endif // wxUSE_STREAMS
 128
 129     // dtor will save unsaved data
 130   virtual ~wxFileConfig();
 131
 132   // under Unix, set the umask to be used for the file creation, do nothing
 133   // under other systems
 134 #ifdef __UNIX__
 135   void SetUmask(int mode) { m_umask = mode; }
 136 #else // !__UNIX__
 137   void SetUmask(int WXUNUSED(mode)) { }
 138 #endif // __UNIX__/!__UNIX__
 139
 140   // implement inherited pure virtual functions
 141   virtual void SetPath(const wxString& strPath);
 142   virtual const wxString& GetPath() const { return m_strPath; }
 143
 144   virtual bool GetFirstGroup(wxString& str, long& lIndex) const;
 145   virtual bool GetNextGroup (wxString& str, long& lIndex) const;
 146   virtual bool GetFirstEntry(wxString& str, long& lIndex) const;
 147   virtual bool GetNextEntry (wxString& str, long& lIndex) const;
 148
 149   virtual size_t GetNumberOfEntries(bool bRecursive = FALSE) const;
 150   virtual size_t GetNumberOfGroups(bool bRecursive = FALSE) const;
 151
 152   virtual bool HasGroup(const wxString& strName) const;
 153   virtual bool HasEntry(const wxString& strName) const;
 154
 155   virtual bool Read(const wxString& key, wxString *pStr) const;
 156   virtual bool Read(const wxString& key, wxString *pStr, const wxString& defValue) const;
 157   virtual bool Read(const wxString& key, long *pl) const;
 158
 159   // The following are necessary to satisfy the compiler
 160   wxString Read(const wxString& key, const wxString& defVal) const
 161     { return wxConfigBase::Read(key, defVal); }
 162   bool Read(const wxString& key, long *pl, long defVal) const
 163     { return wxConfigBase::Read(key, pl, defVal); }
 164   long Read(const wxString& key, long defVal) const
 165     { return wxConfigBase::Read(key, defVal); }
 166   bool Read(const wxString& key, int *pi, int defVal) const
 167     { return wxConfigBase::Read(key, pi, defVal); }
 168   bool Read(const wxString& key, int *pi) const
 169     { return wxConfigBase::Read(key, pi); }
 170   bool Read(const wxString& key, double* val) const
 171     { return wxConfigBase::Read(key, val); }
 172   bool Read(const wxString& key, double* val, double defVal) const
 173     { return wxConfigBase::Read(key, val, defVal); }
 174   bool Read(const wxString& key, bool* val) const
 175     { return wxConfigBase::Read(key, val); }
 176   bool Read(const wxString& key, bool* val, bool defVal) const
 177     { return wxConfigBase::Read(key, val, defVal); }
 178
 179   virtual bool Write(const wxString& key, const wxString& szValue);
 180   virtual bool Write(const wxString& key, long lValue);
 181   bool Write(const wxString& key, double value)
 182     { return wxConfigBase::Write(key, value); }
 183   bool Write(const wxString& key, bool value)
 184     { return wxConfigBase::Write(key, value); }
 185   bool Write(const wxString& key, const wxChar* value)
 186     { return wxConfigBase::Write(key, value); }
 187
 188   virtual bool Flush(bool bCurrentOnly = FALSE);
 189
 190   virtual bool RenameEntry(const wxString& oldName, const wxString& newName);
 191   virtual bool RenameGroup(const wxString& oldName, const wxString& newName);
 192
 193   virtual bool DeleteEntry(const wxString& key, bool bGroupIfEmptyAlso);
 194   virtual bool DeleteGroup(const wxString& szKey);
 195   virtual bool DeleteAll();
 196
 197 public:
 198   // functions to work with this list
 199   wxFileConfigLineList *LineListAppend(const wxString& str);
 200   wxFileConfigLineList *LineListInsert(const wxString& str,
 201                            wxFileConfigLineList *pLine);    // NULL => Prepend()
 202   void      LineListRemove(wxFileConfigLineList *pLine);
 203   bool      LineListIsEmpty();
 204
 205 private:
 206   // GetXXXFileName helpers: return ('/' terminated) directory names
 207   static wxString GetGlobalDir();
 208   static wxString GetLocalDir();
 209
 210   // common part of all ctors (assumes that m_str{Local|Global}File are already
 211   // initialized
 212   void Init();
 213
 214   // common part of from dtor and DeleteAll
 215   void CleanUp();
 216
 217   // parse the whole file
 218   void Parse(wxTextBuffer& buffer, bool bLocal);
 219
 220   // the same as SetPath("/")
 221   void SetRootPath();
 222
 223   // member variables
 224   // ----------------
 225   wxFileConfigLineList *m_linesHead,        // head of the linked list
 226                        *m_linesTail;        // tail
 227
 228   wxString    m_strLocalFile,     // local  file name passed to ctor
 229               m_strGlobalFile;    // global
 230   wxString    m_strPath;          // current path (not '/' terminated)
 231
 232   wxFileConfigGroup *m_pRootGroup,      // the top (unnamed) group
 233                     *m_pCurrentGroup;   // the current group
 234
 235 #ifdef __UNIX__
 236   int m_umask;                    // the umask to use for file creation
 237 #endif // __UNIX__
 238 };
 239
 240 #endif
 241   // wxUSE_CONFIG
 242
 243 #endif
 244   //_FILECONF_H
 245