1 | /* This file is part of Soprano |
2 | * |
3 | * Copyright (C) 2006 Daniele Galdi <daniele.galdi@gmail.com> |
4 | * Copyright (C) 2007 Sebastian Trueg <trueg@kde.org> |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Library General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2 of the License, 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 Library General Public License |
17 | * along with this library; see the file COPYING.LIB. If not, write to |
18 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | * Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | #ifndef SOPRANO_PARSER_H |
23 | #define SOPRANO_PARSER_H |
24 | |
25 | #include "plugin.h" |
26 | #include "soprano_export.h" |
27 | #include "sopranotypes.h" |
28 | #include "error.h" |
29 | |
30 | #include <QtCore/QObject> |
31 | |
32 | class QTextStream; |
33 | class QUrl; |
34 | |
35 | |
36 | namespace Soprano |
37 | { |
38 | class StatementIterator; |
39 | |
40 | /** |
41 | * \class Parser parser.h Soprano/Parser |
42 | * |
43 | * \brief Soprano::Parser defines the interface for a Soprano RDF parser plugin. |
44 | * |
45 | * Each parser plugin may support multiple RDF serializations (supportedSerializations()). |
46 | * |
47 | * |
48 | * \section Usage |
49 | * |
50 | * Using a Parser is straightforward. One starts by getting a plugin that supports the requested |
51 | * RDF data serialization: |
52 | * |
53 | * \code |
54 | * const Soprano::Parser* p = Soprano::PluginManager::instance()->discoverParserForSerialization( Soprano::SerializationRdfXml ); |
55 | * \endcode |
56 | * |
57 | * Then parsing RDF data is done in a single method call resulting in a StatementIterator over |
58 | * the resulting graph (since parsers may support multiple serializations one always needs to |
59 | * provide the serialization type unless a parser plugin support autodetection). |
60 | * |
61 | * \code |
62 | * Soprano::StatementIterator it = p->parseFile( "myrdffile.rdf", Soprano::SerializationRdfXml ); |
63 | * \endcode |
64 | * |
65 | * \sa \ref soprano_writing_plugins |
66 | * |
67 | * \author Daniele Galdi <daniele.galdi@gmail.com><br>Sebastian Trueg <trueg@kde.org> |
68 | */ |
69 | class SOPRANO_EXPORT Parser : public Plugin, public Error::ErrorCache |
70 | { |
71 | public: |
72 | virtual ~Parser(); |
73 | |
74 | /** |
75 | * The serialiazation types supported by this parser. |
76 | * \return A combination of Soprano::RdfSerialization types. If |
77 | * the list contains Soprano::SerializationUser the parser |
78 | * supports additional RDF serializations not |
79 | * officially supported by %Soprano. |
80 | */ |
81 | virtual RdfSerializations supportedSerializations() const = 0; |
82 | |
83 | /** |
84 | * A parser can support additional RDF serializations that are not defined in Soprano::RdfSerialization. |
85 | * In that case supportedSerializations() has to include Soprano::SerializationUser. |
86 | * |
87 | * The default implementation returns an empty list. |
88 | * |
89 | * \return A list of supported user RDF serializations. |
90 | */ |
91 | virtual QStringList supportedUserSerializations() const; |
92 | |
93 | /** |
94 | * Check if a plugin supports a specific serialization. |
95 | * |
96 | * \param s The requested serialization. |
97 | * \param userSerialization If serialization is set to Soprano::SerializationUser this parameter specifies the |
98 | * requested serialization. It allows the extension of the %Soprano Parser interface with new |
99 | * RDF serializations that are not officially supported by %Soprano. |
100 | * |
101 | * \return \p true if the parser is able to parse RDF data encoded |
102 | * in serialization s, \p false otherwise. |
103 | */ |
104 | bool supportsSerialization( RdfSerialization s, const QString& userSerialization = QString() ) const; |
105 | |
106 | /** |
107 | * Parse an RDF model which has been serialized in a file, |
108 | * using the supplied baseURI to resolve any relative URI references. |
109 | * |
110 | * The default implementation simply calls parseStream() on an opened |
111 | * QFile instance. |
112 | * |
113 | * \param filename The name (path) of the file to parse |
114 | * \param baseUri The base URI to be used for relative references. |
115 | * \param serialization The serialization used in the file. |
116 | * \param userSerialization If serialization is set to Soprano::SerializationUser this parameter specifies the |
117 | * serialization to use. It allows the extension of the %Soprano Parser interface with new |
118 | * RDF serializations that are not officially supported by %Soprano. |
119 | * |
120 | * \return An iterator that iterates over the result statements. |
121 | */ |
122 | virtual StatementIterator parseFile( const QString& filename, const QUrl& baseUri, RdfSerialization serialization, const QString& userSerialization = QString() ) const; |
123 | |
124 | /** |
125 | * Parse an RDF model which has been serialized into a string, |
126 | * using the supplied baseURI to resolve any relative URI references. |
127 | * |
128 | * The default implementation simply calls parseStream(). |
129 | * |
130 | * \param data The serialized RDF string. |
131 | * \param baseUri The base URI to be used for relative references. |
132 | * \param serialization The serialization used for the string data. |
133 | * \param userSerialization If serialization is set to Soprano::SerializationUser this parameter specifies the |
134 | * serialization to use. It allows the extension of the %Soprano Parser interface with new |
135 | * RDF serializations that are not officially supported by %Soprano. |
136 | * |
137 | * \return An iterator that iterates over the result statements. |
138 | */ |
139 | virtual StatementIterator parseString( const QString& data, const QUrl& baseUri, RdfSerialization serialization, const QString& userSerialization = QString() ) const; |
140 | |
141 | /** |
142 | * Read a serialized RDF model from a test stream, |
143 | * using the supplied baseURI to resolve any relative URI references. |
144 | * |
145 | * \param stream The text stream to read the serialized RDF data from. |
146 | * \param baseUri The base URI to be used for relative references. |
147 | * \param serialization The serialization used for the string data from the stream. |
148 | * \param userSerialization If serialization is set to Soprano::SerializationUser this parameter specifies the |
149 | * serialization to use. It allows the extension of the %Soprano Parser interface with new |
150 | * RDF serializations that are not officially supported by %Soprano. |
151 | * |
152 | * \return An iterator that iterates over the result statements. |
153 | */ |
154 | virtual StatementIterator parseStream( QTextStream& stream, const QUrl& baseUri, RdfSerialization serialization, const QString& userSerialization = QString() ) const = 0; |
155 | |
156 | protected: |
157 | Parser( const QString& name ); |
158 | |
159 | private: |
160 | class Private; |
161 | Private* const d; |
162 | }; |
163 | } |
164 | |
165 | Q_DECLARE_INTERFACE(Soprano::Parser, "org.soprano.plugins.Parser/1.0" ) |
166 | |
167 | #endif // SOPRANO_PARSER_H |
168 | |
169 | |