← Back to branch summary

~ubuntu-branches/ubuntu/precise/grantlee/precise

« back to all changes in this revision

Viewing changes to corelib/outputstream.h

  • Committer: Bazaar Package Importer
  • Author(s): Harald Sitter
  • Date: 2010-06-11 23:41:45 UTC
  • Revision ID: james.westby@ubuntu.com-20100611234145-oas7rhdrbwy8j55c
Tags: upstream-0.1.1
Import upstream version 0.1.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
corelib/outputstream.h
 
1
/*
 
2
  This file is part of the Grantlee template system.
 
3
 
 
4
  Copyright (c) 2010 Stephen Kelly <steveire@gmail.com>
 
5
 
 
6
  This library is free software; you can redistribute it and/or
 
7
  modify it under the terms of the GNU Lesser General Public
 
8
  License as published by the Free Software Foundation; either version
 
9
  2 of the Licence, or (at your option) any later version.
 
10
 
 
11
  This library is distributed in the hope that it will be useful,
 
12
  but WITHOUT ANY WARRANTY; without even the implied warranty of
 
13
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 
14
  Library General Public License for more details.
 
15
 
 
16
  You should have received a copy of the GNU Lesser General Public
 
17
  License along with this library.  If not, see <http://www.gnu.org/licenses/>.
 
18
 
 
19
*/
 
20
 
 
21
#ifndef GRANTLEE_OUTPUTSTREAM_H
 
22
#define GRANTLEE_OUTPUTSTREAM_H
 
23
 
 
24
#include <QtCore/QTextStream>
 
25
#include <QtCore/QSharedPointer>
 
26
 
 
27
#include "grantlee_core_export.h"
 
28
 
 
29
namespace Grantlee
 
30
{
 
31
 
 
32
class SafeString;
 
33
 
 
34
/// @headerfile outputstream.h grantlee/outputstream.h
 
35
 
 
36
/**
 
37
  @brief The OutputStream class is used to render templates to a QTextStream
 
38
 
 
39
  A OutputStream instance may be passed to the render method of a Template to render
 
40
  the template to a stream.
 
41
 
 
42
  @code
 
43
    QFile outputFile("./output");
 
44
    outputFile.open(QFile::WriteOnly);
 
45
    QTextStream tstream( &outputFile );
 
46
 
 
47
    OutputStream os(&tstream);
 
48
    t->render( &os, &context );
 
49
  @endcode
 
50
 
 
51
  The OutputStream is used to escape the content streamed to it. By default, the escaping is html escaping, converting "&" to "&amp;" for example. If generating non-html output, the escape method may be overriden to perform a different escaping, or non at all.
 
52
 
 
53
  If overriding the escape method, the clone method must also be overriden to return an OutputStream with the same escaping behaviour.
 
54
 
 
55
  @code
 
56
    class NoEscapeStream : public Grantlee::OutputStream
 
57
    {
 
58
    public:
 
59
      // ...
 
60
 
 
61
      QString escape( const QString &input ) const
 
62
      {
 
63
        return input;
 
64
      }
 
65
 
 
66
      QSharedPointer<OutputStream> clone( QTextStream *stream ) const
 
67
      {
 
68
        QSharedPointer<OutputStream> clonedStream = QSharedPointer<OutputStream>( new NoEscapeStream( stream ) );
 
69
        return clonedStream;
 
70
      }
 
71
    };
 
72
  @endcode
 
73
 
 
74
  @author Stephen Kelly <steveire@gmail.com>
 
75
*/
 
76
class GRANTLEE_CORE_EXPORT OutputStream
 
77
{
 
78
public:
 
79
  /**
 
80
    Creates a null OutputStream. Content streamed to this OutputStream is sent to /dev/null
 
81
  */
 
82
  OutputStream();
 
83
 
 
84
  /**
 
85
    Creates an OutputStream which will stream content to @p stream with appropriate escaping.
 
86
  */
 
87
  explicit OutputStream( QTextStream *stream );
 
88
 
 
89
  /**
 
90
    Destructor
 
91
  */
 
92
  virtual ~OutputStream();
 
93
 
 
94
  /**
 
95
    Returns an escaped version of @p input. Does not write anything to the stream.
 
96
  */
 
97
  virtual QString escape( const QString &input ) const;
 
98
 
 
99
  /**
 
100
    Returns an escaped version of @p input. Does not write anything to the stream.
 
101
  */
 
102
  QString escape( const SafeString &input ) const;
 
103
 
 
104
  /**
 
105
    Returns an cloned OutputStream with the same filtering behaviour.
 
106
  */
 
107
  virtual QSharedPointer<OutputStream> clone( QTextStream *stream ) const;
 
108
 
 
109
  /**
 
110
    Returns @p after escaping it, unless @p input is "safe", in which case, @p input is returned unmodified.
 
111
  */
 
112
  QString conditionalEscape( const Grantlee::SafeString &input ) const;
 
113
 
 
114
  /**
 
115
    Writes @p input to the stream after escaping it.
 
116
  */
 
117
  OutputStream& operator<<( const QString &input );
 
118
 
 
119
  /**
 
120
    Writes @p input to the stream after escaping it if necessary.
 
121
  */
 
122
  OutputStream& operator<<( const SafeString &input );
 
123
 
 
124
  /**
 
125
    Reads the content of @p stream and writes it unmodified to the result stream.
 
126
  */
 
127
  OutputStream& operator<<( QTextStream *stream );
 
128
 
 
129
private:
 
130
  QTextStream *m_stream;
 
131
  Q_DISABLE_COPY( OutputStream )
 
132
};
 
133
 
 
134
}
 
135
 
 
136
#endif