vcs/vcsrevision.h

   1 /* This file is part of KDevelop
   2  *
   3  * Copyright 2007 Andreas Pakulat <apaku@gmx.de>
   4  * Copyright 2007 Matthew Woehlke <mw_triad@users.sourceforge.net>
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License
   8  * as published by the Free Software Foundation; either version 2
   9  * of the License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19  * 02110-1301, USA.
  20  */
  21
  22 #ifndef VCSREVISION_H
  23 #define VCSREVISION_H
  24
  25 #include "vcsexport.h"
  26 #include <QtCore/QVariant>
  27 class QStringList;
  28 class QString;
  29
  30 namespace KDevelop
  31 {
  32
  33 /**
  34  * Encapsulates a vcs revision number, date or range of revisions
  35  *
  36  * The type of the QVariant value depends on the type of the revision,
  37  * the following table lists the standard types and the according datatype
  38  * in the qvariant:
  39  *
  40  * <table>
  41  * <tr><th>Revision type</th><th>QVariant type</th></tr>
  42  * <tr><td>GlobalNumber</td><td>qlonglong</td></tr>
  43  * <tr><td>FileNumber</td><td>qlonglong</td></tr>
  44  * <tr><td>Date</td><td>QDateTime</td></tr>
  45  * <tr><td>Special</td><td>KDevelop::VcsRevision::RevisionSpecialType or int, see explanation below</td></tr>
  46  * </table>
  47  *
  48  * The vcs plugins need to register the Revision and RevisionSpecialType with
  49  * qRegisterMetaType.
  50  *
  51  * Also Users of this class should set RevisionSpecialType QVariant values via
  52  * <code>
  53  * setRevisionValue( qVariantFromValue<KDevelop::VcsRevision::RevisionSpecialType>( val ), KDevelop::VcsRevision::Special);
  54  * </code>
  55  * instead of
  56  * <code>
  57  * setRevisionValue( qVariantFromValue( val ), KDevelop::VcsRevision::Special);
  58  * </code>
  59  *
  60  * If the latter method is used the QVariant will be an Integer, which might not
  61  * be handled by the vcs plugin and is possibly ambiguous with the qlonglong
  62  * parameters.
  63  *
  64  */
  65 class KDEVPLATFORMVCS_EXPORT VcsRevision
  66 {
  67 public:
  68
  69     /**
  70      * @note Not all VCS's support both FileNumber and GlobalNumber. For those
  71      * that don't, asking for one may give you the other, therefore you should
  72      * check which is returned. For example, CVS does not support GlobalNumber,
  73      * and Subversion does not support FileNumber, while Perforce supports both.
  74      */
  75     enum RevisionType
  76     {
  77         Special = 0         /**< One of the special versions in RevisionSpecialType. */,
  78         GlobalNumber = 1    /**< Global repository version when item was last changed. */,
  79         FileNumber = 2      /**< Item's independent version number. */,
  80         Date = 3,           /**< The date of the revision to check out */
  81         Invalid = 4         /**< The type is not set, this is an invalid revision. */,
  82         UserType = 1000     /**< This should be used by subclasses as base for their own types. */
  83     };
  84     enum RevisionSpecialType
  85     {
  86         Head = 0                   /**< Latest revision in the repository. */,
  87         Working = 1                /**< The local copy (including any changes made). */,
  88         Base = 2                   /**< The repository source of the local copy. */,
  89         Previous = 3               /**< The version prior the other one (only valid in functions that take two revisions). */,
  90         Start = 4,                 /**< The first commit in a repository. */
  91         UserSpecialType = 1000     /**< This should be used by subclasses as base for their own special types. */
  92     };
  93
  94     VcsRevision();
  95     virtual ~VcsRevision();
  96
  97     VcsRevision( const VcsRevision& );
  98
  99     VcsRevision& operator=( const VcsRevision& );
 100
 101     /**
 102      * Set the value of this revision
 103      */
 104     void setRevisionValue( const QVariant& rev, RevisionType type );
 105
 106     /**
 107      * returns the type of the revision
 108      */
 109     RevisionType revisionType() const;
 110
 111     /**
 112      * return the value of this revision
 113      * The actualy content depends on the type of this revision, the possible
 114      * combinations are:
 115      *
 116      * FileNumber/GlobalNumber -> qlonglong
 117      * RevisionSpecialType     -> int that can be used to create a RevisionSpecialType
 118      * Date                    -> QDateTime
 119      *
 120      */
 121     QVariant revisionValue() const;
 122
 123     /**
 124      * This returns the value of the revision, suitable for displaying to the
 125      * user. For numbers it just returns the number converted to a string, for
 126      * the special types it returns the literal value of the special type and
 127      * for a datetime value it returns a localized string of the datetime value.
 128      */
 129     QString prettyValue() const;
 130
 131     bool operator==( const KDevelop::VcsRevision&) const;
 132
 133     /**
 134      * Helper function to create a vcs revision for one of the special types
 135      */
 136     static VcsRevision createSpecialRevision( KDevelop::VcsRevision::RevisionSpecialType type );
 137 protected:
 138     /**
 139      * Get the keys that make up the internal data of this revision instance
 140      */
 141     QStringList keys() const;
 142     /**
 143      * get the value for a given key, this retrieves internal data and is
 144      * meant to be used by subclasses
 145      */
 146     QVariant getValue( const QString& key ) const;
 147     /**
 148      * change the value of the given internal data
 149      */
 150     void setValue( const QString& key, const QVariant& value );
 151
 152     /**
 153      * write methods for subclasses to easily set the type and value
 154      */
 155     void setType( RevisionType t);
 156     void setSpecialType( RevisionSpecialType t);
 157     void setValue( const QVariant& );
 158
 159
 160 private:
 161     class VcsRevisionPrivate* const d;
 162 };
 163
 164 KDEVPLATFORMVCS_EXPORT uint qHash( const KDevelop::VcsRevision& rev);
 165
 166 }
 167
 168 Q_DECLARE_METATYPE(KDevelop::VcsRevision)
 169 Q_DECLARE_METATYPE(KDevelop::VcsRevision::RevisionSpecialType)
 170
 171
 172
 173 #endif
 174