KTextTemplate

filterexpression.h
1/*
2 This file is part of the KTextTemplate library
3
4 SPDX-FileCopyrightText: 2009, 2010 Stephen Kelly <steveire@gmail.com>
5
6 SPDX-License-Identifier: LGPL-2.1-or-later
7
8*/
9
10#ifndef KTEXTTEMPLATE_FILTEREXPRESSION_H
11#define KTEXTTEMPLATE_FILTEREXPRESSION_H
12
13#include "variable.h"
14
15#include "ktexttemplate_export.h"
16
17namespace KTextTemplate
18{
19class Filter;
20class OutputStream;
21class Parser;
22struct Token;
23
24class FilterExpressionPrivate;
25
26/// @headerfile filterexpression.h <KTextTemplate/FilterExpression>
27
28/**
29 @brief A **%FilterExpression** object represents a filter expression in a
30 template.
31
32 This class is only relevant if implementing custom tags or filters. Most of
33 the API here is internal.
34 Usually when implementing tags or filters, filter expressions will just be
35 created and resolved.
36
37 In template markup, a filter expression is a variable followed by one or more
38 filters separated by pipes:
39
40 %Filter expressions may appear in variable nodes:
41 @code
42 {{ some_var|upper_filter|lower_filter }}
43 @endcode
44
45 Or as arguments to tags
46 @code
47 {% some_tag some_arg1|filter1|filter2 some_arg2|filter3 %}
48 @endcode
49
50 The **%FilterExpression** class would be used in the getNode implementation of
51 the AbstractNodeFactory implementation for the <tt>some_tag</tt> tag.
52
53 @code
54 Node* SomeTagFactory::getNode(const QString &tagContent, Parser *p) const {
55 auto parts = smartSplit( tagContent );
56
57 parts.removeFirst(); // Remove the "some_tag" part.
58
59 FilterExpression arg1( parts.first(), p );
60 FilterExpression arg2( parts.at( 1 ), p );
61
62 return new SomeTagNode( arg1, arg2, p );
63 }
64 @endcode
65
66 @see AbstractNodeFactory::getFilterExpressionList
67
68 When implementing the Node::render method, the @ref resolve method may be used
69 to process the filter expression.
70
71 For example, if our <tt>SomeTagNode</tt> was to concatenate the resolved
72 values given as arguments:
73
74 @code
75 void SomeTagNode::render( QTextStream *stream, Context *c ) {
76 m_arg1.resolve( stream, c );
77 m_arg2.resolve( stream, c );
78 }
79 @endcode
80
81 Because Filters are highly generic, they do not all write data to the stream.
82 For example, a Filter might take as input a string, and return a list by
83 splitting the string on commas, or a Filter might compare an input to its
84 argument and return whether they are the same, but not write anything to the
85 stream. For that reason, the @ref resolve method writes data to the given
86 stream, and returns the same data in its returned QVariant.
87
88 The suitability of either of the @ref resolve methods will depend on the
89 implementation and requirements of your custom tag. For example if the
90 <tt>SomeTagNode</tt> ran a comparison of the arguments:
91
92 @code
93 void SomeTagNode::render( QTextStream *stream, Context *c ) {
94 QString first = m_arg1.resolve( c ).toString();
95 QString second = m_arg2.resolve( c ).toString();
96
97 if ( first == second )
98 m_trueList.render( stream, c );
99 else
100 m_falseList.render( stream, c );
101 }
102 @endcode
103
104 @see @ref tags_with_end_tags
105
106 @author Stephen Kelly <steveire@gmail.com>
107*/
108class KTEXTTEMPLATE_EXPORT FilterExpression
109{
110public:
111 /**
112 Constructs an invalid **%FilterExpression**.
113 */
115
116 /**
117 Constructs a filter expression from the string @p varString. The Parser @p
118 parser is used to retrieve filters.
119 */
120 FilterExpression(const QString &varString, KTextTemplate::Parser *parser);
121
122 /**
123 Copy constructor.
124 */
126
127 /**
128 Destructor.
129 */
131
132 /**
133 Assignment operator.
134 */
135 FilterExpression &operator=(const FilterExpression &other);
136
137 /**
138 Returns the initial variable in the **%FilterExpression**.
139 */
140 Variable variable() const;
141
142 /**
143 Resolves the **%FilterExpression** in the Context @p c and writes it to the
144 stream @p stream.
145 */
146 QVariant resolve(OutputStream *stream, Context *c) const;
147
148 /**
149 Resolves the **%FilterExpression** in the Context @p c.
150 */
151 QVariant resolve(Context *c) const;
152
153 /**
154 Returns whether the Filter resolves to true in the Context @p c.
155 @see @ref truthiness
156 */
157 bool isTrue(Context *c) const;
158
159 /**
160 Returns a list for the **%FilterExpression**.
161
162 If the **%FilterExpression** can not be resolved to a list, an empty list
163 will be returned.
164 */
165 QVariantList toList(Context *c) const;
166
167 /**
168 Returns whether a filter expression is valid.
169
170 A **%FilterExpression** is valid if all filters in the expression exist and
171 the initial variable being filtered is valid.
172 */
173 bool isValid() const;
174
175#ifndef K_DOXYGEN
176 /**
177 @internal
178 Returns the list of filters in the **%FilterExpression**.
179 */
180 QStringList filters() const;
181#endif
182
183private:
184 Q_DECLARE_PRIVATE(FilterExpression)
185 FilterExpressionPrivate *const d_ptr;
186};
187}
188
189#endif
The Context class holds the context to render a Template with.
Definition context.h:107
A FilterExpression object represents a filter expression in a template.
The OutputStream class is used to render templates to a QTextStream.
The Parser class processes a string template into a tree of nodes.
Definition parser.h:38
A container for static variables defined in Templates.
Definition variable.h:42
The KTextTemplate namespace holds all public KTextTemplate API.
Definition Mainpage.dox:8
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 7 2024 12:07:35 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.