1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
4 SPDX-FileCopyrightText: 2001 Waldo Bastian <bastian@kde.org>
5 SPDX-FileCopyrightText: 1999 Preston Brown <pbrown@kde.org>
6 SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KCONFIG_H
12#define KCONFIG_H
13
14#include "kconfigbase.h"
15
16#include <kconfigcore_export.h>
17
18#include <QByteArray>
19#include <QList>
20#include <QStandardPaths>
21#include <QString>
22#include <QVariant>
23
24class KConfigGroup;
25class KConfigPrivate;
26
27/**
28 * \class KConfig kconfig.h <KConfig>
29 *
30 * \brief The central class of the KDE configuration data system.
31 *
32 * Quickstart:
33 *
34 * Get the default application config object via KSharedConfig::openConfig().
35 *
36 * Load a specific configuration file:
37 * \code
38 * KConfig config("/etc/kderc", KConfig::SimpleConfig);
39 * \endcode
40 *
41 * Load the configuration of a specific component:
42 * \code
43 * KConfig config("pluginrc");
44 * \endcode
45 *
46 * In general it is recommended to use KSharedConfig instead of
47 * creating multiple instances of KConfig to avoid the overhead of
48 * separate objects or concerns about synchronizing writes to disk
49 * even if the configuration object is updated from multiple code paths.
50 * KSharedConfig provides a set of open methods as counterparts for the
51 * KConfig constructors.
52 *
53 * \sa KSharedConfig, KConfigGroup, <a href="https://techbase.kde.org/index.php?title=Development/Tutorials/KConfig">the techbase HOWTO on KConfig</a>.
54 */
55class KCONFIGCORE_EXPORT KConfig : public KConfigBase
56{
57public:
58 /**
59 * Determines how the system-wide and user's global settings will affect
60 * the reading of the configuration.
61 *
62 * If CascadeConfig is selected, system-wide configuration sources are used
63 * to provide defaults for the settings accessed through this object, or
64 * possibly to override those settings in certain cases.
65 *
66 * If IncludeGlobals is selected, the kdeglobals configuration is used
67 * as additional configuration sources to provide defaults. Additionally
68 * selecting CascadeConfig will result in the system-wide kdeglobals sources
69 * also getting included.
70 *
71 * Note that the main configuration source overrides the cascaded sources,
72 * which override those provided to addConfigSources(), which override the
73 * global sources. The exception is that if a key or group is marked as
74 * being immutable, it will not be overridden.
75 *
76 * Note that all values other than IncludeGlobals and CascadeConfig are
77 * convenience definitions for the basic mode.
78 * Do @em not combine them with anything.
79 * @see OpenFlags
80 */
81 enum OpenFlag {
82 IncludeGlobals = 0x01, ///< Blend kdeglobals into the config object.
83 CascadeConfig = 0x02, ///< Cascade to system-wide config files.
84
85 SimpleConfig = 0x00, ///< Just a single config file.
86 NoCascade = IncludeGlobals, ///< Include user's globals, but omit system settings.
87 NoGlobals = CascadeConfig, ///< Cascade to system settings, but omit user's globals.
88 FullConfig = IncludeGlobals | CascadeConfig, ///< Fully-fledged config, including globals and cascading to system settings
89 };
90 /**
91 * Stores a combination of #OpenFlag values.
92 */
93 Q_DECLARE_FLAGS(OpenFlags, OpenFlag)
94
95 /**
96 * Creates a KConfig object to manipulate a configuration file for the
97 * current application.
98 *
99 * If an absolute path is specified for @p file, that file will be used
100 * as the store for the configuration settings. If a non-absolute path
101 * is provided, the file will be looked for in the standard directory
102 * specified by type. If no path is provided, a default
103 * configuration file will be used based on the name of the main
104 * application component.
105 *
106 * @p mode determines whether the user or global settings will be allowed
107 * to influence the values returned by this object. See OpenFlags for
108 * more details.
109 *
110 * @note You probably want to use KSharedConfig::openConfig instead.
111 *
112 * @param file the name of the file. If an empty string is passed in
113 * and SimpleConfig is passed in for the OpenFlags, then an in-memory
114 * KConfig object is created which will not write out to file nor which
115 * requires any file in the filesystem at all.
116 * @param mode how global settings should affect the configuration
117 * options exposed by this KConfig object
118 * @param type The standard directory to look for the configuration
119 * file in
120 *
121 * @sa KSharedConfig::openConfig(const QString&, OpenFlags, QStandardPaths::StandardLocation)
122 */
123 explicit KConfig(const QString &file = QString(),
124 OpenFlags mode = FullConfig,
125 QStandardPaths::StandardLocation type = QStandardPaths::GenericConfigLocation);
126
127 /**
128 * @internal
129 *
130 * Creates a KConfig object using the specified backend. If the backend can not
131 * be found or loaded, then the standard configuration parser is used as a fallback.
132 *
133 * @param file the file to be parsed
134 * @param backend the backend to load
135 * @param type where to look for the file if an absolute path is not provided
136 *
137 * @since 4.1
138 */
139 KConfig(const QString &file, const QString &backend, QStandardPaths::StandardLocation type = QStandardPaths::GenericConfigLocation);
140
141 ~KConfig() override;
142
143 /**
144 * Returns the standard location enum passed to the constructor.
145 * Used by KSharedConfig.
146 * @since 5.0
147 */
148 QStandardPaths::StandardLocation locationType() const;
149
150 /**
151 * Returns the filename used to store the configuration.
152 */
153 QString name() const;
154
155 /**
156 * @return the flags this object was opened with
157 * @since 5.3
158 */
159 OpenFlags openFlags() const;
160
161 /// @reimp
162 bool sync() override;
163
164 /// Returns true if sync has any changes to write out.
165 /// @since 4.12
166 bool isDirty() const;
167
168 /// @reimp
169 void markAsClean() override;
170
171 /// @{ configuration object state
172 /// @reimp
173 AccessMode accessMode() const override;
174
175 /**
176 * Whether the configuration can be written to.
177 *
178 * If @p warnUser is true and the configuration cannot be
179 * written to (ie: this method returns @c false), a warning
180 * message box will be shown to the user telling them to
181 * contact their system administrator to get the problem fixed.
182 *
183 * The most likely cause for this method returning @c false
184 * is that the user does not have write permission for the
185 * configuration file.
186 *
187 * @param warnUser whether to show a warning message to the user
188 * if the configuration cannot be written to
189 *
190 * @returns true if the configuration can be written to, false
191 * if the configuration cannot be written to
192 */
193 bool isConfigWritable(bool warnUser);
194 /// @}
195
196 /**
197 * Copies all entries from this config object to a new config
198 * object that will save itself to @p file.
199 *
200 * The configuration will not actually be saved to @p file
201 * until the returned object is destroyed, or sync() is called
202 * on it.
203 *
204 * Do not forget to delete the returned KConfig object if
205 * @p config was 0.
206 *
207 * @param file the new config object will save itself to
208 * @param config if not 0, copy to the given KConfig object rather
209 * than creating a new one
210 *
211 * @return @p config if it was set, otherwise a new KConfig object
212 */
213 KConfig *copyTo(const QString &file, KConfig *config = nullptr) const;
214
215 /**
216 * Ensures that the configuration file contains a certain update.
217 *
218 * If the configuration file does not contain the update @p id
219 * as contained in @p updateFile, kconf_update is run to update
220 * the configuration file.
221 *
222 * If you install config update files with critical fixes
223 * you may wish to use this method to verify that a critical
224 * update has indeed been performed to catch the case where
225 * a user restores an old config file from backup that has
226 * not been updated yet.
227 *
228 * @param id the update to check
229 * @param updateFile the file containing the update
230 */
231 void checkUpdate(const QString &id, const QString &updateFile);
232
233 /**
234 * Updates the state of this object to match the persistent storage.
235 * Note that if this object has pending changes, this method will
236 * call sync() first so as not to lose those changes.
237 */
238 void reparseConfiguration();
239
240 /// @{ extra config files
241 /**
242 * Adds the list of configuration sources to the merge stack.
243 *
244 * Currently only files are accepted as configuration sources.
245 *
246 * The first entry in @p sources is treated as the most general and will
247 * be overridden by the second entry. The settings in the final entry
248 * in @p sources will override all the other sources provided in the list.
249 *
250 * The settings in @p sources will also be overridden by the sources
251 * provided by any previous calls to addConfigSources().
252 *
253 * The settings in the global configuration sources will be overridden by
254 * the sources provided to this method (@see IncludeGlobals).
255 * All the sources provided to any call to this method will be overridden
256 * by any files that cascade from the source provided to the constructor
257 * (@see CascadeConfig), which will in turn be
258 * overridden by the source provided to the constructor.
259 *
260 * Note that only the most specific file, ie: the file provided to the
261 * constructor, will be written to by this object.
262 *
263 * The state is automatically updated by this method, so there is no need to call
264 * reparseConfiguration().
265 *
266 * @param sources A list of extra config sources.
267 */
268 void addConfigSources(const QStringList &sources);
269
270 /**
271 * Returns a list of the additional configuration sources used in this object
272 */
273 QStringList additionalConfigSources() const;
274
275 /// @}
276 /// @{ locales
277 /**
278 * Returns the current locale.
279 */
280 QString locale() const;
281 /**
282 * Sets the locale to @p aLocale.
283 *
284 * The global locale is used by default.
285 *
286 * @note If set to the empty string, @b no locale will be matched. This effectively disables
287 * reading translated entries.
288 *
289 * @return @c true if locale was changed, @c false if the call had no
290 * effect (eg: @p aLocale was already the current locale for this
291 * object)
292 */
293 bool setLocale(const QString &aLocale);
294 /// @}
295
296 /// @{ defaults
297 /**
298 * When set, all readEntry calls return the system-wide (default) values
299 * instead of the user's settings.
300 *
301 * This is off by default.
302 *
303 * @param b whether to read the system-wide defaults instead of the
304 * user's settings
305 */
306 void setReadDefaults(bool b);
307 /**
308 * @returns @c true if the system-wide defaults will be read instead of the
309 * user's settings
310 */
311 bool readDefaults() const;
312 /// @}
313
314 /// @{ immutability
315 /// @reimp
316 bool isImmutable() const override;
317 /// @}
318
319 /// @reimp
320 QStringList groupList() const override;
321
322 /**
323 * Returns a map (tree) of entries in a particular group.
324 *
325 * The entries are all returned as strings.
326 *
327 * @param aGroup The group to get entries from.
328 *
329 * @return A map of entries in the group specified, indexed by key.
330 * The returned map may be empty if the group is empty, or not found.
331 * @see QMap
332 */
333 QMap<QString, QString> entryMap(const QString &aGroup = QString()) const;
334
335 /**
336 * Sets the name of the application config file.
337 * @since 5.0
338 */
339 static void setMainConfigName(const QString &str);
340
341 /**
342 * Get the name of application config file.
343 * @since 5.93
344 */
345 static QString mainConfigName();
346
347protected:
348 bool hasGroupImpl(const QString &groupName) const override;
349 KConfigGroup groupImpl(const QString &groupName) override;
350 const KConfigGroup groupImpl(const QString &groupName) const override;
351 void deleteGroupImpl(const QString &groupName, WriteConfigFlags flags = Normal) override;
352 bool isGroupImmutableImpl(const QString &groupName) const override;
353
354 friend class KConfigGroup;
355 friend class KConfigGroupPrivate;
356 friend class KSharedConfig;
357
358 /** Virtual hook, used to add new "virtual" functions while maintaining
359 * binary compatibility. Unused in this class.
360 */
361 void virtual_hook(int id, void *data) override;
362
363 KConfigPrivate *const d_ptr;
364
365 KCONFIGCORE_NO_EXPORT explicit KConfig(KConfigPrivate &d);
366
367private:
368 friend class KConfigTest;
369
370 Q_DISABLE_COPY(KConfig)
371
372 Q_DECLARE_PRIVATE(KConfig)
373};
374Q_DECLARE_OPERATORS_FOR_FLAGS(KConfig::OpenFlags)
375
376#endif // KCONFIG_H
377

source code of kconfig/src/core/kconfig.h