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
32class QTextStream;
33class QUrl;
34
35
36namespace 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
165Q_DECLARE_INTERFACE(Soprano::Parser, "org.soprano.plugins.Parser/1.0")
166
167#endif // SOPRANO_PARSER_H
168
169