1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the tools applications of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include <QHash>

    43 #include <QString>

    44 

    45 #include "qapplicationargument_p.h"

    46 

    47 QT_BEGIN_NAMESPACE

    48 

    49 /*!

    50  \class QApplicationArgument

    51  \brief The QApplicationArgument class is a declared of a command line

    52         argument for QApplicationArgumentParser.

    53  \reentrant

    54  \internal

    55  \since 4.4

    56 

    57  QApplicationArgument describes a valid command line argument,

    58  by having a set of characteristics:

    59 

    60  \table

    61    \header

    62         \o Characteristic

    63         \o Functions

    64     \row

    65         \o A name. For instance, "backend"

    66         \o setName() and name()

    67     \row

    68         \o A description, for human consumption.

    69         \o setDescription() and description()

    70     \row

    71         \o How many times the argument can occur. For instance, whether the argument is optional or not.

    72         \o setMinimumOccurrence() & minimumOccurrence(), setMaximumOccurrence() & maximumOccurrence()

    73     \row

    74         \o The type of the argument's value, if it has one. For instance, \c int or \c bool.

    75         \o setType() and type()

    76     \row

    77         \o The value that should be used in case the argument isn't used.

    78         \o setDefaultValue() and defaultValue()

    79  \endtable

    80 

    81  \sa QApplicationArgumentParser

    82  */

    83 

    84 class QApplicationArgumentPrivate

    85 {

    86 public:

    87     inline QApplicationArgumentPrivate(const QString &newName,

    88                                        const QString &desc,

    89                                        const int newType) : name(newName)

    90                                                           , description(desc)

    91                                                           , type(newType)

    92                                                           , minimum(0)

    93                                                           , maximum(1)

    94                                                           , isNameless(false)

    95     {

    96     }

    97 

    98     QString         name;

    99     QString         description;

   100     int             type;

   101     QVariant        defaultValue;

   102     int             minimum;

   103     int             maximum;

   104     bool            isNameless;

   105 };

   106 

   107 /*!

   108   Constructs an invalid QApplicationArgument instance.

   109  */

   110 QApplicationArgument::QApplicationArgument() : d_ptr(new QApplicationArgumentPrivate(QString(), QString(), QVariant::Invalid))

   111 {

   112 }

   113 

   114 /*!

   115  Constructs an QApplicationArgument instance that is a copy of \a other.

   116  */

   117 QApplicationArgument::QApplicationArgument(const QApplicationArgument &other) : d_ptr(new QApplicationArgumentPrivate(*other.d_ptr))

   118 {

   119 }

   120 

   121 /*!

   122  Destructs this QApplicationArgument instance.

   123  */

   124 QApplicationArgument::~QApplicationArgument()

   125 {

   126     delete d_ptr;

   127 }

   128 

   129 /*!

   130  Constructs an argument that has the name \a name and is of type

   131  \a aType.

   132 

   133  Calling this constructor is equivalent to calling setName() and setType()

   134  on a default constructed QApplicationArgument instance.

   135 

   136  \sa setName(), setType()

   137  */

   138 QApplicationArgument::QApplicationArgument(const QString &name,

   139                                            const QString &description,

   140                                            int aType) : d_ptr(new QApplicationArgumentPrivate(name, description, aType))

   141 {

   142 }

   143 

   144 /*!

   145  Assigns \a other to this QApplicationArgument instance.

   146  */

   147 QApplicationArgument &QApplicationArgument::operator=(const QApplicationArgument &other)

   148 {

   149     if(this != &other)

   150         *d_ptr = *other.d_ptr;

   151 

   152     return *this;

   153 }

   154 

   155 // TODO is this really what we want?

   156 /*!

   157  Returns true if this QApplicationArgument instance is equal to \a other.

   158 

   159  Equalness is defined to only consider name(). If for instance the type() differs

   160  but the names are equal, this operator will return \c true.

   161  */

   162 bool QApplicationArgument::operator==(const QApplicationArgument &other) const

   163 {

   164     return name() == other.name();

   165 }

   166 

   167 /*!

   168   \fn qHash(const QApplicationArgument &);

   169   \internal

   170 

   171   Returns a hash index of \a argument. This function is used when QApplicationArgument

   172   is used with QHash.

   173 

   174   The hash index is computed on name(). The other properties are ignored.

   175 

   176  \relates QApplicationArgument

   177  */

   178 

   179 /*!

   180  Sets this argument's name to \a newName. The name does not

   181  include any dash, or other prefix that is used by the parser.

   182  */

   183 void QApplicationArgument::setName(const QString &newName)

   184 {

   185     d_ptr->name = newName;

   186 }

   187 

   188 /*!

   189  Returns the name that this argument has.

   190 

   191  \sa setName()

   192  */

   193 QString QApplicationArgument::name() const

   194 {

   195     return d_ptr->name;

   196 }

   197 

   198 /*!

   199  Sets the tupe to \a newType.

   200 

   201  If \a newType is QVariant::Invalid, it signals that this

   202  argument does not accept a value at all.

   203 

   204  \a newType can be a QVariant::type() value, or QVariant::userType().

   205 

   206  \sa type()

   207  */

   208 void QApplicationArgument::setType(int newType)

   209 {

   210     d_ptr->type = newType;

   211 }

   212 

   213 /*!

   214  Returns the type that the value of this argument has. If it

   215  is QVariant::Invalid, it means this argument cannot have a value

   216  and is a switch only.

   217 

   218  The type is by default QVariant::Invalid.

   219 \sa setType()

   220  */

   221 int QApplicationArgument::type() const

   222 {

   223     return d_ptr->type;

   224 }

   225 

   226 void QApplicationArgument::setDefaultValue(const QVariant &value)

   227 {

   228     d_ptr->defaultValue = value;

   229 }

   230 

   231 QVariant QApplicationArgument::defaultValue() const

   232 {

   233     return d_ptr->defaultValue;

   234 }

   235 

   236 /*!

   237  Sets the minimum amount of times this argument can occur, to \a minimum.

   238  For instance, if \a minimum is 2, the argument must be used at least two times.

   239 

   240  If \a minimum is zero, it means the argument is optional.

   241 

   242  \sa minimumOccurrence(), setMaximumOccurrence()

   243  */

   244 void QApplicationArgument::setMinimumOccurrence(int minimum)

   245 {

   246     Q_ASSERT_X(minimum >= 0, Q_FUNC_INFO,

   247            "The minimum cannot be less than zero.");

   248     d_ptr->minimum = minimum;

   249 }

   250 

   251 /*!

   252  Returns the minimum amount of times an an argument must occur.

   253 

   254  The default is 0.

   255 

   256  \sa setMinimumOccurrence(), maximumOccurrence()

   257  */

   258 int QApplicationArgument::minimumOccurrence() const

   259 {

   260     return d_ptr->minimum;

   261 }

   262 

   263 /*!

   264  Sets the maximum occurrence to \a maximum.

   265 

   266  If \a maximum is -1, it means the argument can appear an unlimited

   267  amount of times. Setting it to zero or less than -1, yields

   268  undefined behavior.

   269 

   270 \sa maximumOccurrence(), setMinimumOccurrence()

   271  */

   272 void QApplicationArgument::setMaximumOccurrence(int maximum)

   273 {

   274     Q_ASSERT_X(maximum == -1 || maximum >= 1, Q_FUNC_INFO,

   275            "The maximum can only be -1 or 1 or larger.");

   276     d_ptr->maximum = maximum;

   277 }

   278 

   279 /*!

   280  Returns the maximum amount of times this argument can occur. For instance,

   281  if the maximum occurrence is 2, it would be an error if 3 were specified

   282  on the command line.

   283 

   284  If the maximum occurrence is -1, it signals the argument can appear an unlimited

   285  amount of times.

   286 

   287  The default is 1.

   288 

   289  \sa setMaximumOccurrence()

   290  */

   291 int QApplicationArgument::maximumOccurrence() const

   292 {

   293     return d_ptr->maximum;

   294 }

   295 

   296 /*!

   297  Sets the description to \a newDescription. The description

   298  should describe the argument in a sentence or two. It is used

   299  when displaying a help message, if requested.

   300 

   301  The description should be terminated as if it was a paragraph. This

   302  typically means a period.

   303 

   304  The description should be translated by wrapping the

   305  string literal in a call to tr().

   306 

   307  */

   308 void QApplicationArgument::setDescription(const QString &newDescription)

   309 {

   310     d_ptr->description = newDescription;

   311 }

   312 

   313 /*!

   314  Returns the description of this argument.

   315 

   316  \sa setDescription()

   317  */

   318 QString QApplicationArgument::description() const

   319 {

   320     return d_ptr->description;

   321 }

   322 

   323 /*!

   324  \internal

   325  \relates QApplicationArgument

   326 

   327  Computes a hash key on \a argument's name and returns it.

   328  */

   329 uint qHash(const QApplicationArgument &argument)

   330 {

   331     return qHash(argument.name());

   332 }

   333 

   334 void QApplicationArgument::setNameless(bool value)

   335 {

   336     d_ptr->isNameless = value;

   337 }

   338 

   339 bool QApplicationArgument::isNameless() const

   340 {

   341     return d_ptr->isNameless;

   342 }

   343 

   344 QT_END_NAMESPACE