1/*
2 * This file is part of Soprano Project.
3 *
4 * Copyright (C) 2006-2007 Daniele Galdi <daniele.galdi@gmail.com>
5 * Copyright (C) 2007-2009 Sebastian Trueg <trueg@kde.org>
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public License
18 * along with this library; see the file COPYING.LIB. If not, write to
19 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 */
22
23#ifndef SOPRANO_NODE_H
24#define SOPRANO_NODE_H
25
26#include <QtCore/QUrl>
27#include <QtCore/QSharedDataPointer>
28#include <QtCore/QTextStream>
29
30#include "soprano_export.h"
31#include "literalvalue.h"
32#include "languagetag.h"
33#include "sopranomacros.h"
34
35namespace Soprano
36{
37 /**
38 * \class Node node.h Soprano/Node
39 *
40 * \brief A Node represents one RDF resource.
41 *
42 * Nodes are the cornerstone of RDF data in %Soprano. Four Nodes form one Statement and a Model
43 * is essentially a set of Statements.
44 *
45 * A Node can have one of four types: EmptyNode, ResourceNode, LiteralNode, and BlankNode.
46 * Resource nodes are identified through their URI (uri()), literal nodes have a LiteralValue (literal()),
47 * and blank nodes have a string identifier.
48 *
49 * Empty nodes can be used as wildcards in methods such as Model::listStatements.
50 *
51 * \author Daniele Galdi <daniele.galdi@gmail.com><br>Sebastian Trueg <trueg@kde.org>
52 */
53 class SOPRANO_EXPORT Node
54 {
55 public:
56 enum Type {
57 EmptyNode = 0, /**< An empty node, can be used as a wildcard in commands like Model::listStatements. */
58 ResourceNode = 1, /**< A resource node has a URI which can be accessed via uri() */
59 LiteralNode = 2, /**< A literal node has a literal value and an optional language. */
60 BlankNode = 3 /**< A blank node has an identifier string */
61 };
62
63 /**
64 * \name Constructors
65 */
66 //@{
67 /**
68 * Default costructor.
69 * Creates an empty node.
70 *
71 * \sa createEmptyNode()
72 */
73 Node();
74
75 // This constructor is non-explicit for a reason: it makes creating
76 // Statements much much easier and more readable
77 /**
78 * Creates a resource node.
79 *
80 * \param uri The URI of the node. If empty the type will be ignored
81 * and an empty node will be created.
82 *
83 * \sa createResourceNode()
84 */
85 Node( const QUrl &uri );
86
87 /**
88 * Creates a blank node.
89 *
90 * \param id An identifier for the blank node.
91 *
92 * \sa createBlankNode()
93 */
94 explicit Node( const QString& id );
95
96 /**
97 * Creates a literal node.
98 *
99 * \param value The value of a node. If empty the node will become
100 * an empty node.
101 *
102 * \sa createLiteralNode()
103 *
104 * \since 2.3
105 */
106 Node( const LiteralValue& value );
107
108 /**
109 * Creates a literal node.
110 *
111 * \param value The value of a node. If empty the node will become
112 * an empty node.
113 * \param language The language of the literal value.
114 *
115 * \sa createLiteralNode()
116 *
117 * \deprecated Use Soprano::Node::Node( const LiteralValue& ) and
118 * Soprano::LiteralValue::createPlainLiteral( const QString&, const LanguageTag& )
119 */
120 SOPRANO_CONSTRUCTOR_DEPRECATED Node( const LiteralValue& value,
121 const QString& language );
122
123 /**
124 * Copy constructor.
125 */
126 Node( const Node &other );
127
128 ~Node();
129 //@}
130
131 /**
132 * \name Operators
133 */
134 //@{
135 Node& operator=( const Node& other );
136
137 /**
138 * Assigns \p resource to this node and makes it a ResourceNode.
139 */
140 Node& operator=( const QUrl& resource );
141
142 /**
143 * Assigns \p literal to this node and makes it a LiteralNode.
144 */
145 Node& operator=( const LiteralValue& literal );
146
147 /**
148 * Comparison operator.
149 * \return \p true if this node and \p other are equal.
150 */
151 bool operator==( const Node& other ) const;
152
153 /**
154 * Comparison operator.
155 * \return \p true if this node and \p other differ.
156 */
157 bool operator!=( const Node& other ) const;
158
159 /**
160 * Comparison operator.
161 * \return \p true if this node is a ResourceNode and
162 * has URI \p uri.
163 */
164 bool operator==( const QUrl& uri ) const;
165
166 /**
167 * Comparison operator.
168 * \return \p true if this node is a LiteralNode and
169 * has literal value \p other.
170 */
171 bool operator==( const LiteralValue& other ) const;
172
173 /**
174 * Match this node against template node \a other. The only difference
175 * to operator== is that empty nodes are matched as wildcards,
176 * i.e. they match any other node.
177 *
178 * Be aware that the following is NOT always true since only \a other
179 * is treated a a wildcard:
180 *
181 * \code
182 * // NOT always true:
183 * a.matches(b) == b.matches(a)
184 * \endcode
185 *
186 * \return \p true if this node matches other, \p false if not.
187 *
188 * \sa Statement::matches
189 */
190 bool matches( const Node& other ) const;
191 //@}
192
193 /**
194 * \name Type information
195 */
196 //@{
197 /**
198 * \return The node type.
199 */
200 Type type() const;
201
202 /**
203 * \return \p true if the node is empty.
204 */
205 bool isEmpty() const;
206
207 /**
208 * \return \p true if the node is a ResourceNode, LiteralNode or BlankNode.
209 */
210 bool isValid() const ;
211
212 /**
213 * \return \p true if the node is a LiteralNode.
214 */
215 bool isLiteral() const;
216
217 /**
218 * \return \p true if the node is a ResourceNode.
219 */
220 bool isResource() const;
221
222 /**
223 * \return \p true if the node is a BlankNode (anonymous).
224 */
225 bool isBlank() const;
226 //@}
227
228 /**
229 * \name Resource nodes
230 */
231 //@{
232 /**
233 * \return The URI if the node is a ResourceNode.
234 * An null QUrl otherwise.
235 */
236 QUrl uri() const;
237 //@}
238
239 /**
240 * \name Blank nodes
241 */
242 //@{
243 /**
244 * Retrieve a blank node's identifier.
245 * \return The node's identifier if it is a BlankNode, a null
246 * string otherwise.
247 */
248 QString identifier() const;
249 //@}
250
251 /**
252 * \name Literal nodes
253 */
254 //@{
255 /**
256 * \return The literal value if the node is a LiteralNode.
257 * An null QString otherwise.
258 */
259 LiteralValue literal() const;
260
261 /**
262 * \return The datatype URI of a literal node, i.e. the XML schema type
263 * or an empty value if the node is not a LiteralNode.
264 * \sa LiteralValue::dataTypeUri
265 */
266 QUrl dataType() const;
267
268 /**
269 * Each literal value can have an associated language, thus each property
270 * can be stored for different languages. An empty language refers to the
271 * default language.
272 *
273 * \return A string representing the language of the literal value
274 * or an empty string if the node is not a literal.
275 *
276 * \deprecated Language exists on the Soprano::LiteralValue. Use Soprano::Node::literal() and
277 * Soprano::LiteralValue::language().
278 */
279 QString language() const;
280 //@}
281
282 /**
283 * \name Conversion
284 */
285 //@{
286 /**
287 * Converts the Node to a string.
288 *
289 * \return A String representation of the Node, suitable for storage,
290 * not really suitable for user readable strings.
291 *
292 * \sa LiteralValue::toString(), QUrl::toString(), toN3()
293 */
294 QString toString() const;
295
296 /**
297 * Convert a Node into N3 notation to be used in SPARQL graph patterns.
298 *
299 * Examples:
300 * \code
301 * <http://soprano.sourceforce.net/>
302 * "Hello World"^^<http://www.w3.org/2001/XMLSchema#string>
303 * "09-08-1977T17:42.234Z"^^<http://www.w3.org/2001/XMLSchema#dateTime>
304 * _:blankNode
305 * \endcode
306 *
307 * \return A string representing the node in N3 encoding or an empty
308 * string for invalid nodes.
309 *
310 * \sa resourceToN3(), literalToN3(), blankToN3(), fromN3(), toString()
311 *
312 * \since 2.2
313 */
314 QString toN3() const;
315 //@}
316
317 /**
318 * Convenience method to create an empty node.
319 * Using this method instead of the default constructor
320 * may result in better readable code.
321 *
322 * \return An empty Node.
323 */
324 static Node createEmptyNode();
325
326 /**
327 * Convenience method to create a resource node.
328 * Using this method instead of the constructor
329 * may result in better readable code.
330 *
331 * \param uri The URI of the node. If empty the type will be ignored
332 * and an empty node will be created.
333 *
334 * \return A resource Node or an empty Node if the specified URI is empty.
335 */
336 static Node createResourceNode( const QUrl& uri );
337
338 /**
339 * Convenience method to create a blank node.
340 * Using this method instead of the constructor
341 * may result in better readable code.
342 *
343 * If you need to create a new blank node which is not
344 * used in the model yet and, thus, has a unique identifier
345 * see Model::createBlankNode().
346 *
347 * \param id An identifier for the blank node.
348 *
349 * \return A blank node or an empty Node if the specified
350 * identifier was empty.
351 */
352 static Node createBlankNode( const QString& id );
353
354 /**
355 * Convenience method to create a literal node.
356 * Using this method instead of the constructor
357 * may result in better readable code.
358 *
359 * \param value The value of a node. If empty the node will become
360 * an empty node.
361 *
362 * \return A literal node or an empty node if the specified value
363 * was empty.
364 *
365 * \since 2.3
366 */
367 static Node createLiteralNode( const LiteralValue& value );
368
369 /**
370 * Convenience method to create a literal node.
371 * Using this method instead of the constructor
372 * may result in better readable code.
373 *
374 * \param value The value of a node. If empty the node will become
375 * an empty node.
376 * \param language The language of the literal value.
377 *
378 * \return A literal node or an empty node if the specified value
379 * was empty.
380 *
381 * \deprecated Use Soprano::Node::createLiteralNode( const LiteralValue& ) and
382 * Soprano::LiteralValue::createPlainLiteral( const QString&, const LanguageTag& )
383 */
384 static SOPRANO_DEPRECATED Node createLiteralNode( const LiteralValue& value, const QString& language );
385
386 /**
387 * Format a resource URI as N3 string to be used in SPARQL queries.
388 *
389 * \return A string representing the resource in N3 encoding or an empty
390 * string for invalid URIs.
391 *
392 * Example:
393 * \code
394 * <http://soprano.sourceforce.net/>
395 * \endcode
396 *
397 * \sa toN3(), fromN3()
398 *
399 * \since 2.3
400 */
401 static QString resourceToN3( const QUrl& resource );
402
403 /**
404 * Format a blank node identifier as N3 string to be used in SPARQL queries.
405 *
406 * \return A string representing the blank identifier in N3 encoding or an empty
407 * string for invalid/empty ids.
408 *
409 * Example:
410 * \code
411 * _:blankNode
412 * \endcode
413 *
414 * \sa toN3(), fromN3()
415 *
416 * \since 2.3
417 */
418 static QString blankToN3( const QString& blank );
419
420 /**
421 * Format a literal value as N3 string to be used in SPARQL queries.
422 *
423 * \return A string representing the literal in N3 encoding or an empty
424 * string for invalid literals.
425 *
426 * Examples:
427 * \code
428 * "Hello World"^^<http://www.w3.org/2001/XMLSchema#string>
429 * "09-08-1977T17:42.234Z"^^<http://www.w3.org/2001/XMLSchema#dateTime>
430 * \endcode
431 *
432 * \sa toN3(), fromN3()
433 *
434 * \since 2.3
435 */
436 static QString literalToN3( const LiteralValue& literal );
437
438 /**
439 * Parsing flags to infuence the behaviour of the parser in
440 * fromN3() and fromN3Stream().
441 *
442 * \since 2.5
443 */
444 enum N3ParserFlag {
445 /**
446 * No parsing flags, default behaviour.
447 */
448 NoFlags = 0x0,
449
450 /**
451 * Use strict literal parsing, i.e. do not treat
452 * \p true and \p false as boolean literals or
453 * do not handle numbers as literals if they do
454 * not contain a literal type.
455 */
456 StrictLiteralTypes = 0x1,
457
458 /**
459 * Use strict URI parsing.
460 *
461 * \sa QUrl::StrictMode
462 */
463 StrictUris = 0x2,
464
465 /**
466 * Do not make use of m_prefixes
467 */
468 IgnorePrefixes = 0x4
469 };
470 Q_DECLARE_FLAGS( N3ParserFlags, N3ParserFlag )
471
472 /**
473 * Convert a node from its N3 representation.
474 *
475 * \param n3 The N3 representation of the node.
476 *
477 * \return A %Node representing the parsed version of \p n3 or an invalid %Node in case
478 * parsing failed.
479 *
480 * \sa resourceToN3(), literalToN3(), blankToN3(), toN3()
481 *
482 * \since 2.5
483 */
484 static Node fromN3( const QString& n3, N3ParserFlags flags = NoFlags );
485
486 /**
487 * Read a node from its N3 representation on a stream.
488 *
489 * \param stream The stream from which the N3 representation of the node will be read.
490 *
491 * \return A %Node representing the parsed version of \p n3 or an invalid %Node in case
492 * parsing failed.
493 *
494 * \sa resourceToN3(), literalToN3(), blankToN3(), toN3()
495 *
496 * \since 2.5
497 */
498 static Node fromN3Stream( QTextStream& stream, N3ParserFlags flags = NoFlags );
499
500 private:
501 class NodeData;
502 class ResourceNodeData;
503 class BNodeData;
504 class LiteralNodeData;
505 QSharedDataPointer<NodeData> d;
506 };
507
508 /**
509 * \relates Soprano::Node
510 */
511 SOPRANO_EXPORT uint qHash( const Node& node );
512}
513
514/**
515 * \relates Soprano::Node
516 */
517SOPRANO_EXPORT QDebug operator<<( QDebug s, const Soprano::Node& );
518
519/**
520 * Default Soprano::Node stream operator. The operator serializes the Node
521 * based on the N-Triples standard, except that it uses Unicode strings.
522 *
523 * \sa Soprano::Node::toN3()
524 *
525 * \relates Soprano::Node
526 */
527SOPRANO_EXPORT QTextStream& operator<<( QTextStream& s, const Soprano::Node& );
528
529/**
530 * Read a node from an N3 encoded string.
531 *
532 * \sa Soprano::Node::fromN3()
533 *
534 * \since 2.5
535 */
536SOPRANO_EXPORT QTextStream& operator>>( QTextStream& s, Soprano::Node& );
537
538#if QT_VERSION < 0x040700
539SOPRANO_EXPORT uint qHash( const QUrl& url );
540#endif
541
542Q_DECLARE_OPERATORS_FOR_FLAGS( Soprano::Node::N3ParserFlags )
543
544#endif // SOPRANO_NODE_H
545