The Battle for Wesnoth  1.19.6+dev
markup.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2024
3  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 #pragma once
16 
17 #include "color.hpp"
18 #include "config.hpp"
19 // This file isn't needed by any of these functions, but this allows any
20 // standard color to be passed to span_color without an extra include.
21 #include "font/standard_colors.hpp"
22 #include "formatter.hpp"
24 
25 #include <string>
26 
27 namespace markup {
28 
29 /**
30  * @return A Help markup tag corresponding to a linebreak.
31  * @see gui2::rich_label for details on how this tag is parsed.
32  */
33 const static std::string br = "<br/>";
34 
35 /**
36  * @return The contents enclosed inside `<tag_name>` and `</tag_name>`.
37  * Does not escape its contents and returns empty string
38  * if empty or no contents is passed.
39  *
40  * @param tag_name Name of the tag.
41  * @param contents Variable list of contents to enclose inside @p tag_name.
42  * Could anything that can be appended to a @ref formatter.
43  */
44 template<typename... Args>
45 std::string tag(const std::string& tag_name, Args&&... contents)
46 {
47  std::string input_text = ((formatter()) << ... << contents);
48  if (input_text.empty()) {
49  return "";
50  } else {
51  return formatter()
52  << "<" << tag_name << ">"
53  << input_text
54  << "</" << tag_name << ">";
55  }
56 }
57 
58 /**
59  * @return A Pango formatting string using the provided color_t object.
60  * The string returned will be in format: `<span foreground=#color>#data</span>`.
61  *
62  * @param color The color_t object from which to retrieve the color.
63  * @param data Variable list of contents to enclose inside the span tag.
64  * Could anything that can be appended to a @ref formatter.
65  * This function does not escape data internally, so data should be escaped by the caller if needed.
66  */
67 template<typename... Args>
68 std::string span_color(const color_t& color, Args&&... data)
69 {
70  std::string input_text = ((formatter()) << ... << data);
71  if (input_text.empty()) {
72  return "";
73  } else {
74  return formatter()
75  << "<span color='" << color.to_hex_string() << "'>" << input_text << "</span>";
76  }
77 }
78 
79 /**
80  * @return A Pango formatting string using the provided hex color string.
81  * The string returned will be in format: `<span foreground=#color>#data</span>`.
82  *
83  * @param color The hex color string.
84  * @param data Variable list of contents to enclose inside the span tag.
85  * Could anything that can be appended to a @ref formatter.
86  * This function does not escape data internally, so data should be escaped by the caller if needed.
87  */
88 template<typename... Args>
89 std::string span_color(const std::string& color, Args&&... data)
90 {
91  std::string input_text = ((formatter()) << ... << data);
92  if (input_text.empty()) {
93  return "";
94  } else {
95  return formatter()
96  << "<span color='" << color << "'>" << input_text << "</span>";
97  }
98 }
99 
100 /**
101  * @return A Pango formatting string that set the font size of the enclosed data.
102  * The string returned will be in format: `<span size=#size>#data</span>`.
103  *
104  * @param size The font size. String so values like x-large, large etc could be used.
105  * @param data Variable list of contents to enclose inside the span tag.
106  * Could anything that can be appended to a @ref formatter.
107  * This function does not escape data internally, so data should be escaped by the caller if needed.
108  */
109 template<typename... Args>
110 std::string span_size(const std::string& size, Args&&... data)
111 {
112  std::string input_text = ((formatter()) << ... << data);
113  if (input_text.empty()) {
114  return "";
115  } else {
116  return formatter()
117  << "<span size='" << size << "'>" << input_text << "</span>";
118  }
119 }
120 
121 /**
122  * @return A Pango formatting string corresponding to bold formatting.
123  *
124  * @param data Variable list of contents to enclose inside the bold tag. Could anything that can be appended to a @ref formatter.
125  * This function does not escape data internally, so data should be escaped by the caller if needed.
126  */
127 template<typename... Args>
128 std::string bold(Args&&... data)
129 {
130  return tag("b", (formatter() << ... << data).str());
131 }
132 
133 /**
134  * @return A Pango formatting string corresponding to italic formatting.
135  *
136  * @param data Variable list of contents to enclose inside the italic tag. Could anything that can be appended to a @ref formatter.
137  * This function does not escape data internally, so data should be escaped by the caller if needed.
138  */
139 template<typename... Args>
140 std::string italic(Args&&... data)
141 {
142  return tag("i", (formatter() << ... << data).str());
143 }
144 
145 /**
146  * @return A Help markup tag corresponding to an image. This function does not escape
147  * strings internally, so should be escaped by the caller if needed.
148  *
149  * @param src The WML path to where the image is located. (i.e., 'units/drakes/arbiter.png')
150  * @param align Alignment of this image. Possible values: left, right, center.
151  * @param floating Is the image a floating image or an inline image?
152  *
153  * @see gui2::rich_label for details on how this tag is parsed.
154  *
155  */
156 std::string img(const std::string& src, const std::string& align = "left", const bool floating = false);
157 
158 /**
159  * @return A Help markup tag corresponding to a reference or link. This function does not
160  * escape strings internally, so should be escaped by the caller if needed.
161  *
162  * @param text User visible text/caption of the link.
163  * @param dst Destination of the link. Can be any string depending on the link handler in the parsing @ref gui2::rich_label.
164  *
165  * @see gui2::rich_label for details on how this tag is parsed.
166  */
167 std::string make_link(const std::string& text, const std::string& dst);
168 
169 //
170 // Markup Parser
171 //
172 
173 /** Thrown when the help system fails to parse something. */
174 struct parse_error : public game::error
175 {
176  parse_error(const std::string& msg) : game::error(msg) {}
177 };
178 
179 /**
180  * Parse a xml style marked up text string. Return a config with the different parts of the
181  * text. Each markup item is a separate part while the text between
182  * markups are separate parts.
183  */
184 config parse_text(const std::string &text);
185 
186 } //end namespace markup
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:172
std::ostringstream wrapper.
Definition: formatter.hpp:40
Definitions for the interface to Wesnoth Markup Language (WML).
std::string italic(Args &&... data)
Definition: markup.hpp:140
static const std::string br
Definition: markup.hpp:33
std::string span_size(const std::string &size, Args &&... data)
Definition: markup.hpp:110
std::string make_link(const std::string &text, const std::string &dst)
Definition: markup.cpp:23
std::string img(const std::string &src, const std::string &align, const bool floating)
Definition: markup.cpp:29
std::string tag(const std::string &tag_name, Args &&... contents)
Definition: markup.hpp:45
std::string bold(Args &&... data)
Definition: markup.hpp:128
std::string span_color(const color_t &color, Args &&... data)
Definition: markup.hpp:68
config parse_text(const std::string &text)
Parse a xml style marked up text string.
Definition: markup.cpp:401
std::size_t size(const std::string &str)
Length in characters of a UTF-8 string.
Definition: unicode.cpp:85
static void msg(const char *act, debug_info &i, const char *to="", const char *result="")
Definition: debugger.cpp:109
std::string_view data
Definition: picture.cpp:178
rect dst
Location on the final composed sheet.
rect src
Non-transparent portion of the surface to compose.
The basic class for representing 8-bit RGB or RGBA colour values.
Definition: color.hpp:59
std::string to_hex_string() const
Returns the stored color in rrggbb hex format.
Definition: color.cpp:88
Base class for all the errors encountered by the engine.
Definition: exceptions.hpp:29
Thrown when the help system fails to parse something.
Definition: markup.hpp:175
parse_error(const std::string &msg)
Definition: markup.hpp:176