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 | |
35 | namespace 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 | */ |
517 | SOPRANO_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 | */ |
527 | SOPRANO_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 | */ |
536 | SOPRANO_EXPORT QTextStream& operator>>( QTextStream& s, Soprano::Node& ); |
537 | |
538 | #if QT_VERSION < 0x040700 |
539 | SOPRANO_EXPORT uint qHash( const QUrl& url ); |
540 | #endif |
541 | |
542 | Q_DECLARE_OPERATORS_FOR_FLAGS( Soprano::Node::N3ParserFlags ) |
543 | |
544 | #endif // SOPRANO_NODE_H |
545 | |