Warning: That file was not part of the compilation database. It may have many parsing errors.

1/*
2 This file is part of the Nepomuk KDE project.
3 Copyright (C) 2007-2010 Sebastian Trueg <trueg@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License version 2 as published by the Free Software Foundation.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18 */
19
20#ifndef _NEPOMUK2_SEARCH_QUERY_PARSER_H_
21#define _NEPOMUK2_SEARCH_QUERY_PARSER_H_
22
23#include "query.h"
24
25#include <QtCore/QString>
26
27#include "nepomuk_export.h"
28
29
30namespace Nepomuk2 {
31 namespace Query {
32 /**
33 * \class QueryParser queryparser.h Nepomuk2/Query/QueryParser
34 *
35 * \brief Parser for desktop user queries.
36 *
37 * \warning This is NOT a SPARQL parser.
38 *
39 * The QueryParser can be used to parse user queries, ie. queries that the user
40 * would enter in any search interface, and convert them into Query instances.
41 *
42 * The syntax is fairly simple: plain strings match to LiteralTerm terms,
43 * URIs need to be N3-encoded, when using white space parenthesis need to
44 * be put around properties and values, terms can be excluded via \p '-'.
45 *
46 * \section queryparser_examples Examples
47 *
48 * %Query everything that contains the term "nepomuk":
49 * \code
50 * nepomuk
51 * \endcode
52 *
53 * %Query everything that contains both the terms "Hello" and "World":
54 * \code
55 * Hello World
56 * \endcode
57 *
58 * %Query everything that contains the term "Hello World":
59 * \code
60 * "Hello World"
61 * \endcode
62 *
63 * %Query everything that has a tag whose label matches "nepomuk" (actually
64 * this is where Query::resolveProperties would match "hastag" to nao:hasTag):
65 * \code
66 * hastag:nepomuk
67 * \endcode
68 *
69 * %Query everything that has a tag labeled "nepomuk" or a tag labeled "scribo:
70 * \code
71 * hastag:nepomuk OR hastag:scribo
72 * \endcode
73 *
74 * %Query everything that has a tag labeled "nepomuk" but not a tag labeled "scribo":
75 * \code
76 * +hastag:nepomuk AND -hastag:scribo
77 * \endcode
78 *
79 * The parser can handle one special case of nesting (TODO: implement a "real" parser)
80 * which matches all resources that are related to a resource which in turn has a certain
81 * property:
82 * \code
83 * related:(hastag:nepomuk)
84 * \endcode
85 *
86 * \author Sebastian Trueg <trueg@kde.org>
87 *
88 * \since 4.4
89 */
90 class NEPOMUK_EXPORT QueryParser
91 {
92 public:
93 /**
94 * Create a new query parser.
95 */
96 QueryParser();
97
98 /**
99 * Destructor
100 */
101 ~QueryParser();
102
103 /**
104 * Flags to change the behaviour of the parser.
105 *
106 * \since 4.5
107 */
108 enum ParserFlag {
109 /**
110 * No flags. Default for parse()
111 */
112 NoParserFlags = 0x0,
113
114 /**
115 * Make each full text term use a '*' wildcard
116 * to match longer strings ('foobar' is matched
117 * by 'foob*').
118 *
119 * Be aware that the query engine needs at least
120 * 4 chars to do globbing though.
121 *
122 * This is disabled by default.
123 */
124 QueryTermGlobbing = 0x1,
125
126 /**
127 * Try to detect filename pattern like *.mp3
128 * or hello*.txt and create appropriate ComparisonTerm
129 * instances using ComparisonTerm::Regexp instead of
130 * ComparisonTerm::Contains.
131 *
132 * \since 4.6
133 */
134 DetectFilenamePattern = 0x2
135 };
136 Q_DECLARE_FLAGS( ParserFlags, ParserFlag )
137
138 /**
139 * Parse a user query.
140 *
141 * \return The parsed query or an invalid Query object
142 * in case the parsing failed.
143 */
144 Query parse( const QString& query ) const;
145
146 /**
147 * Parse a user query.
148 *
149 * \param query The query string to parse
150 * \param flags a set of flags influencing the parsing process.
151 *
152 * \return The parsed query or an invalid Query object
153 * in case the parsing failed.
154 *
155 * \since 4.5
156 */
157 Query parse( const QString& query, ParserFlags flags ) const;
158
159 /**
160 * Try to match a field name as used in a query string to actual
161 * properties.
162 *
163 * The matching is cached inside the Query instance for fast
164 * subsequent lookups.
165 *
166 * Example:
167 * \code
168 * hastag:nepomuk
169 * \endcode
170 *
171 * \return A list of properties that match \p fieldName or an empty
172 * list in case nothing was matched.
173 *
174 * This method is used by parse() to match properties used in user queries.
175 */
176 QList<Types::Property> matchProperty( const QString& fieldName ) const;
177
178 /**
179 * Convenience method to quickly parse a query without creating an object.
180 *
181 * \return The parsed query or an invalid Query object
182 * in case the parsing failed.
183 */
184 static Query parseQuery( const QString& query );
185
186 /**
187 * \overload
188 *
189 * \param query The query string to parse
190 * \param flags a set of flags influencing the parsing process.
191 *
192 * \since 4.6
193 */
194 static Query parseQuery( const QString& query, ParserFlags flags );
195
196 private:
197 class Private;
198 Private* const d;
199 };
200 }
201}
202
203Q_DECLARE_OPERATORS_FOR_FLAGS( Nepomuk2::Query::QueryParser::ParserFlags )
204
205#endif
206

Warning: That file was not part of the compilation database. It may have many parsing errors.