ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
expressionformatter.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_expressions of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
8ALIB_EXPORT namespace alib { namespace expressions::util {
9
10//==================================================================================================
11/// This class allows using \alib_expressions_nl within format strings used with
12/// \alib{format;Formatter;ALib Formatters} and thus allows exposing customizable format
13/// strings to end-users, which leverage an application's expression subsystem.
14///
15/// To understand the concept of this class, please read the documentation of class
16/// \alib{format;PropertyFormatter} \b first, which is almost a 1:1 copy of this class but
17/// uses simple "property callback functions" instead of expressions.
18///
19/// \note
20/// This documentation rather documents the differences to \b %PropertyFormatter instead of
21/// repeating what is explained already in the sibling class.
22///
23/// This class can be used in the same way as \alib{format;PropertyFormatter}. However,
24/// instead of the provision of a table of type
25/// \alib{format;PropertyFormatter::TCallbackTable}, this class expects an expression
26/// compiler in the constructor.
27///
28/// With that, simple expressions comprising just a single identifier term can be used in
29/// exactly the same way as demonstrated with \b PropertyFormatter. For example, format string:
30///
31/// "{name} is aged {age} and his/her hobby is {hobby}"
32///
33/// would compile three expressions (<em>"name"</em>, <em>"age"</em> and <em>"hobby"</em>) and
34/// convert the format string to just
35///
36/// "{} is aged {} and his/her hobby is {}"
37///
38/// Then, with the invocation of method #Format, an expression scope has to be provided, which
39/// is used to evaluate each expression and add the result value to the list of format parameters.
40///
41/// To separate the given expressions strings from other formatting information provided in a
42/// placeholder, a special separator character is used. This character is provided with construction
43/// and defaults to the symbol \c '@'. A format string that uses
44/// \alib{format;FormatterPythonStyle;python formatting syntax} might look like this:
45///
46/// "The surface is {width * height@:>5.2} sqm."
47///
48/// <p>
49///\I{#############################################################################################}
50/// # Reference Documentation #
51/// @throws alib::format::FMTExceptions::UnknownPropertyInFormatString \I{CLANGDUMMY}
52//==================================================================================================
54{
55 protected:
56 /// The expression compiler (as given in the constructor).
58
59 /// The formatter to use (as given in the constructor).
61
62 /// The original format string. Used only for exception information.
64
65 /// The resulting format string passed to \alib formatters.
67
68 /// The expressions functions to receive the format data.
69 std::vector<Expression> expressions;
70
71 public:
72
73 //==========================================================================================
74 /// Constructor. Processes the given format string and compiles embedded expressions, which
75 /// are then used with invocations of method #Format.
76 ///
77 /// @param formatString The format string as described in the class documentation.
78 /// @param compiler The expression compiler.
79 /// @param formatter The formatter to use. Defaults to \c nullptr which selects
80 /// \alib{format;Formatter::Default;default formatter}.
81 /// @param separatorChar The character that is to be used to separate the expression
82 /// from the placeholder format information in
83 /// \p{customFormatString}.<br>
84 /// Defaults to <c>'@'</c>.
85 ///
86 /// @throws alib::format::FMTExceptions::UnknownPropertyInFormatString. \I{CLANGDUMMY}
87 //==========================================================================================
89 ExpressionFormatter( const String formatString,
91 SPFormatter formatter = nullptr,
92 character separatorChar = '@' );
93
94 //==========================================================================================
95 /// Writes the formatted output of the expressions in accordance to the given \p{scope}
96 /// object to given \p{target} string.
97 ///
98 /// @param target The target string to write into.
99 /// @param scope The scope used to evaluate the expressions found in the format string.
100 //==========================================================================================
102 void Format( AString& target, expressions::Scope& scope );
103
104}; // class ExpressionFormatter
105
106} // namespace alib[::expressions::util]
107
108/// Type alias in namespace \b alib.
110
111} // namespace [alib]
112
Compiler * compiler
The expression compiler (as given in the constructor).
AString formatStringStripped
The resulting format string passed to ALib formatters.
ALIB_DLL ExpressionFormatter(const String formatString, Compiler *compiler, SPFormatter formatter=nullptr, character separatorChar='@')
SPFormatter stdFormatter
The formatter to use (as given in the constructor).
ALIB_DLL void Format(AString &target, expressions::Scope &scope)
const AString originalFormatString
The original format string. Used only for exception information.
std::vector< Expression > expressions
The expressions functions to receive the format data.
#define ALIB_DLL
Definition alib.inl:496
#define ALIB_EXPORT
Definition alib.inl:488
Utility types of camp ALib Expressions.
strings::TAString< character, lang::HeapAllocator > AString
Type alias in namespace alib.
expressions::util::ExpressionFormatter ExpressionFormatter
Type alias in namespace alib.
containers::SharedPtr< format::Formatter > SPFormatter
Definition formatter.inl:42
strings::TString< character > String
Type alias in namespace alib.
Definition string.inl:2381
characters::character character
Type alias in namespace alib.