/*-*- c++ -*-*****************************************************************\
* Project: CppLib: C++ library for Windows/UNIX platfroms *
* File: config.h - Config class, .INI/.rc file manager *
*---------------------------------------------------------------------------*
* Language: C++ *
* Platfrom: any (tested under Windows NT) *
*---------------------------------------------------------------------------*
* (c) Karsten Ballüder & Vadim Zeitlin *
* Ballueder@usa.net Vadim.zeitlin@dptmaths.ens-cachan.fr *
*---------------------------------------------------------------------------*
* $Id: appconf.h,v 1.1.1.1 2004/07/09 15:55:46 JoernWuestenfeld Exp $ *
*---------------------------------------------------------------------------*
* Classes: *
* BaseConfig - ABC for class that manage tree organized config info *
* FileConfig - implementation of BaseConfig based on disk files *
* RegistryConfig - implementation of BaseConfig based Win32 registry *
*---------------------------------------------------------------------------*
* To do: *
* - derive wxConfig *
* - EXTENSIVE ERROR CHECKING (none done actually) *
* - derive IniConfig for standard dumb Windows INI files using Win APIs *
*---------------------------------------------------------------------------*
* History: *
* 25.10.97 adapted from wxConfig by Karsten Ballüder *
* 29.10.97 FileConfig now saves comments back (VZ) *
* 30.10.97 Immutable entries support added (KB) *
* 01.11.97 Fixed NULL pointer access in BaseConfig::setCurrentPath (KB) *
* Replaced filterIn() with original function from wxConfig, *
* doing environment variable expansion, too (KB) *
* Made parsing case insensitive (Compile time option) (KB) *
* 02.11.97 Added deleteEntry function (VZ) *
* 08.11.97 Environment variable expansion on demand (VZ) *
* RegistryConfig::changeCurrentPath added (VZ) *
* AppConf defined to be used instead of File/RegistryConfig *
* 18.01.98 Several fixes and changes to FileConfig (KB) *
* Added recordDefaults() method (KB) *
\*****************************************************************************/
#ifndef _APPCONF_H
#define _APPCONF_H
/**@name AppConf - Configuration entry management
*
*
* Copyright
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. *
* You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the Free * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. *
*
*These classes support easy to use management of configuration settings.
*On Unix systems these settings get written to configuration files, of the
*type used by Windows (.INI) and KDE (.lnk). On Win32 systems (Windows NT
*or 95), the settings get written to the registry database.
*Therefor AppConfig provides a consistent API for configuration management
*across both platforms. The API is defined by the BaseConfig virtual base
*class and two implemenations, FileConfig and RegistryConfig are derived
*from this. Nevertheless, you can also use FileConfig under Windows if
*you need it for some special purpose.
*
*The class AppConfig is defined which is the 'native' implementation on *each platform. *
*Also, if the gettext() library function is available (use -lintl on *Unix systems), AppConfig can be compiled with -DAPPCONF_USE_GETTEXT=1 *to support multiple languages in its error messages. *Precompiled message catalogues for German and French are included, *copy them to the appropriate directories under Unix *(e.g. /usr/share/locale/fr/LC_MESSAGES/appconf.mo or * /usr/share/locale/de/LC_MESSAGES/appconf.mo). *
*Two simple programs demonstrating the use of AppConfig are included. *
*Full documentation of the classes is included in HTML format in the
*doc directory. Please use your web browser to view it.
*The LaTeX documentation appconf.tex in the same directory contains a
*few errors (because it was auto-generated with doc++), but is usable.
*Just keep pressing Enter when LaTeX complains. An A4 PostScript version
*is also included.
*
*Feel free to contact us with any questions or suggestions. If you use
*it in your programs, we would be pleased to hear about it.
* @memo A configuration management system for Unix and Windows.
* @author Karsten Ballüder and Vadim Zeitlin
*/
//@{
#if APPCONF_USE_CONFIG_H
# include
char **aszGroups;
config.setCurrentPath("mygroup");
BaseConfig::Enumerator *pEnum = config.enumSubgroups();
size_t nGroups = pEnum->Count();
for ( size_t n = 0; n < nGroups; n++ )
cout << "Name of subgorup #" << n << " is " << (*pEnum)[n] << endl;
delete pEnum;
@param Pointer to an array of strings which is allocated by the function
@return Number of subgroups
@see Enumerator, setCurrentPath, enumEntries
*/
virtual Enumerator *enumSubgroups() const = 0;
/**
Enumerate entries of the current group.
@return Number of entries
@see Enumerator, enumSubgroups
*/
virtual Enumerator *enumEntries() const = 0;
//@}
/** @name Key access */
//@{
/**
Get the value of an entry, or the default value.
@param szKey The key to search for.
@param szDefault The default value to return if not found.
@return The value of the key, or defval if not found
*/
virtual const char *readEntry(const char *szKey,
const char *szDefault = NULL) const = 0;
/**
Get the value of an entry, or the default value, interpreted as a
long integer.
@param szKey The key to search for.
@param Default The default value to return if not found.
@return The value of the key converted to long int or the default value.
*/
long int readEntry(const char *szKey, long int Default) const;
/**
Get the value of an entry, or the default value, interpreted as a
double value.
@param szKey The key to search for.
@param Default The default value to return if not found.
@return The value of the key converted to double or the default value.
*/
double readEntry(const char *szKey, double Default) const;
/**
Set the value of an entry.
@param szKey The key whose value to change.
@param szValue The new value.
@return TRUE on success, FALSE on failure
*/
virtual Bool writeEntry(const char *szKey, const char *szValue) = 0;
/**
Set the value of an entry to a long int value.
@param szKey The key whose value to change.
@param Value The new value.
@return TRUE on success, FALSE on failure
*/
Bool writeEntry(const char *szKey, long int Value);
/**
Set the value of an entry to a double value.
@param szKey The key whose value to change.
@param Value The new value.
@return TRUE on success, FALSE on failure
*/
Bool writeEntry(const char *szKey, double Value);
/**
Delets the entry. Notice that there is intentionally no such function
as deleteGroup: the group is automatically deleted when it's last entry
is deleted.
@memo Deletes the entry.
@param szKey The key to delete
@return TRUE on success, FALSE on failure
*/
virtual Bool deleteEntry(const char *szKey) = 0;
//@}
/** @name Other functions */
//@{
/// permanently writes changes, returns TRUE on success
virtual Bool flush(Bool /* bCurrentOnly */ = FALSE) { return TRUE; }
/// returns TRUE if object was correctly initialized
Bool isInitialized() const { return m_bOk; }
//@}
/**
@name Filter functions.
All key values should pass by these functions, derived classes should
call them in their read/writeEntry functions.
Currently, these functions only escape meta-characters (mainly spaces
which would otherwise confuse the parser), but they could also be used
to encode/decode key values.
*/
//@{
/// should be called from writeEntry, returns pointer to dynamic buffer
static char *filterOut(const char *szValue);
/// should be called from readEntry, returns pointer to dynamic buffer
static char *filterIn(const char *szValue);
/// should environment variables be automatically expanded?
void expandVariables(Bool bExpand = TRUE) { m_bExpandVariables = bExpand; }
/// do environment variables get automatically expanded?
Bool doesExpandVariables(void) const { return m_bExpandVariables; }
//@}
protected:
/// TRUE if ctor successfully initialized the object
Bool m_bOk;
/// TRUE if environment variables are to be auto-expanded
Bool m_bExpandVariables;
/// TRUE if default values are to be recorded
Bool m_bRecordDefaults;
private:
char *m_szCurrentPath;
};
// ----------------------------------------------------------------------------
/**
FileConfig derives from BaseConfig and implements file based config class,
i.e. it uses ASCII disk files to store the information. These files are
alternatively called INI, .conf or .rc in the documentation. They are
organized in groups or sections, which can nest (i.e. a group contains
subgroups, which contain their own subgroups &c). Each group has some
number of entries, which are "key = value" pairs. More precisely, the format
is:
# comments are allowed after either ';' or '#' (Win/UNIX standard)
# blank lines (as above) are ignored
# global entries are members of special (no name) top group
written_for = wxWindows
platform = Linux
# the start of the group 'Foo'
[Foo] # may put comments like this also
# following 3 lines are entries
key = value
another_key = " strings with spaces in the beginning should be quoted, \
otherwise the spaces are lost"
last_key = but you don't have to put " normally (nor quote them, like here)
# subgroup of the group 'Foo'
# (order is not important, only the name is: separator is '/', as in paths)
[Foo/Bar]
# entries prefixed with "!" are immutable, i.e. can't be changed if they are
# set in the system wide .conf file
!special_key = value
bar_entry = whatever
[Foo/Bar/Fubar] # depth is (theoretically :-) unlimited
# may have the same name as key in another section
bar_entry = whatever not
You {have read/write/delete}Entry functions (guess what they do) and also
setCurrentPath to select current group. enum{Subgroups/Entries} allow you
to get all entries in the config file (in the current group). Finally,
flush() writes immediately all changed entries to disk (otherwise it would
be done automatically in dtor)
FileConfig manages not less than 2 config files for each program: global
and local (or system and user if you prefer). Entries are read from both of
them and the local entries override the global ones unless the latter is
immutable (prefixed with '!') in which case a warning message is generated
and local value is ignored. Of course, the changes are always written to local
file only.
*/
// ----------------------------------------------------------------------------
class FileConfig : public BaseConfig
{
public:
/** @name Constructors and destructor */
//@{
/**
FileConfig will