src/settings.h

   1 /*
   2 Minetest
   3 Copyright (C) 2010-2013 celeron55, Perttu Ahola <celeron55@gmail.com>
   4
   5 This program is free software; you can redistribute it and/or modify
   6 it under the terms of the GNU Lesser General Public License as published by
   7 the Free Software Foundation; either version 2.1 of the License, or
   8 (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU Lesser General Public License for more details.
  14
  15 You should have received a copy of the GNU Lesser General Public License along
  16 with this program; if not, write to the Free Software Foundation, Inc.,
  17 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18 */
  19
  20 #pragma once
  21
  22 #include "irrlichttypes_bloated.h"
  23 #include "util/string.h"
  24 #include <string>
  25 #include <list>
  26 #include <set>
  27 #include <mutex>
  28
  29 class Settings;
  30 struct NoiseParams;
  31
  32 // Global objects
  33 extern Settings *g_settings;
  34 extern std::string g_settings_path;
  35
  36 // Type for a settings changed callback function
  37 typedef void (*SettingsChangedCallback)(const std::string &name, void *data);
  38
  39 typedef std::vector<
  40         std::pair<
  41                 SettingsChangedCallback,
  42                 void *
  43         >
  44 > SettingsCallbackList;
  45
  46 typedef std::unordered_map<std::string, SettingsCallbackList> SettingsCallbackMap;
  47
  48 enum ValueType {
  49         VALUETYPE_STRING,
  50         VALUETYPE_FLAG // Doesn't take any arguments
  51 };
  52
  53 enum SettingsParseEvent {
  54         SPE_NONE,
  55         SPE_INVALID,
  56         SPE_COMMENT,
  57         SPE_KVPAIR,
  58         SPE_END,
  59         SPE_GROUP,
  60         SPE_MULTILINE,
  61 };
  62
  63 struct ValueSpec {
  64         ValueSpec(ValueType a_type, const char *a_help=NULL)
  65         {
  66                 type = a_type;
  67                 help = a_help;
  68         }
  69
  70         ValueType type;
  71         const char *help;
  72 };
  73
  74 struct SettingsEntry {
  75         SettingsEntry() = default;
  76
  77         SettingsEntry(const std::string &value_) :
  78                 value(value_)
  79         {}
  80
  81         SettingsEntry(Settings *group_) :
  82                 group(group_),
  83                 is_group(true)
  84         {}
  85
  86         std::string value = "";
  87         Settings *group = nullptr;
  88         bool is_group = false;
  89 };
  90
  91 typedef std::unordered_map<std::string, SettingsEntry> SettingEntries;
  92
  93 class Settings {
  94 public:
  95         Settings() = default;
  96
  97         ~Settings();
  98
  99         Settings & operator += (const Settings &other);
 100         Settings & operator = (const Settings &other);
 101
 102         /***********************
 103          * Reading and writing *
 104          ***********************/
 105
 106         // Read configuration file.  Returns success.
 107         bool readConfigFile(const char *filename);
 108         //Updates configuration file.  Returns success.
 109         bool updateConfigFile(const char *filename);
 110         // NOTE: Types of allowed_options are ignored.  Returns success.
 111         bool parseCommandLine(int argc, char *argv[],
 112                         std::map<std::string, ValueSpec> &allowed_options);
 113         bool parseConfigLines(std::istream &is, const std::string &end = "");
 114         void writeLines(std::ostream &os, u32 tab_depth=0) const;
 115
 116         /***********
 117          * Getters *
 118          ***********/
 119
 120         Settings *getGroup(const std::string &name) const;
 121         const std::string &get(const std::string &name) const;
 122         const std::string &getDefault(const std::string &name) const;
 123         bool getBool(const std::string &name) const;
 124         u16 getU16(const std::string &name) const;
 125         s16 getS16(const std::string &name) const;
 126         u32 getU32(const std::string &name) const;
 127         s32 getS32(const std::string &name) const;
 128         u64 getU64(const std::string &name) const;
 129         float getFloat(const std::string &name) const;
 130         v2f getV2F(const std::string &name) const;
 131         v3f getV3F(const std::string &name) const;
 132         u32 getFlagStr(const std::string &name, const FlagDesc *flagdesc,
 133                         u32 *flagmask) const;
 134         bool getNoiseParams(const std::string &name, NoiseParams &np) const;
 135         bool getNoiseParamsFromValue(const std::string &name, NoiseParams &np) const;
 136         bool getNoiseParamsFromGroup(const std::string &name, NoiseParams &np) const;
 137
 138         // return all keys used
 139         std::vector<std::string> getNames() const;
 140         bool exists(const std::string &name) const;
 141
 142
 143         /***************************************
 144          * Getters that don't throw exceptions *
 145          ***************************************/
 146
 147         bool getGroupNoEx(const std::string &name, Settings *&val) const;
 148         bool getNoEx(const std::string &name, std::string &val) const;
 149         bool getDefaultNoEx(const std::string &name, std::string &val) const;
 150         bool getFlag(const std::string &name) const;
 151         bool getU16NoEx(const std::string &name, u16 &val) const;
 152         bool getS16NoEx(const std::string &name, s16 &val) const;
 153         bool getS32NoEx(const std::string &name, s32 &val) const;
 154         bool getU64NoEx(const std::string &name, u64 &val) const;
 155         bool getFloatNoEx(const std::string &name, float &val) const;
 156         bool getV2FNoEx(const std::string &name, v2f &val) const;
 157         bool getV3FNoEx(const std::string &name, v3f &val) const;
 158
 159         // Like other getters, but handling each flag individualy:
 160         // 1) Read default flags (or 0)
 161         // 2) Override using user-defined flags
 162         bool getFlagStrNoEx(const std::string &name, u32 &val,
 163                 const FlagDesc *flagdesc) const;
 164
 165
 166         /***********
 167          * Setters *
 168          ***********/
 169
 170         // N.B. Groups not allocated with new must be set to NULL in the settings
 171         // tree before object destruction.
 172         bool setEntry(const std::string &name, const void *entry,
 173                 bool set_group, bool set_default);
 174         bool set(const std::string &name, const std::string &value);
 175         bool setDefault(const std::string &name, const std::string &value);
 176         bool setGroup(const std::string &name, const Settings &group);
 177         bool setGroupDefault(const std::string &name, const Settings &group);
 178         bool setBool(const std::string &name, bool value);
 179         bool setS16(const std::string &name, s16 value);
 180         bool setU16(const std::string &name, u16 value);
 181         bool setS32(const std::string &name, s32 value);
 182         bool setU64(const std::string &name, u64 value);
 183         bool setFloat(const std::string &name, float value);
 184         bool setV2F(const std::string &name, v2f value);
 185         bool setV3F(const std::string &name, v3f value);
 186         bool setFlagStr(const std::string &name, u32 flags,
 187                 const FlagDesc *flagdesc = nullptr, u32 flagmask = U32_MAX);
 188         bool setNoiseParams(const std::string &name, const NoiseParams &np,
 189                 bool set_default=false);
 190
 191         // remove a setting
 192         bool remove(const std::string &name);
 193         void clear();
 194         void clearDefaults();
 195
 196         /**************
 197          * Miscellany *
 198          **************/
 199
 200         void setDefault(const std::string &name, const FlagDesc *flagdesc, u32 flags);
 201         // Takes the provided setting values and uses them as new defaults
 202         void overrideDefaults(Settings *other);
 203         const FlagDesc *getFlagDescFallback(const std::string &name) const;
 204
 205         void registerChangedCallback(const std::string &name,
 206                 SettingsChangedCallback cbf, void *userdata = NULL);
 207         void deregisterChangedCallback(const std::string &name,
 208                 SettingsChangedCallback cbf, void *userdata = NULL);
 209
 210 private:
 211         /***********************
 212          * Reading and writing *
 213          ***********************/
 214
 215         SettingsParseEvent parseConfigObject(const std::string &line,
 216                 const std::string &end, std::string &name, std::string &value);
 217         bool updateConfigObject(std::istream &is, std::ostream &os,
 218                 const std::string &end, u32 tab_depth=0);
 219
 220         static bool checkNameValid(const std::string &name);
 221         static bool checkValueValid(const std::string &value);
 222         static std::string getMultiline(std::istream &is, size_t *num_lines=NULL);
 223         static void printEntry(std::ostream &os, const std::string &name,
 224                 const SettingsEntry &entry, u32 tab_depth=0);
 225
 226         /***********
 227          * Getters *
 228          ***********/
 229
 230         const SettingsEntry &getEntry(const std::string &name) const;
 231         const SettingsEntry &getEntryDefault(const std::string &name) const;
 232
 233         // Allow TestSettings to run sanity checks using private functions.
 234         friend class TestSettings;
 235
 236         void updateNoLock(const Settings &other);
 237         void clearNoLock();
 238         void clearDefaultsNoLock();
 239
 240         void doCallbacks(const std::string &name) const;
 241
 242         SettingEntries m_settings;
 243         SettingEntries m_defaults;
 244         std::unordered_map<std::string, const FlagDesc *> m_flags;
 245
 246         SettingsCallbackMap m_callbacks;
 247
 248         mutable std::mutex m_callback_mutex;
 249
 250         // All methods that access m_settings/m_defaults directly should lock this.
 251         mutable std::mutex m_mutex;
 252
 253 };