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