common/config-file.h

   1 /* ScummVM - Graphic Adventure Engine
   2  *
   3  * ScummVM is the legal property of its developers, whose names
   4  * are too numerous to list here. Please refer to the COPYRIGHT
   5  * file distributed with this source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation; either version 2
  10  * of the License, or (at your option) any later version.
  11
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20  *
  21  * $URL$
  22  * $Id$
  23  *
  24  */
  25
  26 #ifndef COMMON_CONFIG_FILE_H
  27 #define COMMON_CONFIG_FILE_H
  28
  29 #include "common/config-manager.h"
  30 #include "common/list.h"
  31 #include "common/str.h"
  32 #include "common/stream.h"
  33
  34 namespace Common {
  35
  36 /**
  37  * This class allows reading/writing INI style config files.
  38  * It is used by the ConfigManager for storage, but can also
  39  * be used by other code if it needs to read/write custom INI
  40  * files.
  41  *
  42  * Lines starting with a '#' are ignored (i.e. treated as comments).
  43  * Some effort is made to preserve comments, though.
  44  *
  45  * This class makes no attempts to provide fast access to key/value pairs.
  46  * In particular, it stores all sections and k/v pairs in lists, not
  47  * in dictionaries/maps. This makes it very easy to read/write the data
  48  * from/to files, but of course is not appropriate for fast access.
  49  * The main reason is that this class is indeed geared toward doing precisely
  50  * that!
  51  * If you need fast access to the game config, use higher level APIs, like the
  52  * one provided by ConfigManager.
  53  */
  54 class ConfigFile {
  55 public:
  56         struct KeyValue {
  57                 String key;
  58                 String value;
  59                 String comment;
  60         };
  61
  62         typedef List<KeyValue> SectionKeyList;
  63
  64         /** A section in a config file. I.e. corresponds to something like this:
  65          *   [mySection]
  66          *   key=value
  67          *
  68          * Comments are also stored, to keep users happy who like editing their
  69          * config files manually.
  70          */
  71         struct Section {
  72                 String name;
  73                 List<KeyValue> keys;
  74                 String comment;
  75
  76                 bool hasKey(const String &key) const;
  77                 const KeyValue* getKey(const String &key) const;
  78                 void setKey(const String &key, const String &value);
  79                 void removeKey(const String &key);
  80                 const SectionKeyList getKeys() const { return keys; }
  81         };
  82
  83         typedef List<Section> SectionList;
  84
  85 public:
  86         ConfigFile();
  87         ~ConfigFile();
  88
  89         // TODO: Maybe add a copy constructor etc.?
  90
  91         /**
  92          * Check whether the given string is a valid section or key name.
  93          * For that, it must only consist of letters, numbers, dashes and
  94          * underscores. In particular, white space and "#", "=", "[", "]"
  95          * are not valid!
  96          */
  97         static bool isValidName(const Common::String &name);
  98
  99         /** Reset everything stored in this config file. */
 100         void    clear();
 101
 102         bool    loadFromFile(const String &filename);
 103         bool    loadFromSaveFile(const char *filename);
 104         bool    loadFromStream(SeekableReadStream &stream);
 105         bool    saveToFile(const String &filename);
 106         bool    saveToSaveFile(const char *filename);
 107         bool    saveToStream(WriteStream &stream);
 108
 109         bool    hasSection(const String &section) const;
 110         void    removeSection(const String &section);
 111         void    renameSection(const String &oldName, const String &newName);
 112
 113         bool    hasKey(const String &key, const String &section) const;
 114         bool    getKey(const String &key, const String &section, String &value) const;
 115         void    setKey(const String &key, const String &section, const String &value);
 116         void    removeKey(const String &key, const String &section);
 117
 118         const SectionList getSections() const { return _sections; }
 119         const SectionKeyList getKeys(const String &section) const;
 120
 121         void listKeyValues(StringMap &kv);
 122
 123 private:
 124         SectionList _sections;
 125
 126         Section *getSection(const String &section);
 127         const Section *getSection(const String &section) const;
 128 };
 129
 130 /*
 131 - ConfigMan owns a config file
 132 - allow direct access to that config file (for the launcher)
 133 - simplify and unify the regular ConfigMan API in exchange
 134
 135
 136 */
 137
 138 }       // End of namespace Common
 139
 140 #endif