1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxFileConfig derivation of wxConfigBase
4 // Author: Vadim Zeitlin
6 // Created: 07.04.98 (adapted from appconf.cpp)
8 // Copyright: (c) 1997 Karsten Ballüder & Vadim Zeitlin
9 // Ballueder@usa.net <zeitlin@dptmaths.ens-cachan.fr>
10 // Licence: wxWindows licence
11 ///////////////////////////////////////////////////////////////////////////////
16 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
17 #pragma interface "fileconf.h"
24 #include "wx/textfile.h"
25 #include "wx/string.h"
26 #include "wx/confbase.h"
28 // ----------------------------------------------------------------------------
30 // ----------------------------------------------------------------------------
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
41 # comments are allowed after either ';' or '#' (Win/UNIX standard)
43 # blank lines (as above) are ignored
45 # global entries are members of special (no name) top group
49 # the start of the group 'Foo'
50 [Foo] # may put comments like this also
51 # following 3 lines are entries
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)
57 # subgroup of the group 'Foo'
58 # (order is not important, only the name is: separator is '/', as in paths)
60 # entries prefixed with "!" are immutable, i.e. can't be changed if they are
61 # set in the system-wide config file
65 [Foo/Bar/Fubar] # depth is (theoretically :-) unlimited
66 # may have the same name as key in another section
67 bar_entry = whatever not
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)
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
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
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).
96 class WXDLLIMPEXP_BASE wxFileConfigGroup
;
97 class WXDLLIMPEXP_BASE wxFileConfigEntry
;
98 class WXDLLIMPEXP_BASE wxFileConfigLineList
;
99 class WXDLLIMPEXP_BASE wxInputStream
;
101 class WXDLLIMPEXP_BASE wxFileConfig
: public wxConfigBase
104 // construct the "standard" full name for global (system-wide) and
105 // local (user-specific) config files from the base file name.
107 // the following are the filenames returned by this functions:
109 // Unix /etc/file.ext ~/.file
110 // Win %windir%\file.ext %USERPROFILE%\file.ext
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
);
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
| wxCONFIG_USE_GLOBAL_FILE
,
125 wxMBConv
& conv
= wxConvUTF8
);
128 // ctor that takes an input stream.
129 wxFileConfig(wxInputStream
&inStream
, wxMBConv
& conv
= wxConvUTF8
);
130 #endif // wxUSE_STREAMS
132 // dtor will save unsaved data
133 virtual ~wxFileConfig();
135 // under Unix, set the umask to be used for the file creation, do nothing
136 // under other systems
138 void SetUmask(int mode
) { m_umask
= mode
; }
140 void SetUmask(int WXUNUSED(mode
)) { }
141 #endif // __UNIX__/!__UNIX__
143 // implement inherited pure virtual functions
144 virtual void SetPath(const wxString
& strPath
);
145 virtual const wxString
& GetPath() const { return m_strPath
; }
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;
152 virtual size_t GetNumberOfEntries(bool bRecursive
= false) const;
153 virtual size_t GetNumberOfGroups(bool bRecursive
= false) const;
155 virtual bool HasGroup(const wxString
& strName
) const;
156 virtual bool HasEntry(const wxString
& strName
) const;
158 virtual bool Flush(bool bCurrentOnly
= false);
160 virtual bool RenameEntry(const wxString
& oldName
, const wxString
& newName
);
161 virtual bool RenameGroup(const wxString
& oldName
, const wxString
& newName
);
163 virtual bool DeleteEntry(const wxString
& key
, bool bGroupIfEmptyAlso
= true);
164 virtual bool DeleteGroup(const wxString
& szKey
);
165 virtual bool DeleteAll();
167 // additional, wxFileConfig-specific, functionality
169 // save the entire config file text to the given stream, note that the text
170 // won't be saved again in dtor when Flush() is called if you use this method
171 // as it won't be "changed" any more
172 virtual bool Save(wxOutputStream
& os
, wxMBConv
& conv
= wxConvUTF8
);
173 #endif // wxUSE_STREAMS
176 // functions to work with this list
177 wxFileConfigLineList
*LineListAppend(const wxString
& str
);
178 wxFileConfigLineList
*LineListInsert(const wxString
& str
,
179 wxFileConfigLineList
*pLine
); // NULL => Prepend()
180 void LineListRemove(wxFileConfigLineList
*pLine
);
181 bool LineListIsEmpty();
184 virtual bool DoReadString(const wxString
& key
, wxString
*pStr
) const;
185 virtual bool DoReadLong(const wxString
& key
, long *pl
) const;
187 virtual bool DoWriteString(const wxString
& key
, const wxString
& szValue
);
188 virtual bool DoWriteLong(const wxString
& key
, long lValue
);
191 // GetXXXFileName helpers: return ('/' terminated) directory names
192 static wxString
GetGlobalDir();
193 static wxString
GetLocalDir();
195 // common part of all ctors (assumes that m_str{Local|Global}File are already
199 // common part of from dtor and DeleteAll
202 // parse the whole file
203 void Parse(wxTextBuffer
& buffer
, bool bLocal
);
205 // the same as SetPath("/")
208 // set/test the dirty flag
209 void SetDirty() { m_isDirty
= true; }
210 void ResetDirty() { m_isDirty
= false; }
211 bool IsDirty() const { return m_isDirty
; }
216 wxFileConfigLineList
*m_linesHead
, // head of the linked list
217 *m_linesTail
; // tail
219 wxString m_strLocalFile
, // local file name passed to ctor
220 m_strGlobalFile
; // global
221 wxString m_strPath
; // current path (not '/' terminated)
223 wxFileConfigGroup
*m_pRootGroup
, // the top (unnamed) group
224 *m_pCurrentGroup
; // the current group
229 int m_umask
; // the umask to use for file creation
232 bool m_isDirty
; // if true, we have unsaved changes
234 DECLARE_NO_COPY_CLASS(wxFileConfig
)