The Battle for Wesnoth  1.19.4+dev
help_impl.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2024
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  * Note:
18  * Prior to the creation of this file, all the code associated to the help
19  * browser existed in a single file src/help.cpp, including all of the
20  * widgets, topic generators, and implementation details. This totaled
21  * ~4000 lines of code.
22  *
23  * I have split it all up now, so that the gui aspects are separated from
24  * the content, the "front facing" part which the rest of the code base
25  * interacts with is in src/help/help.?pp, and the topic generators are
26  * separated. The remaining "guts" are here. It is implemented in a static
27  * singleton pattern, using "extern"'d variables, simply for ease of translation
28  * from the previous state. It would probably be a good idea to rewrite this
29  * guy as a proper C++ object. Feel free to do so, or to adopt some other
30  * design pattern.
31  */
32 
33 #pragma once
34 
35 #include "color.hpp"
36 #include "exceptions.hpp" // for error
37 #include "font/constants.hpp"
38 #include "font/standard_colors.hpp"
39 #include "gettext.hpp"
40 #include "utils/optional_fwd.hpp"
41 #include <cstring>
42 #include <list> // for list
43 #include <memory>
44 #include <sstream>
45 #include <string> // for string, allocator, etc
46 #include <utility> // for pair, make_pair
47 #include <vector> // for vector, etc
48 #include <boost/logic/tribool.hpp>
49 #include "config.hpp"
50 
51 class game_config_view;
52 class unit_type;
53 class terrain_type_data;
54 
55 namespace help {
56 
57 /**
58  * Generate the help contents from the configurations given to the manager.
59  */
60 void generate_contents();
61 
62 
63 /** Generate a topic text on the fly. */
65 {
66 public:
67  topic_generator() = default;
68  virtual std::string operator()() const = 0;
69  virtual ~topic_generator() {}
70 };
71 
73  std::string text_;
74 public:
75  text_topic_generator(const std::string& t): text_(t) {}
76  virtual std::string operator()() const { return text_; }
77 };
78 
79 /**
80  * The text displayed in a topic. It is generated on the fly with the information contained in generator_
81  */
83 {
85  mutable std::shared_ptr<topic_generator> generator_;
86 public:
87  topic_text() = default;
88  ~topic_text() = default;
89 
90  topic_text(const std::string& t):
91  parsed_text_(),
92  generator_(std::make_shared<text_topic_generator>(t))
93  {
94  }
95 
96  explicit topic_text(std::shared_ptr<topic_generator> g):
97  parsed_text_(),
98  generator_(g)
99  {
100  }
101 
102  topic_text(const topic_text& t) = default;
103  topic_text(topic_text&& t) = default;
105  topic_text& operator=(const topic_text& t) = default;
106  topic_text& operator=(std::shared_ptr<topic_generator> g);
107 
108  const config& parsed_text() const;
109 };
110 
111 /** A topic contains a title, an id and some text. */
112 struct topic
113 {
114  topic() :
115  title(),
116  id(),
117  text()
118  {
119  }
120 
121  topic(const std::string &_title, const std::string &_id) :
122  title(_title),
123  id(_id),
124  text()
125  {
126  }
127 
128  topic(const std::string &_title, const std::string &_id, const std::string &_text)
129  : title(_title), id(_id), text(_text) {}
130  topic(const std::string &_title, const std::string &_id, std::shared_ptr<topic_generator> g)
131  : title(_title), id(_id), text(g) {}
132  /** Two topics are equal if their IDs are equal. */
133  bool operator==(const topic &) const;
134  bool operator!=(const topic &t) const { return !operator==(t); }
135  /** Comparison on the ID. */
136  bool operator<(const topic &) const;
137  std::string title, id;
138  mutable topic_text text;
139 };
140 
141 struct section;
142 typedef std::list<section> section_list;
143 typedef std::list<topic> topic_list;
144 
145 /** A section contains topics and sections along with title and ID. */
146 struct section {
148  title(""),
149  id(""),
150  topics(),
151  sections()
152  {
153  }
154 
155  /** Two sections are equal if their IDs are equal. */
156  bool operator==(const section &) const;
157  /** Comparison on the ID. */
158  bool operator<(const section &) const;
159 
160  /** Allocate memory for and add the section. */
161  void add_section(const section &s);
162 
163  void clear();
164  std::string title, id;
167 };
168 
169 
170 /**
171  * To be used as a function object to locate sections and topics with a specified ID.
172  */
173 class has_id
174 {
175 public:
176  has_id(const std::string &id) : id_(id) {}
177  bool operator()(const topic &t) { return t.id == id_; }
178  bool operator()(const section &s) { return s.id == id_; }
179  bool operator()(const section *s) { return s != nullptr && s->id == id_; }
180 private:
181  const std::string id_;
182 };
183 
184 /** To be used as a function object when sorting topic lists on the title. */
186 {
187 public:
188  bool operator()(const topic &t1, const topic &t2)
189  {
190  return translation::compare(t1.title, t2.title) < 0;
191  }
192 };
193 
194 /** To be used as a function object when sorting section lists on the title. */
196 {
197 public:
198  bool operator()(const section& s1, const section& s2)
199  {
200  return translation::compare(s1.title, s2.title) < 0;
201  }
202 };
203 
205 {
206 public:
207  bool operator() (const std::string &s1, const std::string &s2) const {
208  return translation::compare(s1, s2) < 0;
209  }
210 };
211 
212 /** Thrown when the help system fails to parse something. */
213 struct parse_error : public game::error
214 {
215  parse_error(const std::string& msg) : game::error(msg) {}
216 };
217 
218 // Generator stuff below. Maybe move to a separate file? This one is
219 // getting crowded. Dunno if much more is needed though so I'll wait and
220 // see.
221 
222 /** Dispatch generators to their appropriate functions. */
223 void generate_sections(const config *help_cfg, const std::string &generator, section &sec, int level);
224 std::vector<topic> generate_topics(const bool sort_topics,const std::string &generator);
225 std::string generate_topic_text(const std::string &generator, const config *help_cfg, const section &sec);
226 std::string generate_contents_links(const std::string& section_name, config const *help_cfg);
227 std::string generate_contents_links(const section &sec);
228 
229 /**
230  * return a hyperlink with the unit's name and pointing to the unit page
231  * return empty string if this unit is hidden. If not yet discovered add the (?) suffix
232  */
233 std::string make_unit_link(const std::string& type_id);
234 /** return a list of hyperlinks to unit's pages (ordered or not) */
235 std::vector<std::string> make_unit_links_list(
236  const std::vector<std::string>& type_id_list, bool ordered = false);
237 
238 void generate_races_sections(const config *help_cfg, section &sec, int level);
239 void generate_terrain_sections(section &sec, int level);
240 std::vector<topic> generate_unit_topics(const bool, const std::string& race);
241 void generate_unit_sections(const config *help_cfg, section &sec, int level, const bool, const std::string& race);
244  /** Ignore this unit for documentation purposes. */
246  /**
247  * Although the unit itself is hidden, traits reachable via this unit are not hidden.
248  *
249  * This is a bug workaround - traits are defined by WML macros, and therefore the help
250  * system has to use a place where that macro is instanciated to provide the documentation.
251  * None of the normal unit types has the "loyal" trait, but there is a hidden unit which
252  * does, purely to support the help system.
253  */
255 };
256 /**
257  * Return the type of description that should be shown for a unit of
258  * the given kind. This method is intended to filter out information
259  * about units that should not be shown, for example due to not being
260  * encountered.
261  */
263 std::vector<topic> generate_ability_topics(const bool);
264 std::vector<topic> generate_time_of_day_topics(const bool);
265 std::vector<topic> generate_weapon_special_topics(const bool);
266 
267 void generate_era_sections(const config *help_cfg, section &sec, int level);
268 std::vector<topic> generate_faction_topics(const config &, const bool);
269 std::vector<topic> generate_era_topics(const bool, const std::string & era_id);
270 std::vector<topic> generate_trait_topics(const bool);
271 
272 /**
273  * Parse a help config, return the top level section. Return an empty
274  * section if cfg is nullptr.
275  */
276 section parse_config(const config *cfg);
277 /** Recursive function used by parse_config. */
278 void parse_config_internal(const config *help_cfg, const config *section_cfg,
279  section &sec, int level=0);
280 
281 /**
282  * Return true if the section with id section_id is referenced from
283  * another section in the config, or the toplevel.
284  */
285 bool section_is_referenced(const std::string &section_id, const config &cfg);
286 /**
287  * Return true if the topic with id topic_id is referenced from
288  * another section in the config, or the toplevel.
289  */
290 bool topic_is_referenced(const std::string &topic_id, const config &cfg);
291 
292 /**
293  * Search for the topic with the specified identifier in the section
294  * and its subsections. Return the found topic, or nullptr if none could
295  * be found.
296  */
297 const topic *find_topic(const section &sec, const std::string &id);
298 
299 /**
300  * Search for the section with the specified identifier in the section
301  * and its subsections. Return the found section or nullptr if none could
302  * be found.
303  */
304 const section *find_section(const section &sec, const std::string &id);
305 section *find_section(section &sec, const std::string &id);
306 
307 /**
308  * Parse a xml style marked up text string. Return a config with the different parts of the
309  * text. Each markup item is a separate part while the text between
310  * markups are separate parts.
311  */
312 config parse_text(const std::string &text);
313 
314 /** Make a best effort to word wrap s. All parts are less than width. */
315 std::vector<std::string> split_in_width(const std::string &s, const int font_size, const unsigned width);
316 
317 std::string remove_first_space(const std::string& text);
318 
319 /** Prepend all chars with meaning inside attributes with a backslash. */
320 std::string escape(const std::string &s);
321 
322 /** Return the first word in s, not removing any spaces in the start of it. */
323 std::string get_first_word(const std::string &s);
324 
325 /** Load the appropriate terrain types data to use */
326 std::shared_ptr<terrain_type_data> load_terrain_types_data();
327 
328 extern const game_config_view *game_cfg;
329 // The default toplevel.
331 // All sections and topics not referenced from the default toplevel.
333 
334 extern int last_num_encountered_units;
336 extern boost::tribool last_debug_state;
337 
338 extern std::vector<std::string> empty_string_vector;
339 extern const int max_section_level;
340 extern const int title_size;
341 extern const int title2_size;
342 extern const int box_width;
343 extern const int normal_font_size;
344 extern const unsigned max_history;
345 extern const std::string topic_img;
346 extern const std::string closed_section_img;
347 extern const std::string open_section_img;
348 // The topic to open by default when opening the help dialog.
349 extern const std::string default_show_topic;
350 extern const std::string unknown_unit_topic;
351 extern const std::string unit_prefix;
352 extern const std::string terrain_prefix;
353 extern const std::string race_prefix;
354 extern const std::string faction_prefix;
355 extern const std::string era_prefix;
356 extern const std::string variation_prefix;
357 extern const std::string ability_prefix;
358 
359 // id starting with '.' are hidden
360 std::string hidden_symbol(bool hidden = true);
361 
362 bool is_visible_id(const std::string &id);
363 
364 /**
365  * Return true if the id is valid for user defined topics and
366  * sections. Some IDs are special, such as toplevel and may not be
367  * be defined in the config.
368  */
369 bool is_valid_id(const std::string &id);
370 
371 // Helpers for making generation of topics easier.
372 
373 inline std::string make_link(const std::string& text, const std::string& dst)
374 {
375  // some sorting done on list of links may rely on the fact that text is first
376  return "<ref dst='" + help::escape(dst) + "'>" + help::escape(text) + "</ref>";
377 }
378 
379 inline std::string bold(const std::string &s)
380 {
381  std::stringstream ss;
382  ss << "<b>" << help::escape(s) << "</b>";
383  return ss.str();
384 }
385 
386 // A string to be displayed and its width.
387 typedef std::pair< std::string, unsigned > item;
388 
389 } // end namespace help
double t
Definition: astarsearch.cpp:63
double g
Definition: astarsearch.cpp:63
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:163
A class grating read only view to a vector of config objects, viewed as one config with all children ...
To be used as a function object to locate sections and topics with a specified ID.
Definition: help_impl.hpp:174
has_id(const std::string &id)
Definition: help_impl.hpp:176
const std::string id_
Definition: help_impl.hpp:181
bool operator()(const topic &t)
Definition: help_impl.hpp:177
bool operator()(const section &s)
Definition: help_impl.hpp:178
bool operator()(const section *s)
Definition: help_impl.hpp:179
To be used as a function object when sorting section lists on the title.
Definition: help_impl.hpp:196
bool operator()(const section &s1, const section &s2)
Definition: help_impl.hpp:198
bool operator()(const std::string &s1, const std::string &s2) const
Definition: help_impl.hpp:207
text_topic_generator(const std::string &t)
Definition: help_impl.hpp:75
virtual std::string operator()() const
Definition: help_impl.hpp:76
To be used as a function object when sorting topic lists on the title.
Definition: help_impl.hpp:186
bool operator()(const topic &t1, const topic &t2)
Definition: help_impl.hpp:188
Generate a topic text on the fly.
Definition: help_impl.hpp:65
virtual std::string operator()() const =0
virtual ~topic_generator()
Definition: help_impl.hpp:69
The text displayed in a topic.
Definition: help_impl.hpp:83
topic_text(const topic_text &t)=default
topic_text & operator=(const topic_text &t)=default
topic_text(std::shared_ptr< topic_generator > g)
Definition: help_impl.hpp:96
std::shared_ptr< topic_generator > generator_
Definition: help_impl.hpp:85
~topic_text()=default
topic_text & operator=(topic_text &&t)=default
topic_text()=default
topic_text(const std::string &t)
Definition: help_impl.hpp:90
const config & parsed_text() const
Definition: help_impl.cpp:386
topic_text(topic_text &&t)=default
config parsed_text_
Definition: help_impl.hpp:84
Contains the database of all known terrain types, both those defined explicitly by WML [terrain_type]...
Definition: type_data.hpp:40
A single unit type that the player may recruit.
Definition: types.hpp:43
Definitions for the interface to Wesnoth Markup Language (WML).
std::string id
Text to match against addon_info.tags()
Definition: manager.cpp:197
std::string get_first_word(const std::string &s)
Return the first word in s, not removing any spaces in the start of it.
Definition: help_impl.cpp:1737
std::vector< topic > generate_unit_topics(const bool sort_generated, const std::string &race)
Definition: help_impl.cpp:1058
std::string hidden_symbol(bool hidden)
Definition: help_impl.cpp:1824
void generate_unit_sections(const config *, section &sec, int, const bool, const std::string &race)
Definition: help_impl.cpp:1025
UNIT_DESCRIPTION_TYPE
Definition: help_impl.hpp:242
@ FULL_DESCRIPTION
Definition: help_impl.hpp:243
@ HIDDEN_BUT_SHOW_MACROS
Although the unit itself is hidden, traits reachable via this unit are not hidden.
Definition: help_impl.hpp:254
@ NO_DESCRIPTION
Ignore this unit for documentation purposes.
Definition: help_impl.hpp:245
std::string bold(const std::string &s)
Definition: help_impl.hpp:379
std::string make_link(const std::string &text, const std::string &dst)
Definition: help_impl.hpp:373
void generate_races_sections(const config *help_cfg, section &sec, int level)
Definition: help_impl.cpp:845
std::string escape(const std::string &s)
Prepend all chars with meaning inside attributes with a backslash.
Definition: help_impl.cpp:1857
bool topic_is_referenced(const std::string &topic_id, const config &cfg)
Return true if the topic with id topic_id is referenced from another section in the config,...
Definition: help_impl.cpp:177
std::vector< topic > generate_time_of_day_topics(const bool)
Definition: help_impl.cpp:401
int last_num_encountered_units
Definition: help_impl.cpp:73
void generate_terrain_sections(section &sec, int)
Definition: help_impl.cpp:966
std::string make_unit_link(const std::string &type_id)
return a hyperlink with the unit's name and pointing to the unit page return empty string if this uni...
Definition: help_impl.cpp:804
const std::string open_section_img
Definition: help_impl.cpp:86
const std::string unit_prefix
Definition: help_impl.cpp:90
const std::string variation_prefix
Definition: help_impl.cpp:95
void parse_config_internal(const config *help_cfg, const config *section_cfg, section &sec, int level)
Recursive function used by parse_config.
Definition: help_impl.cpp:201
bool is_visible_id(const std::string &id)
Definition: help_impl.cpp:1828
const std::string closed_section_img
Definition: help_impl.cpp:85
std::vector< topic > generate_faction_topics(const config &era, const bool sort_generated)
Definition: help_impl.cpp:647
const int box_width
Definition: help_impl.cpp:81
void generate_sections(const config *help_cfg, const std::string &generator, section &sec, int level)
Dispatch generators to their appropriate functions.
Definition: help_impl.cpp:343
const std::string topic_img
Definition: help_impl.cpp:84
UNIT_DESCRIPTION_TYPE description_type(const unit_type &type)
Return the type of description that should be shown for a unit of the given kind.
Definition: help_impl.cpp:1189
const std::string race_prefix
Definition: help_impl.cpp:92
const std::string ability_prefix
Definition: help_impl.cpp:96
std::vector< std::string > make_unit_links_list(const std::vector< std::string > &type_id_list, bool ordered)
return a list of hyperlinks to unit's pages (ordered or not)
Definition: help_impl.cpp:830
std::vector< topic > generate_topics(const bool sort_generated, const std::string &generator)
Definition: help_impl.cpp:314
const section * find_section(const section &sec, const std::string &id)
Search for the section with the specified identifier in the section and its subsections.
Definition: help_impl.cpp:1314
std::pair< std::string, unsigned > item
Definition: help_impl.hpp:387
const int title2_size
Definition: help_impl.cpp:80
const int normal_font_size
Definition: help_impl.cpp:82
void generate_contents()
Generate the help contents from the configurations given to the manager.
Definition: help_impl.cpp:1763
const std::string terrain_prefix
Definition: help_impl.cpp:91
std::vector< topic > generate_weapon_special_topics(const bool sort_generated)
Definition: help_impl.cpp:448
std::vector< topic > generate_ability_topics(const bool sort_generated)
Definition: help_impl.cpp:545
std::string remove_first_space(const std::string &text)
Definition: help_impl.cpp:1729
const std::string unknown_unit_topic
Definition: help_impl.cpp:89
const int max_section_level
Definition: help_impl.cpp:78
const unsigned max_history
Definition: help_impl.cpp:83
std::vector< std::string > empty_string_vector
Definition: help_impl.cpp:77
bool section_is_referenced(const std::string &section_id, const config &cfg)
Return true if the section with id section_id is referenced from another section in the config,...
Definition: help_impl.cpp:153
std::shared_ptr< terrain_type_data > load_terrain_types_data()
Load the appropriate terrain types data to use.
Definition: help_impl.cpp:1863
bool is_valid_id(const std::string &id)
Return true if the id is valid for user defined topics and sections.
Definition: help_impl.cpp:1837
boost::tribool last_debug_state
Definition: help_impl.cpp:75
std::string generate_contents_links(const std::string &section_name, config const *help_cfg)
Definition: help_impl.cpp:1209
std::vector< std::string > split_in_width(const std::string &s, const int font_size, const unsigned width)
Make a best effort to word wrap s.
Definition: help_impl.cpp:1710
std::string generate_topic_text(const std::string &generator, const config *help_cfg, const section &sec)
Definition: help_impl.cpp:362
std::list< topic > topic_list
Definition: help_impl.hpp:143
help::section default_toplevel
Definition: help_impl.cpp:69
const topic * find_topic(const section &sec, const std::string &id)
Search for the topic with the specified identifier in the section and its subsections.
Definition: help_impl.cpp:1298
section parse_config(const config *cfg)
Parse a help config, return the top level section.
Definition: help_impl.cpp:304
std::vector< topic > generate_era_topics(const bool sort_generated, const std::string &era_id)
Definition: help_impl.cpp:611
const game_config_view * game_cfg
Definition: help_impl.cpp:67
int last_num_encountered_terrains
Definition: help_impl.cpp:74
std::list< section > section_list
Definition: help_impl.hpp:141
help::section hidden_sections
Definition: help_impl.cpp:71
std::vector< topic > generate_trait_topics(const bool sort_generated)
Definition: help_impl.cpp:722
const std::string default_show_topic
Definition: help_impl.cpp:88
void generate_era_sections(const config *help_cfg, section &sec, int level)
Definition: help_impl.cpp:943
const std::string era_prefix
Definition: help_impl.cpp:94
const int title_size
Definition: help_impl.cpp:79
config parse_text(const std::string &text)
Parse a xml style marked up text string.
Definition: help_impl.cpp:1694
const std::string faction_prefix
Definition: help_impl.cpp:93
rng * generator
This generator is automatically synced during synced context.
Definition: random.cpp:60
int compare(const std::string &s1, const std::string &s2)
Case-sensitive lexicographical comparison.
Definition: gettext.cpp:502
static void msg(const char *act, debug_info &i, const char *to="", const char *result="")
Definition: debugger.cpp:109
rect dst
Location on the final composed sheet.
Base class for all the errors encountered by the engine.
Definition: exceptions.hpp:29
Thrown when the help system fails to parse something.
Definition: help_impl.hpp:214
parse_error(const std::string &msg)
Definition: help_impl.hpp:215
A section contains topics and sections along with title and ID.
Definition: help_impl.hpp:146
section_list sections
Definition: help_impl.hpp:166
bool operator<(const section &) const
Comparison on the ID.
Definition: help_impl.cpp:1282
void add_section(const section &s)
Allocate memory for and add the section.
Definition: help_impl.cpp:1287
std::string id
Definition: help_impl.hpp:164
std::string title
Definition: help_impl.hpp:164
bool operator==(const section &) const
Two sections are equal if their IDs are equal.
Definition: help_impl.cpp:1277
topic_list topics
Definition: help_impl.hpp:165
A topic contains a title, an id and some text.
Definition: help_impl.hpp:113
topic(const std::string &_title, const std::string &_id, std::shared_ptr< topic_generator > g)
Definition: help_impl.hpp:130
bool operator==(const topic &) const
Two topics are equal if their IDs are equal.
Definition: help_impl.cpp:1267
std::string id
Definition: help_impl.hpp:137
topic(const std::string &_title, const std::string &_id, const std::string &_text)
Definition: help_impl.hpp:128
topic_text text
Definition: help_impl.hpp:138
bool operator!=(const topic &t) const
Definition: help_impl.hpp:134
bool operator<(const topic &) const
Comparison on the ID.
Definition: help_impl.cpp:1272
std::string title
Definition: help_impl.hpp:137
topic(const std::string &_title, const std::string &_id)
Definition: help_impl.hpp:121
static map_location::DIRECTION s