workspace/libs/nepomukquery/term.h

   1 /*
   2    This file is part of the Nepomuk KDE project.
   3    Copyright (C) 2007 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 _NEPOMUK_SEARCH_TERM_H_
  21 #define _NEPOMUK_SEARCH_TERM_H_
  22
  23 #include <QtCore/QList>
  24 #include <QtCore/QUrl>
  25 #include <QtCore/QSharedDataPointer>
  26
  27 #include <Soprano/LiteralValue>
  28
  29 #include "nepomukquery_export.h"
  30
  31
  32 namespace Nepomuk {
  33     namespace Search {
  34         /**
  35          * \class Term term.h nepomuk/term.h
  36          *
  37          * \brief A Query constist of Terms.
  38          *
  39          * Queries are build from Term instances. A Term can have one of multiple
  40          * types and subterms. See Term::Type for details on the different Term types.
  41          *
  42          * \author Sebastian Trueg <trueg@kde.org>
  43          */
  44         class NEPOMUKQUERY_EXPORT Term
  45         {
  46         public:
  47             /**
  48              * Each search term has a type.
  49              */
  50             enum Type {
  51                 InvalidTerm,    /**< An invalid term does not do anything */
  52                 /**
  53                  * A literal term is the simplest form of Term. It matches all resource
  54                  * that contain the value.
  55                  *
  56                  * It is also used to specify literal values in comparison Terms such
  57                  * as ContainsTerm or EqualityTerm.
  58                  */
  59                 LiteralTerm,
  60
  61                 /**
  62                  * A resource term matches one resource by URI.
  63                  *
  64                  * It is also used to specify a resource in EqualityTerm Terms.
  65                  */
  66                 ResourceTerm,
  67
  68                 /**
  69                  * Match all resources that match all sub terms.
  70                  */
  71                 AndTerm,
  72
  73                 /**
  74                  * Match all resources that match one of the sub terms.
  75                  */
  76                 OrTerm,
  77
  78                 /**
  79                  * A comparison. The comparison operator needs to be specified in addition.
  80                  * For specifying the %property the same applies as for ContainsTerm.
  81                  *
  82                  * A single subterm specifies the resource or value to match (resource terms
  83                  * can only be matched via Equal or Contains.
  84                  */
  85                 ComparisonTerm
  86             };
  87
  88             enum Comparator {
  89                 Contains,
  90                 Equal,
  91                 Greater,
  92                 Smaller,
  93                 GreaterOrEqual,
  94                 SmallerOrEqual
  95             };
  96
  97             /**
  98              * Constructs an invalid term.
  99              */
 100             Term();
 101
 102             /**
 103              * Copy constructor.
 104              */
 105             Term( const Term& other );
 106
 107             /**
 108              * Construct a literal term.
 109              */
 110             Term( const Soprano::LiteralValue& value );
 111
 112             /**
 113              * Construct a resource term.
 114              */
 115             Term( const QUrl& resource );
 116
 117             /**
 118              * Construct a Contains ComparisonTerm term.
 119              * \param field A string that will be matched against a field label
 120              * \param value A value that will be matched against the field value. Unsupported
 121              *        types are converted to string.
 122              * \param comparator The Comparator to use
 123              */
 124             Term( const QString& field, const Soprano::LiteralValue& value, Comparator c = Contains );
 125
 126             /**
 127              * Construct a Contains ComparisonTerm term.
 128              * \param field The exact field to match
 129              * \param value A value that will be matched against the field value. Unsupported
 130              *        types are converted to string.
 131              * \param comparator The Comparator to use
 132              */
 133             Term( const QUrl& field, const Soprano::LiteralValue& value, Comparator c = Contains );
 134
 135             /**
 136              * Construct an EqualityTerm term.
 137              * \param field The exact field to match
 138              * \param value The resource that should be matched.
 139              */
 140             Term( const QUrl& field, const QUrl& resource );
 141
 142             /**
 143              * Destructor
 144              */
 145             ~Term();
 146
 147             /**
 148              * Assign another term to this one.
 149              */
 150             Term& operator=( const Term& other );
 151
 152             /**
 153              * Make the term a literal term.
 154              */
 155             Term& operator=( const Soprano::LiteralValue& other );
 156
 157             /**
 158              * \return \p true if the Term is valid.
 159              */
 160             bool isValid() const;
 161
 162             /**
 163              * \return the Term type.
 164              *
 165              * \sa setType
 166              */
 167             Type type() const;
 168
 169             /**
 170              * The literal value of a LiteralTerm.
 171              *
 172              * \sa setValue
 173              */
 174             Soprano::LiteralValue value() const;
 175
 176             /**
 177              * The resource of a ResourceTerm
 178              *
 179              * \sa setResource
 180              */
 181             QUrl resource() const;
 182
 183             /**
 184              * The Comparator used by ComparisonTerm Terms.
 185              *
 186              * \sa setComparator
 187              */
 188             Comparator comparator() const;
 189
 190             /**
 191              * A property name used for ComparisonTerm Terms. Will be matched against
 192              * the rdfs:label to find the corresponding property.
 193              *
 194              * \sa setField, property, setProperty
 195              */
 196             QString field() const;
 197
 198             /**
 199              * A property used for ComparisonTerm Terms.
 200              *
 201              * \sa setProperty, field, setField
 202              */
 203             QUrl property() const;
 204
 205             /**
 206              * The sub terms  used by AndTerm, OrTerm, and ComparisonTerm.
 207              *
 208              * \sa setSubTerms, addSubTerm
 209              */
 210             QList<Term> subTerms() const;
 211
 212             /**
 213              * Set the type of the Term
 214              */
 215             void setType( Type );
 216
 217             /**
 218              * Set the value of a LiteralTerm
 219              */
 220             void setValue( const Soprano::LiteralValue& );
 221
 222             /**
 223              * Set the resource of a ResourceTerm
 224              */
 225             void setResource( const QUrl& );
 226
 227             /**
 228              * Defaults to Equal
 229              */
 230             void setComparator( Comparator );
 231
 232             /**
 233              * Set the property label in case the exact
 234              * property is not known. Will be mached against
 235              * the property's rdfs:label.
 236              *
 237              * \sa field, setProperty, property
 238              */
 239             void setField( const QString& );
 240
 241             /**
 242              * Set the property for ComparisonTerm
 243              * Terms.
 244              *
 245              * If the exact property is not known use setField.
 246              *
 247              * \sa property
 248              */
 249             void setProperty( const QUrl& );
 250
 251             /**
 252              * Set the subterms used by AndTerm, OrTerm, and ComparisonTerm.
 253              *
 254              * \sa addSubTerm
 255              */
 256             void setSubTerms( const QList<Term>& );
 257
 258             /**
 259              * Add a subterm used by AndTerm, OrTerm, and ComparisonTerm.
 260              *
 261              * \sa setSubTerm
 262              */
 263             void addSubTerm( const Term& );
 264
 265             /**
 266              * Comparison operator.
 267              */
 268             bool operator==( const Term& ) const;
 269
 270         private:
 271             class Private;
 272             QSharedDataPointer<Private> d;
 273         };
 274
 275         NEPOMUKQUERY_EXPORT uint qHash( const Nepomuk::Search::Term& );
 276     }
 277 }
 278
 279 NEPOMUKQUERY_EXPORT QDebug operator<<( QDebug, const Nepomuk::Search::Term& );
 280
 281 #endif