KTextTemplate

outputstream.h
1/*
2 This file is part of the KTextTemplate library
3
4 SPDX-FileCopyrightText: 2010 Stephen Kelly <steveire@gmail.com>
5
6 SPDX-License-Identifier: LGPL-2.1-or-later
7
8*/
9
10#ifndef KTEXTTEMPLATE_OUTPUTSTREAM_H
11#define KTEXTTEMPLATE_OUTPUTSTREAM_H
12
13#include "ktexttemplate_export.h"
14
15#include <QSharedPointer>
16#include <QTextStream>
17
18namespace KTextTemplate
19{
20
21class SafeString;
22
23/// @headerfile outputstream.h <KTextTemplate/OutputStream>
24
25/**
26 @brief The **%OutputStream** class is used to render templates to a
27 QTextStream
28
29 A **%OutputStream** instance may be passed to the render method of a Template
30 to render the template to a stream.
31
32 @code
33 QFile outputFile("./output");
34 outputFile.open(QFile::WriteOnly);
35 QTextStream tstream( &outputFile );
36
37 OutputStream os(&tstream);
38 t->render( &os, &context );
39 @endcode
40
41 The **%OutputStream** is used to escape the content streamed to it. By
42 default, the escaping is html escaping, converting "&" to "&amp;" for example.
43 If generating non-html output, the @ref escape method may be overriden to
44 perform a different escaping, or non at all.
45
46 If overriding the @ref escape method, the @ref clone method must also be
47 overriden to return an **%OutputStream** with the same escaping behaviour.
48
49 @code
50 class NoEscapeStream : public KTextTemplate::OutputStream
51 {
52 public:
53 // ...
54
55 QString escape( const QString &input ) const
56 {
57 return input;
58 }
59
60 QSharedPointer<OutputStream> clone( QTextStream *stream ) const
61 {
62 return QSharedPointer<NoEscapeStream>::create( stream );
63 }
64 };
65 @endcode
66
67 @author Stephen Kelly <steveire@gmail.com>
68*/
69class KTEXTTEMPLATE_EXPORT OutputStream
70{
71public:
72 /**
73 Creates a null **%OutputStream**. Content streamed to
74 this **%OutputStream** is sent to <tt>/dev/null</tt>
75 */
77
78 /**
79 Creates an **%OutputStream** which will stream content to @p stream
80 with appropriate escaping.
81 */
82 explicit OutputStream(QTextStream *stream);
83
84 /**
85 Destructor
86 */
87 virtual ~OutputStream();
88
89 /**
90 Returns an escaped version of @p input. Does not write anything to the
91 stream.
92 */
93 virtual QString escape(const QString &input) const;
94
95 /**
96 Returns an escaped version of @p input. Does not write anything to the
97 stream.
98 */
99 QString escape(const SafeString &input) const;
100
101 /**
102 Returns a cloned **%OutputStream** with the same filtering behaviour.
103 */
104 virtual QSharedPointer<OutputStream> clone(QTextStream *stream) const;
105
106 /**
107 Returns @p after escaping it, unless @p input is "safe", in which case,
108 @p input is returned unmodified.
109 */
110 QString conditionalEscape(const KTextTemplate::SafeString &input) const;
111
112 /**
113 Writes @p input to the stream after escaping it.
114 */
115 OutputStream &operator<<(const QString &input);
116
117 /**
118 Writes @p input to the stream after escaping it if necessary.
119 */
120 OutputStream &operator<<(const SafeString &input);
121
122 /**
123 Reads the content of @p stream and writes it unmodified to the result
124 stream.
125 */
126 OutputStream &operator<<(QTextStream *stream);
127
128private:
129 QTextStream *m_stream;
130 Q_DISABLE_COPY(OutputStream)
131};
132}
133
134#endif
The OutputStream class is used to render templates to a QTextStream.
virtual ~OutputStream()
Destructor.
A QString wrapper class for containing whether a string is safe or needs to be escaped.
Definition safestring.h:81
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 Jul 19 2024 11:59:16 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.