util/environmentgrouplist.h

   1 /* This file is part of KDevelop
   2 Copyright 2007 Andreas Pakulat <apaku@gmx.de>
   3
   4 This library is free software; you can redistribute it and/or
   5 modify it under the terms of the GNU Library General Public
   6 License as published by the Free Software Foundation; either
   7 version 2 of the License, or (at your option) any later version.
   8
   9 This library is distributed in the hope that it will be useful,
  10 but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12 Library General Public License for more details.
  13
  14 You should have received a copy of the GNU Library General Public License
  15 along with this library; see the file COPYING.LIB.  If not, write to
  16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17 Boston, MA 02110-1301, USA.
  18 */
  19
  20 #ifndef ENVIRONMENTGROUPLIST_H
  21 #define ENVIRONMENTGROUPLIST_H
  22
  23 #include "utilexport.h"
  24 #include <ksharedconfig.h>
  25
  26 class KConfig;
  27 template <typename T1, typename T2> class QMap;
  28 class QString;
  29 class QStringList;
  30
  31 namespace KDevelop
  32 {
  33
  34 /**
  35  * This class manages a list of environment groups, each group containing a number
  36  * of environment variables and their values.
  37  *
  38  * The class is constructed from a KConfig object for easy usage in the plugins.
  39  *
  40  * The methods to change the environments is protected to disallow access to those methods
  41  * from plugins, only the environment widget is allowed to change them.
  42  *
  43  * Example Usage
  44  * \code
  45  *   KSharedConfigPtr config = KGlobal::config();
  46  *   EnvironmentGroupList env(config);
  47  *   KConfigGroup cfg(config, "QMake Builder");
  48  *   QMap<QString,QString> myenvVars = env.variables( cfg.readEntry("QMake Environment") );
  49  * \endcode
  50  *
  51  * Two entries are used by this class:
  52  * "Default Environment Group" and "Environment Variables".
  53  *
  54  * "Default Environment Variables" stores the default group that should be used if the
  55  * user didn't select a group via a plugins configuration dialog.
  56  *
  57  * "Environment Variables" entry stores the actual list of
  58  * <groupname%varname=varvalue>. The groupname can't contain '%' or '='.
  59  * For example, suppose that two configuration, say "release" and "debug" exist.
  60  * Then the actual contents of .kdev4 project file will be
  61  *
  62  * \code
  63  * [Environment Settings]
  64  * Default Environment Group=debug
  65  * Environment Variables=debug_PATH=/home/kde-devel/usr/bin,release_PATH=/usr/bin
  66  * \endcode
  67  *
  68  */
  69 class KDEVPLATFORMUTIL_EXPORT EnvironmentGroupList
  70 {
  71 public:
  72     /**
  73      * Creates an a list of EnvironmentGroups from a KConfig object
  74      * @param config the KConfig object to read the environment groups from
  75      */
  76     EnvironmentGroupList( KSharedConfigPtr config );
  77     EnvironmentGroupList( KConfig* config );
  78     ~EnvironmentGroupList();
  79
  80     /**
  81      * Creates a merged environment between the defaults specified by
  82      * \a defaultEnvironment and those saved in \a group
  83      */
  84     QStringList createEnvironment(const QString& group, const QStringList& defaults) const;
  85
  86     /**
  87      * returns the variables that are set for a given group.
  88      * This function provides read-only access to the environment
  89      * @param group  the name of the group for which the environment should be returned
  90      * @return a map containing the environment variables for this group, or an empty map if the group doesn't exist in this list
  91      */
  92     const QMap<QString, QString> variables( const QString& group ) const;
  93
  94     /**
  95      * returns the default group
  96      * The default group should be used by plugins unless the user chooses a different group
  97      * @return the name of the default group, defaults to "default"
  98      */
  99     QString defaultGroup() const;
 100
 101     /**
 102      * Fetch the list of known groups from the list
 103      * @return the list of groups
 104      */
 105     QStringList groups() const;
 106
 107 protected:
 108     EnvironmentGroupList();
 109     /**
 110      * returns the variables that are set for a given group.
 111      * This function provides write access to the environment, so new variables can be inserted, existing ones changed or deleted
 112      *
 113      * If a non-existing group is specified this returns a new empty map and that way this function can be used to add a new group
 114      * to the list of environment groups
 115      * @param group  the name of the group for which the environment should be returned
 116      * @return a map containing the environment variables for this group, or an empty map if the group doesn't exist in this list
 117      */
 118     QMap<QString, QString>& variables( const QString& group );
 119
 120     /**
 121      * Changes the default group.
 122      * @param group a new groupname, if a group of this name doesn't exist the default group is not changed
 123      */
 124     void setDefaultGroup( const QString& group );
 125
 126     /**
 127      * Stores the environment groups in this list to the given KConfig object
 128      * @param config a KConfig object to which the environment settings should be stored
 129      */
 130     void saveSettings( KConfig* config ) const;
 131
 132     void loadSettings( KConfig* config );
 133     void removeGroup( const QString& group );
 134 private:
 135     class EnvironmentGroupListPrivate* const d;
 136
 137 };
 138
 139 }
 140
 141 #endif