fixed the last of the off-by-one errors (some are refixed, again...)
[wxWidgets.git] / 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 // dtor will save unsaved data
125 virtual ~wxFileConfig();
126
127 // under Unix, set the umask to be used for the file creation, do nothing
128 // under other systems
129 #ifdef __UNIX__
130 void SetUmask(int mode) { m_umask = mode; }
131 #else // !__UNIX__
132 void SetUmask(int WXUNUSED(mode)) { }
133 #endif // __UNIX__/!__UNIX__
134
135 // implement inherited pure virtual functions
136 virtual void SetPath(const wxString& strPath);
137 virtual const wxString& GetPath() const { return m_strPath; }
138
139 virtual bool GetFirstGroup(wxString& str, long& lIndex) const;
140 virtual bool GetNextGroup (wxString& str, long& lIndex) const;
141 virtual bool GetFirstEntry(wxString& str, long& lIndex) const;
142 virtual bool GetNextEntry (wxString& str, long& lIndex) const;
143
144 virtual size_t GetNumberOfEntries(bool bRecursive = FALSE) const;
145 virtual size_t GetNumberOfGroups(bool bRecursive = FALSE) const;
146
147 virtual bool HasGroup(const wxString& strName) const;
148 virtual bool HasEntry(const wxString& strName) const;
149
150 virtual bool Read(const wxString& key, wxString *pStr) const;
151 virtual bool Read(const wxString& key, wxString *pStr, const wxString& defValue) const;
152 virtual bool Read(const wxString& key, long *pl) const;
153
154 // The following are necessary to satisfy the compiler
155 wxString Read(const wxString& key, const wxString& defVal) const
156 { return wxConfigBase::Read(key, defVal); }
157 bool Read(const wxString& key, long *pl, long defVal) const
158 { return wxConfigBase::Read(key, pl, defVal); }
159 long Read(const wxString& key, long defVal) const
160 { return wxConfigBase::Read(key, defVal); }
161 bool Read(const wxString& key, int *pi, int defVal) const
162 { return wxConfigBase::Read(key, pi, defVal); }
163 bool Read(const wxString& key, int *pi) const
164 { return wxConfigBase::Read(key, pi); }
165 bool Read(const wxString& key, double* val) const
166 { return wxConfigBase::Read(key, val); }
167 bool Read(const wxString& key, double* val, double defVal) const
168 { return wxConfigBase::Read(key, val, defVal); }
169 bool Read(const wxString& key, bool* val) const
170 { return wxConfigBase::Read(key, val); }
171 bool Read(const wxString& key, bool* val, bool defVal) const
172 { return wxConfigBase::Read(key, val, defVal); }
173
174 virtual bool Write(const wxString& key, const wxString& szValue);
175 virtual bool Write(const wxString& key, long lValue);
176 bool Write(const wxString& key, double value)
177 { return wxConfigBase::Write(key, value); }
178 bool Write(const wxString& key, bool value)
179 { return wxConfigBase::Write(key, value); }
180 bool Write(const wxString& key, const wxChar* value)
181 { return wxConfigBase::Write(key, value); }
182
183 virtual bool Flush(bool bCurrentOnly = FALSE);
184
185 virtual bool RenameEntry(const wxString& oldName, const wxString& newName);
186 virtual bool RenameGroup(const wxString& oldName, const wxString& newName);
187
188 virtual bool DeleteEntry(const wxString& key, bool bGroupIfEmptyAlso);
189 virtual bool DeleteGroup(const wxString& szKey);
190 virtual bool DeleteAll();
191
192 public:
193 // functions to work with this list
194 wxFileConfigLineList *LineListAppend(const wxString& str);
195 wxFileConfigLineList *LineListInsert(const wxString& str,
196 wxFileConfigLineList *pLine); // NULL => Prepend()
197 void LineListRemove(wxFileConfigLineList *pLine);
198 bool LineListIsEmpty();
199
200 private:
201 // GetXXXFileName helpers: return ('/' terminated) directory names
202 static wxString GetGlobalDir();
203 static wxString GetLocalDir();
204
205 // common part of all ctors (assumes that m_str{Local|Global}File are already
206 // initialized
207 void Init();
208
209 // common part of from dtor and DeleteAll
210 void CleanUp();
211
212 // parse the whole file
213 void Parse(wxTextFile& file, bool bLocal);
214
215 // the same as SetPath("/")
216 void SetRootPath();
217
218 // member variables
219 // ----------------
220 wxFileConfigLineList *m_linesHead, // head of the linked list
221 *m_linesTail; // tail
222
223 wxString m_strLocalFile, // local file name passed to ctor
224 m_strGlobalFile; // global
225 wxString m_strPath; // current path (not '/' terminated)
226
227 wxFileConfigGroup *m_pRootGroup, // the top (unnamed) group
228 *m_pCurrentGroup; // the current group
229
230 #ifdef __UNIX__
231 int m_umask; // the umask to use for file creation
232 #endif // __UNIX__
233 };
234
235 #endif
236 // wxUSE_CONFIG
237
238 #endif
239 //_FILECONF_H
240