ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
escaper.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_strings 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 strings::util {
9
10
11/// This is a virtual base type defining the interface for derived struct
12/// \alib{strings::util;StringEscaperStandard} and possible custom derivates.<br>
13/// However, this class is not abstract but instead implements the interface by just copying
14/// the strings to the given target buffers. The rationale for this is that it can be used
15/// in situations, where no externalization and import of externalized strings are needed.
16/// In other words: In situations where a function expects a \b StringEscaper where none is necessary
17/// a local instance of this type can be created and just passed.
18///
19/// @see
20/// Any further explanation is found with the documentation of derived type
21/// \alib{strings::util;StringEscaperStandard}.
23{
24 /// Virtual destructor.
25 virtual ~StringEscaper() {}
26
27 //==============================================================================================
28 /// Just copies the given \p{src} string to \p{dest}.
29 ///
30 /// @param src The source string.
31 /// @param dest The destination string.
32 /// @param delimiters Ignored
33 /// @return \p{dest} to allow concatenated operations.
34 //==============================================================================================
35 virtual inline
36 AString& Escape( const String& src, AString& dest, const String& delimiters ) const
37 { (void) delimiters; return dest << src; }
38
39 //==============================================================================================
40 /// Just copies the given \p{src} string to \p{dest}.
41 ///
42 /// @param src The source string.
43 /// @param dest The destination string.
44 /// @return \p{dest} to allow concatenated operations.
45 //==============================================================================================
46 virtual inline
47 AString& Unescape( const String& src, AString& dest ) const
48 { return dest << src; }
49
50#if ALIB_MONOMEM
51 //==============================================================================================
52 /// Simply tokenizes \p{src} and feeds the tokens into \p{result}.
53 ///
54 /// \par Availability
55 /// This method is defined only if module \alib_monomem is included in the \alibbuild.
56 /// @param result The destination list of strings.
57 /// @param src The source string.
58 /// @param delimiters A set of characters accepted as delimiters.
59 /// @return The number of tokens found.
60 //==============================================================================================
61 ALIB_DLL virtual
62 int EscapeTokens( StringVectorMA& result, const String& src, const String& delimiters) const;
63
64 //==============================================================================================
65 /// Simply tokenizes \p{src} and feeds the tokens into \p{result}.
66 /// (In fact, #EscapeTokens is called.)
67 ///
68 /// \par Availability
69 /// This method is defined only if module \alib_monomem is included in the \alibbuild.
70 /// @param result The destination list of strings.
71 /// @param src The source string.
72 /// @param delimiters A set of characters accepted as delimiters.
73 /// @return The number of tokens found.
74 //==============================================================================================
75 virtual inline
76 int UnescapeTokens(StringVectorMA& result, const String& src, const String& delimiters) const
77 { return EscapeTokens( result, src, delimiters); }
78
79#endif // #if ALIB_MONOMEM
80
81}; // StringEscaper
82
83//==================================================================================================
84/// This struct implements the interface given with \alib{strings::util;StringEscaper}.
85/// Its purpose is to convert string data to external string representations and vice versa.
86/// Such conversion is needed when C++ strings contain non-readable characters like
87/// 'new line', 'carriage return' or 'tabulator' and such strings should be stored in ASCII or
88/// unicode files. The common way of conversion is to add "escape sequences", for example <c>"\n"</c>
89/// for the 'new line' character.
90///
91/// Furthermore if a C++ string starts or ends with spaces, the string has to be quoted and in this
92/// case occurences of the quote character <c>(\")</c> inside the string have to be escaped.
93/// Quotation is also needed, if a series of strings, separated by possible delimiter characters
94/// needs to be escaped, and a string contains one of the delimiters itself. Likewise, when such
95/// string is imported back to C++ representation, delimiters must only be recognized when outside
96/// of quoted string tokens.
97///
98/// With this approach, this implementation should be compatible with INI-files, JSon files
99/// and such. If a different approach is needed, the virtual functions may be overridden by
100/// custom descendents.
101///
102/// ---------------------------
103/// This default implementation proceeds as follows:
104/// - "Externalizing" a value:
105/// - Value is surrounded by quotes if it starts or ends with spaces or if it includes one of
106/// the delimiter tokens.
107/// - A few characters are escaped using \c '\\'. Those are
108/// \c \\n, \c \\r, \c \\t , \c \\a, \c \\b, \c \\v, \c \\f, \c \\e and also
109/// the double quotation marks \c \\" and the backslash itself (\c \\\\‍).
110///
111/// - "Internalizing" a value:
112/// - If (non-escaped) quote \c " characters are found, those are removed and whitespaces
113/// within such quotes are kept.
114/// - Escaped characters are converted to their original value.
115///
116/// - Loading variables from external strings:
117/// - If the provided variable has a valid delimiter, this character is used to tokenize
118/// the external string.
119/// - Values are trimmed, unless quoted. Quoted characters themselves are removed.
120/// - Delimiters found within a pair of quotes are ignored.
121/// - Each value found is internalized separately.
122//==================================================================================================
124{
125 /// Virtual destructor.
126 virtual ~StringEscaperStandard() override {}
127
128 //==============================================================================================
129 /// Converts the given \p{src} string to an external representation.
130 /// The escape symbol is backslash \c '\\' and the following characters are escaped:
131 /// \c \\n, \c \\r, \c \\t , \c \\a, \c \\b, \c \\v, \c \\f, \c \\e. Furthermore
132 /// the double quotation marks \c \\" and the backslash itself (\c \\\\‍).<br>
133 ///
134 /// Besides that, the value is surrounded by double quotes \c " if it starts or ends with spaces
135 /// or if it includes one of the delimiter characters. The rationale of the latter is understood
136 /// when it comes to method #UnescapeTokens: Here, delimiters are ignored if they reside in a
137 /// quoted string. If neither trailing nor leading spaces nor a delimiter is found, the string
138 /// is \b not quoted. In situations, a quoted string is always needed, the caller has to test
139 /// if a string was quoted and add the quote after the invocation of this method.
140 ///
141 /// @param src The source string to convert to external representation.
142 /// @param dest The destination string buffer.
143 /// @param delimiters If one of these characters is found in the string, the value is quoted
144 /// @return \p{dest} to allow concatenated operations.
145 //==============================================================================================
146 ALIB_DLL virtual
147 AString& Escape( const String& src, AString& dest, const String& delimiters ) const override;
148
149 //==============================================================================================
150 /// Trims \p{src}, removes surrounding quotes and, un-escapes characters as defined with
151 /// method #Escape.
152 ///
153 /// @param src The source string.
154 /// @param dest The destination string.
155 /// @return \p{dest} to allow concatenated operations.
156 //==============================================================================================
157 ALIB_DLL virtual
158 AString& Unescape( const String& src, AString& dest ) const override;
159
160#if ALIB_MONOMEM
161 //==============================================================================================
162 /// Parses a list of tokens separated by the given \p{delimiter} and calls method
163 /// #Escape for each of them. The results are copied to string list \p{result}.
164 ///
165 /// \par Availability
166 /// This method is defined only if module \alib_monomem is included in the \alibbuild.
167 ///
168 /// @param result The destination list of strings.
169 /// @param src The source string.
170 /// @param delimiters A set of characters defining the delimiters.
171 /// @return The number of tokens found.
172 //==============================================================================================
173 ALIB_DLL virtual
174 int EscapeTokens( StringVectorMA& result, const String& src, const String& delimiters ) const override;
175
176 //==============================================================================================
177 /// Parses a list of tokens separated by the given \p{delimiter} and calls method
178 /// #Unescape for each of them. The results are copied to string list \p{result}.
179 /// Delimiters found within quoted strings are rightfully ignored.
180 ///
181 /// \par Availability
182 /// This method is defined only if module \alib_monomem is included in the \alibbuild.
183 /// @param result The destination list of strings.
184 /// @param src The source string.
185 /// @param delimiters A set of characters accepted as delimiters.
186 /// @return The number of tokens found.
187 //==============================================================================================
188 ALIB_DLL virtual
189 int UnescapeTokens(StringVectorMA& result,
190 const String& src , const String& delimiters) const override;
191#endif //#if ALIB_MONOMEM
192
193}; // struct StringEscaperStandard
194
195
196} // namespace alib::[strings::util]
197
198/// Type alias in namespace \b alib.
200
201/// Type alias in namespace \b alib.
203
204
205} // namespace [alib]
206
207
#define ALIB_DLL
Definition alib.inl:496
#define ALIB_EXPORT
Definition alib.inl:488
strings::TEscape< character > Escape
Type alias in namespace alib.
Definition format.inl:536
strings::util::StringEscaper StringEscaper
Type alias in namespace alib.
Definition escaper.inl:199
strings::TAString< character, lang::HeapAllocator > AString
Type alias in namespace alib.
strings::util::TStringVector< character, MonoAllocator > StringVectorMA
Type alias in namespace alib.
strings::TString< character > String
Type alias in namespace alib.
Definition string.inl:2381
strings::util::StringEscaperStandard StringEscaperStandard
Type alias in namespace alib.
Definition escaper.inl:202
virtual ALIB_DLL AString & Unescape(const String &src, AString &dest) const override
Definition escaper.cpp:48
virtual ALIB_DLL int UnescapeTokens(StringVectorMA &result, const String &src, const String &delimiters) const override
Definition escaper.cpp:155
virtual ~StringEscaperStandard() override
Virtual destructor.
Definition escaper.inl:126
virtual ALIB_DLL int EscapeTokens(StringVectorMA &result, const String &src, const String &delimiters) const override
Definition escaper.cpp:141
virtual ~StringEscaper()
Virtual destructor.
Definition escaper.inl:25
virtual ALIB_DLL int EscapeTokens(StringVectorMA &result, const String &src, const String &delimiters) const
Definition escaper.cpp:33
virtual int UnescapeTokens(StringVectorMA &result, const String &src, const String &delimiters) const
Definition escaper.inl:76
virtual AString & Unescape(const String &src, AString &dest) const
Definition escaper.inl:47
virtual AString & Escape(const String &src, AString &dest, const String &delimiters) const
Definition escaper.inl:36