The Battle for Wesnoth  1.19.15+dev
config_attribute_value.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2025
3  by David White <dave@whitevine.net>
4  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 /**
17  * @file
18  * Definitions for the interface to Wesnoth Markup Language (WML).
19  *
20  * This module defines the interface to Wesnoth Markup Language (WML). WML is
21  * a simple hierarchical text-based file format. The format is defined in
22  * Wiki, under BuildingScenariosWML
23  *
24  * All configuration files are stored in this format, and data is sent across
25  * the network in this format. It is thus used extensively throughout the
26  * game.
27  */
28 
29 #pragma once
30 
31 #include "tstring.hpp"
32 #include "utils/variant.hpp"
33 
34 #include <chrono>
35 #include <climits>
36 #ifdef __cpp_concepts
37 #include <concepts>
38 #endif
39 #include <iosfwd>
40 #include <string>
41 #include <vector>
42 #include <type_traits>
43 
44 #ifdef __cpp_concepts
45 template<typename T>
46 concept StringLike = std::constructible_from<std::string, T>;
47 #endif
48 
49 /**
50  * Variant for storing WML attributes.
51  * The most efficient type is used when assigning a value. For instance,
52  * strings "yes", "no", "true", "false" will be detected and stored as boolean.
53  * @note The blank variant is only used when querying missing attributes.
54  * It is not stored in config objects.
55  */
57 {
58  /**
59  * A wrapper for bool to get the correct streaming ("true"/"false").
60  * Most visitors can simply treat this as bool.
61  */
62 public:
63  class true_false
64  {
65  bool value_;
66  public:
67  explicit true_false(bool value = false) : value_(value) {}
68  operator bool() const { return value_; }
69 
70  const std::string & str() const
71  {
73  }
74  };
75  friend std::ostream& operator<<(std::ostream &os, const true_false &v) { return os << v.str(); }
76 
77  /**
78  * A wrapper for bool to get the correct streaming ("yes"/"no").
79  * Most visitors can simply treat this as bool.
80  */
81  class yes_no
82  {
83  bool value_;
84  public:
85  explicit yes_no(bool value = false) : value_(value) {}
86  operator bool() const { return value_; }
87 
88  const std::string & str() const
89  {
91  }
92  };
93  friend std::ostream& operator<<(std::ostream &os, const yes_no &v) { return os << v.str(); }
94 private:
95  /** Visitor for checking equality. */
96  class equality_visitor;
97  /** Visitor for converting a variant to a string. */
98  class string_visitor;
99 
100  // Data will be stored in a variant, allowing for the possibility of
101  // boolean, numeric, and translatable data in addition to basic string
102  // data. For most purposes, int is the preferred type for numeric data
103  // as it is fast (often natural word size). While it is desirable to
104  // use few types (to keep the overhead low), we do have use cases for
105  // fractions (double) and huge numbers (up to the larger of LLONG_MAX
106  // and SIZE_MAX).
107  typedef utils::variant<utils::monostate,
108  true_false, yes_no,
109  int, unsigned long long, double,
110  std::string, t_string
112  /**
113  * The stored value will always use the first type from the variant
114  * definition that can represent it and that can be streamed to the
115  * correct string representation (if applicable).
116  * This is enforced upon assignment.
117  */
119 
120 public:
121  // Numeric assignments:
124  config_attribute_value& operator=(long v) { return operator=(static_cast<long long>(v)); }
125  config_attribute_value& operator=(long long v);
126  config_attribute_value& operator=(unsigned v) { return operator=(static_cast<unsigned long long>(v)); }
127  config_attribute_value& operator=(unsigned long v) { return operator=(static_cast<unsigned long long>(v)); }
128  config_attribute_value& operator=(unsigned long long v);
130 
131  // String assignments:
132  config_attribute_value& operator=(const char *v) { return operator=(std::string(v)); }
133  config_attribute_value& operator=(std::string&& v);
134  config_attribute_value& operator=(const std::string &v);
135  config_attribute_value& operator=(const std::string_view &v);
137 
138  //TODO: should this be a normal constructor?
139  template<typename T>
140  static config_attribute_value create(const T val)
141  {
143  res = val;
144  return res;
145  }
146 
147  template<typename... Args>
148  config_attribute_value& operator=(const std::chrono::duration<Args...>& v)
149  {
150  return this->operator=(v.count());
151  }
152 
153  /** Calls @ref operator=(const std::string&) if @a v is not empty. */
154  void write_if_not_empty(const std::string& v);
155  void write_if_not_empty(const t_string& v);
156 
157  // Extracting as a specific type:
158  bool to_bool(bool def = false) const;
159  int to_int(int def = 0) const;
160  long long to_long_long(long long def = 0) const;
161  unsigned to_unsigned(unsigned def = 0) const;
162  std::size_t to_size_t(std::size_t def = 0) const;
163  double to_double(double def = 0.) const;
164  std::string str(const std::string& fallback = "") const;
165  t_string t_str() const;
166 
167  bool to(const bool def) const { return to_bool(def); }
168  int to(int def) const { return to_int(def); }
169  unsigned to(unsigned def) const { return to_unsigned(def); }
170  double to(double def) const { return to_double(def); }
171  std::string to(const std::string& def) const { return str(def); }
172 
173  // Implicit conversions:
174  operator std::string() const { return str(); }
175  operator t_string() const { return t_str(); }
176 
177  /** Tests for an attribute that was never set. */
178  bool blank() const;
179  /** Tests for an attribute that either was never set or was set to "". */
180  bool empty() const;
181 
182  // Comparisons:
183  bool operator==(const config_attribute_value &other) const;
184  bool operator!=(const config_attribute_value &other) const
185  {
186  return !operator==(other);
187  }
188 
189 #ifdef __cpp_concepts
190  bool operator==(const StringLike auto& comp) const
191  {
192  return apply_visitor([this, &comp]<typename V>(const V& value) {
193  if constexpr(StringLike<V>) {
194  return value == comp;
195  } else {
196  return *this == create(comp);
197  }
198  });
199  }
200 #else
201  template<typename T>
202  std::enable_if_t<std::is_constructible_v<std::string, T>, bool>
203  operator==(const T& comp) const
204  {
205  return apply_visitor([this, &comp](const auto& value) {
206  if constexpr(std::is_constructible_v<std::string, std::decay_t<decltype(value)>>) {
207  return value == comp;
208  } else {
209  return *this == create(comp);
210  }
211  });
212  }
213 
214  template<typename T>
215  std::enable_if_t<std::is_constructible_v<std::string, T>, bool>
216  operator!=(const T& comp) const
217  {
218  return !operator==(comp);
219  }
220 #endif
221 
222  // Streaming:
223  friend std::ostream& operator<<(std::ostream& os, const config_attribute_value& v);
224 
225  /**
226  * Visitor support:
227  * Applies a visitor to the underlying variant.
228  * (See the documentation for Boost.Variant.)
229  */
230  template <typename V>
231  auto apply_visitor(const V & visitor) const
232  {
233  return utils::visit(visitor, value_);
234  }
235 
236 private:
237  // Special strings.
238  static const std::string s_yes, s_no;
239  static const std::string s_true, s_false;
240 };
241 
242 #ifndef USING_BOOST_VARIANT
243 /** Specialize operator<< for monostate. Boost already does this, but the STL does not. */
244 inline std::ostream& operator<<(std::ostream& os, const std::monostate&) { return os; }
245 #endif
246 
247 namespace utils
248 {
249  std::vector<std::string> split(const config_attribute_value& val);
250 }
A wrapper for bool to get the correct streaming ("true"/"false").
A wrapper for bool to get the correct streaming ("yes"/"no").
const std::string & str() const
Variant for storing WML attributes.
friend std::ostream & operator<<(std::ostream &os, const true_false &v)
static const std::string s_false
value_type value_
The stored value will always use the first type from the variant definition that can represent it and...
std::enable_if_t< std::is_constructible_v< std::string, T >, bool > operator!=(const T &comp) const
config_attribute_value & operator=(unsigned v)
std::string str(const std::string &fallback="") const
std::string to(const std::string &def) const
static const std::string s_true
auto apply_visitor(const V &visitor) const
Visitor support: Applies a visitor to the underlying variant.
unsigned to_unsigned(unsigned def=0) const
static const std::string s_yes
unsigned to(unsigned def) const
bool blank() const
Tests for an attribute that was never set.
static const std::string s_no
config_attribute_value & operator=(long v)
config_attribute_value & operator=(unsigned long v)
bool to(const bool def) const
bool operator!=(const config_attribute_value &other) const
bool to_bool(bool def=false) const
config_attribute_value & operator=(bool v)
static config_attribute_value create(const T val)
config_attribute_value & operator=(const char *v)
utils::variant< utils::monostate, true_false, yes_no, int, unsigned long long, double, std::string, t_string > value_type
double to(double def) const
bool operator==(const config_attribute_value &other) const
Checks for equality of the attribute values when viewed as strings.
void write_if_not_empty(const std::string &v)
Calls operator=(const std::string&) if v is not empty.
bool empty() const
Tests for an attribute that either was never set or was set to "".
config_attribute_value & operator=(const std::chrono::duration< Args... > &v)
std::enable_if_t< std::is_constructible_v< std::string, T >, bool > operator==(const T &comp) const
friend std::ostream & operator<<(std::ostream &os, const yes_no &v)
long long to_long_long(long long def=0) const
std::size_t to_size_t(std::size_t def=0) const
double to_double(double def=0.) const
std::ostream & operator<<(std::ostream &os, const std::monostate &)
Specialize operator<< for monostate.
std::vector< std::string > split(const config_attribute_value &val)
MacOS doesn't support std::visit when targing MacOS < 10.14 (currently we target 10....