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

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