← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/soprano/gutsy

« back to all changes in this revision

Viewing changes to soprano/parser.h

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Riddell
  • Date: 2007-10-12 14:43:48 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20071012144348-yajzi51v4k23ahxf
Tags: 1.95.0~beta2-1ubuntu1
* Sync with Debian
* Add versioned build-dep on raptor

Show diffs side-by-side

added added

removed removed

Lines of Context:
soprano/parser.h
22
22
#ifndef SOPRANO_PARSER_H
23
23
#define SOPRANO_PARSER_H
24
24
 
25
 
#include <soprano/soprano_export.h>
 
25
#include "plugin.h"
 
26
#include "soprano_export.h"
 
27
#include "sopranotypes.h"
 
28
#include "error.h"
 
29
 
 
30
#include <QtCore/QObject>
26
31
 
27
32
class QTextStream;
28
 
class QString;
29
33
class QUrl;
30
34
 
31
35
 
32
36
namespace Soprano
33
37
{
34
 
    class Model;
 
38
    class StatementIterator;
35
39
 
36
40
    /**
37
 
     * Different types of RDF serialization.
 
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. Once starts by getting a plugin that supports the requested
 
51
     * RDF data serilization:
 
52
     *
 
53
     * \code
 
54
     * Parser* p = PluginManager::instance()->discoverParserForSerialization( 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
     * StatementIterator it = p->parseFile( "myrdffile.rdf", 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>
38
68
     */
39
 
    // FIXME: what about the used charsets? Should we and if so, how should we include them?
40
 
    enum RdfSerialization {
41
 
        UNKNOWN = 0x0,   /**< The serialization is unknown. */
42
 
        RDF_XML = 0x1,   /**< Standard RDF/XML serialization */
43
 
        N3 = 0x2,        /**< Notation 3: http://www.w3.org/DesignIssues/Notation3 */
44
 
        N_TRIPLES = 0x4, /**< N-Triples as defined by W3: http://www.w3.org/TR/rdf-testcases/#ntriples */
45
 
        TURTLE = 0x8,    /**< Turtle - Terse RDF Triple Language: http://www.dajobe.org/2004/01/turtle/ */
46
 
        TRIG = 0x10      /**< TriG - Turtle + Named Graphs: http://sites.wiwiss.fu-berlin.de/suhl/bizer/TriG/ */
 
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 serialiazations 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;
47
162
    };
48
 
    Q_DECLARE_FLAGS(RdfSerializations, RdfSerialization)
49
 
 
50
 
    /**
51
 
     * \return The mimetype of serialization or an empty string is serialization is UNKNOWN
52
 
     */
53
 
    SOPRANO_EXPORT QString serializationMimeType( RdfSerialization serialization );
54
 
 
55
 
    /**
56
 
     * Parse a mimetype and match it to the RdfSerialization enum.
57
 
     * \return the RdfSerialization type that matches mimetype or UNKNOWN if the mimetype 
58
 
     * could not be parsed.
59
 
     */
60
 
    SOPRANO_EXPORT RdfSerialization mimeTypeToSerialization( const QString& mimetype );
61
 
 
62
 
    class SOPRANO_EXPORT Parser
63
 
        {
64
 
        public:
65
 
            virtual ~Parser();
66
 
 
67
 
            /**
68
 
             * The serialiazation types supported by this parser.
69
 
             * \return A combination of RdfSerialization types.
70
 
             */
71
 
            virtual RdfSerializations supportedSerializations() const = 0;
72
 
 
73
 
            /**
74
 
             * \deprecated
75
 
             * Calls parseFile with RDF_XML serialization
76
 
             */
77
 
            Model* parse( const QUrl& url ) const;
78
 
 
79
 
            /**
80
 
             * Parse an RDF model which has been serialized in a file,
81
 
             * using the supplied baseURI to resolve any relative URI references.
82
 
             *
83
 
             * The default implementation simply calls parseStream on an opened
84
 
             * QFile instance.
85
 
             *
86
 
             * \param filename The name (path) of the file to parse
87
 
             * \param baseUri The base URI to be used for relative references.
88
 
             * \param serialization The serialization used in the file.
89
 
             * If UNKNOWN the parser is supposed to auto detect the serialization type. 
90
 
             * Might not be reliable.
91
 
             */
92
 
            virtual Model* parseFile( const QString& filename, const QUrl& baseUri, RdfSerialization serialization = UNKNOWN ) const;
93
 
 
94
 
            /**
95
 
             * Parse an RDF model which has been serialized into a string,
96
 
             * using the supplied baseURI to resolve any relative URI references.
97
 
             *
98
 
             * The default implementation simply calls parseStream.
99
 
             *
100
 
             * \param data The serialized RDF string.
101
 
             * \param baseUri The base URI to be used for relative references.
102
 
             * \param serialization The serialization used for the string data.
103
 
             * If UNKNOWN the parser is supposed to auto detect the serialization type. 
104
 
             * Might not be reliable.
105
 
             */
106
 
            virtual Model* parseString( const QString& data, const QUrl& baseUri, RdfSerialization serialization = UNKNOWN ) const;
107
 
 
108
 
            /**
109
 
             * Read a serialized RDF model from a test stream,
110
 
             * using the supplied baseURI to resolve any relative URI references.
111
 
             *
112
 
             * \param stream The text stream to read the serialized RDF data from.
113
 
             * \param baseUri The base URI to be used for relative references.
114
 
             * \param serialization The serialization used for the string data from the stream.
115
 
             * If UNKNOWN the parser is supposed to auto detect the serialization type. 
116
 
             * Might not be reliable.
117
 
             */ 
118
 
            virtual Model* parseStream( QTextStream* stream, const QUrl& baseUri, RdfSerialization serialization = UNKNOWN ) const = 0;
119
 
 
120
 
        protected:
121
 
            Parser();
122
 
        };
123
163
}
124
164
 
125
 
Q_DECLARE_OPERATORS_FOR_FLAGS(Soprano::RdfSerializations)
 
165
Q_DECLARE_INTERFACE(Soprano::Parser, "org.soprano.plugins.Parser/1.0")
126
166
 
127
167
#endif // SOPRANO_PARSER_H
128
168