/****************************************************************************

**

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

** All rights reserved.

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

**

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

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

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

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

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

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

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

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

**

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

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

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

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#include <QtDebug>

#include <QTextBoundaryFinder>

#include <QCoreApplication>

#include <QHash>

#include <QPair>

#include <QStringList>

#include <QTextStream>

#include <QUrl>

#include "qapplicationargument_p.h"

#include "qapplicationargumentparser_p.h"

QT_BEGIN_NAMESPACE

/*!

 \class QApplicationArgumentParser

 \brief The QApplicationArgumentParser class parses the command

        line arguments for an application.

 \reentrant

 \internal

 \since 4.4

 QApplicationArgumentParser simplifies writing command line applications by taking care of:

 \list

    \o Generating help and version arguments

    \o Taking care of converting arguments to QVariant types, since each argument

       has a type: QApplicationArgument::type()

    \o Validates the command line such that the user operates on well-defined input. For instance,

       that the argument is a valid integer if that is the case, that an argument does not

       occur more times than allowed, and so on.

    \o Allows customization through sub-classing.

 \endlist

 The user declares what arguments that can be given to the application with QApplicationArgument. Provided

 with that information, QApplicationArgumentParser takes care of parsing the actual

 command line, appropriately flag errors, generate help messages, and provide

 convenient access to the values of the arguments.

 The way to use it is to create a set of QApplicationArgument by ones choosing, call

 addArgument() for each, and subsequently call parse(). If parse() returns \c false,

 the caller should exit and return exitCode().

 If parse() returns \c true the command line was successfully parsed, its

 values are well-defined, and they can be spectated with count(),

 has(), value() and values().

 \snippet doc/src/snippets/code/tools_patternist_qapplicationargumentparser.cpp 0

 For arguments without a name(such as filename passed to the \c ls utility on Linux) add a

 QApplicationArgument that does not have a name. The minimum and maximum occurrences will be

 respected as usual and the type applies too.

 QApplicationArgumentParser always has two options builtin: \c version and \c help.

 \section1 Changing Parsing Convention

 QApplicationArgumentParser by default parses the command line in the style

 of Qt's utilities, where arguments are preceded by a single dash, and identified

 by a single name. However, in some cases it might be of interest to parse

 another style, such as the well-established UNIX \c getopt convention(\c -l

 and \c --long).

 This can be achieved by sub-classing QApplicationArgumentParser and reimplementing

 parse(). It would do the following:

 \list

    \o Call input() to retrieve the strings the user specified on the command line.

    \o Call declaredArguments() to retrieve the arguments that the implementor has

       decided can be specified.

    \o Parse and validate the input. Salt and pepper as per taste.

    \o If an error occurred, call setExitCode() and return \c false.

    \o Otherwise, call setExitCode(Success), provide access to the

       arguments by calling setUsedArguments(), and return \c true. If a

       help message was requested, call setExitCode(Success) and return \c false.

 \endlist

 \sa QApplicationArgument, QCoreApplication

*/

class QApplicationArgumentParserPrivate

{

    Q_DECLARE_TR_FUNCTIONS(QApplicationArgumentParserPrivate)

public:

    // TODO Isn't it like ten times better with QHash<QApplicationArgument, QList<QVariant> >?

    // TODO test QApplicationArgument::nameless()

    typedef QList<QPair<QApplicationArgument, QVariant> > UsedList;

    /*!

     We initialize exitCode to ParseError such that we consciously flag success.

     */

    inline QApplicationArgumentParserPrivate(QApplicationArgumentParser *const master,

                                             const QStringList &aInput) : exitCode(QApplicationArgumentParser::ParseError)

                                                                        , input(aInput)

                                                                        , q_ptr(master)

    {

        Q_ASSERT(!aInput.isEmpty());

    }

    QApplicationArgument nextNamelessArgument() const;

    static QStringList argumentsFromLocal(const int argc, const char *const *const argv);

    bool error(const QString &message);

    static bool errorMessage(const QString &message);

    static inline bool isSwitch(const QApplicationArgument &arg);

    static inline QVariant conversionError(const QString &typeName,

                                           const QString &input);

    int count(const QApplicationArgument &arg) const;

    bool contains(const QApplicationArgument &arg) const;

    static inline bool isBuiltinVariant(const int type);

    void displayVersion() const;

    void displayHelp() const;

    void parseNameless();

    bool parseNamelessArguments(const QString &in);

    QApplicationArgumentParser::ExitCode    exitCode;

    const QStringList                       input;

    /*!

      Since the QString is QApplicationArgument::name() anyway, why

      not use a QSet?

     */

    QHash<QString, QApplicationArgument>    declaredArguments;

    QList<QApplicationArgument>             declaredNamelessArguments;

    UsedList                                usedArguments;

    QString                                 applicationDescription;

    QString                                 applicationVersion;

private:

    QApplicationArgumentParser *const       q_ptr;

    Q_DECLARE_PUBLIC(QApplicationArgumentParser)

    static QString lineWrap(const QString &input,

                            const int leftIndent,

                            const int width);

    static QList<QApplicationArgument> builtinArguments();

};

QApplicationArgument QApplicationArgumentParserPrivate::nextNamelessArgument() const

{

    /* Count how many nameless arguments we have so far. */

    int count = 0;

    for(int i = 0; i < usedArguments.count(); ++i)

    {

        if(usedArguments.at(i).first.isNameless())

            ++count;

    }

    /* TODO this doesn't work for arguments that have more than one

     * mandatory value(e.g nameless ones), since several values should

     * then only count for one argument. */

    for(int i = 0; i < declaredNamelessArguments.count(); ++i)

    {

        if(count)

        {

            /* Skip the ones we already have processed. */

            --count;

            continue;

        }

        if(declaredNamelessArguments.at(i).isNameless())

            return declaredNamelessArguments.at(i);

    }

    return QApplicationArgument();

}

int QApplicationArgumentParserPrivate::count(const QApplicationArgument &arg) const

{

    const int len = usedArguments.count();

    int count = 0;

    for(int i = 0; i < len; ++i)

    {

        if(usedArguments.at(i).first == arg)

            ++count;

    }

    return count;

}

/*!

 Returns \c true if \a arg has appeared on the command line, not whether it has been declared.

 */

bool QApplicationArgumentParserPrivate::contains(const QApplicationArgument &arg) const

{

    const int len = usedArguments.count();

    for(int i = 0; i < len; ++i)

    {

        if(usedArguments.at(i).first == arg)

            return true;

    }

    return false;

}

/*!

 Returns always \c false.

 */

bool QApplicationArgumentParserPrivate::error(const QString &message)

{

    exitCode = QApplicationArgumentParser::ParseError;

    errorMessage(message);

    return errorMessage(tr("Pass -help for information about the command line."));

}

/*!

 Returns always \c false.

 */

bool QApplicationArgumentParserPrivate::errorMessage(const QString &message)

{

    QTextStream out(stderr, QIODevice::WriteOnly);

    out << message << endl;

    return false;

}

/*!

  \internal

  Determines whether \a arg carries a value or is on/off.

 */

bool QApplicationArgumentParserPrivate::isSwitch(const QApplicationArgument &arg)

{

    return arg.type() == QVariant::Invalid;

}

QVariant QApplicationArgumentParserPrivate::conversionError(const QString &typeName,

                                                            const QString &input)

{

    errorMessage(tr("Cannot convert %1 to type %2.").arg(input, typeName));

    return QVariant();

}

bool QApplicationArgumentParserPrivate::isBuiltinVariant(const int type)

{

    return type < int(QVariant::UserType);

}

/*!

  TODO Temporary, replace with a function in QCoreApplication.

*/

QStringList QApplicationArgumentParserPrivate::argumentsFromLocal(const int argc, const char *const *const argv)

{

    Q_ASSERT(argc >= 1);

    Q_ASSERT(argv);

    QStringList result;

    for(int i = 0; i < argc; ++i)

        result.append(QString::fromLocal8Bit(argv[i]));

    return result;

}

void QApplicationArgumentParserPrivate::displayVersion() const

{

    QTextStream out(stderr);

    out << tr("%1 version %2 using Qt %3").arg(QCoreApplication::applicationName(), applicationVersion, QString::fromAscii(qVersion()))

        << endl;

}

/*!

 \internal

 \relates QApplicationArgument

 qLess() functor for QApplicationArgument that considers the name.

 */

template<>

class qLess <QApplicationArgument>

{

public:

    inline bool operator()(const QApplicationArgument &o1,

                           const QApplicationArgument &o2) const

    {

        return o1.name().compare(o2.name()) < 0;

    }

};

void QApplicationArgumentParserPrivate::displayHelp() const

{

    enum Constants

    {

        /**

         * When we want to line wrap, 80 minus a couple of characters. This should

         * be suitable for vt100 compatible terminals.

         */

        LineWrapAt = 78,

        /**

         * The initial "  -" for each option.

         */

        IndentPadding = 3,

        /**

         * Pad for the brackets and space we use when we have a type.

         */

        ValueArgumentPadding = 4

    };

    QList<QApplicationArgument> args(declaredArguments.values());

    args += builtinArguments();

    /* Sort them, such that we get the nameless options at the end, and it

     * generally looks tidy. */

    qSort(args);

    /* This is the basic approach:

     * Switches:

     *  -name description

     * Value arguments:

     *  -name <name-of-value-type> description

     *

     * Nameless arguments

     *  name <type> description

     *

     * It all line-wraps at OutputWidth and the description is indented,

     * where the highest indent is the length of the name plus length of the name

     * of the type. */

    /* First we find the name with the largest width. */

    int maxWidth = 0;

    QList<QApplicationArgument> nameless(declaredNamelessArguments);

    qSort(nameless);

    /* Note, here the nameless arguments appear last, but are sorted

     * with themselves. */

    QList<QApplicationArgument> allArgs(args + nameless);

    const int allArgsCount = allArgs.count();

    for(int i = 0; i < allArgsCount; ++i)

    {

        const QApplicationArgument &at = allArgs.at(i);

        const int nameLength = at.name().length();

        const QString typeName(q_ptr->typeToName(at));

        const int typeNameLength = typeName.length();

        const int padding = at.type() == QVariant::Invalid ? 0 : ValueArgumentPadding;

        maxWidth = qMax(maxWidth, nameLength + typeNameLength + padding);

    }

    QTextStream out(stderr);

    out << endl

        << QString(IndentPadding, QLatin1Char(' '))

        << QCoreApplication::applicationName()

        << QLatin1String(" -- ")

        << applicationDescription

        << endl;

    // TODO synopsis

    /* One extra so we get some space between the overview and the options. */

    out << endl;

    const int indentWidth = maxWidth + 3;

    /* Ok, print them out. */

    for(int i = 0; i < allArgsCount; ++i)

    {

        const QApplicationArgument &at = allArgs.at(i);

        /* "  -name ". Indent a bit first, inspired by Qt's moc. */

        const QString &name = at.name();

        QString prolog(QLatin1String("  "));

        /* We have a special case for the single dash. */

        if(name == QChar::fromLatin1('-'))

            prolog.append(name);

        else

        {

            if(!at.isNameless())

                prolog.append(QLatin1Char('-'));

             prolog.append(name + QLatin1Char(' '));

        }

        if(at.type() != QVariant::Invalid)

        {

            /* It's not a switch, it has a value. */

            /* Do we have a default value? If so, the argument is optional. */

            const QString typeName(q_ptr->typeToName(at));

            if(at.defaultValue().isValid())

                prolog.append(QLatin1Char('[') + typeName + QLatin1Char(']'));

            else

                prolog.append(QLatin1Char('<') + typeName + QLatin1Char('>'));

            // TODO Don't we want to display the default value?

            prolog.append(QLatin1Char(' '));

        }

        prolog = prolog.leftJustified(indentWidth);

        out << prolog

            << lineWrap(at.description(), indentWidth, LineWrapAt)

            << endl;

    }

}

/*!

 Line wraps \a input and indents each line with \a leftIndent spaces, such that

 the width does not go beyond \a maxWidth.

 The addition of line endings is accounted for by the caller.

 With QTextBoundaryFinder our line wrapping is relatively fancy, since it

 does it the Unicode-way.

 */

QString QApplicationArgumentParserPrivate::lineWrap(const QString &input,

                                                    const int leftIndent,

                                                    const int maxWidth)

{

    const QString indent(QString(leftIndent, QLatin1Char(' ')));

    const int len = input.length();

    const int textWidth = maxWidth - leftIndent;

    QString output;

    QTextBoundaryFinder wrapFinder(QTextBoundaryFinder::Line, input);

    wrapFinder.setPosition(textWidth);

    if(input.length() + leftIndent <= maxWidth)

        return input;

    int from = wrapFinder.toPreviousBoundary();

    output.append(input.left(from));

    while(true)

    {

        if((len - from) + leftIndent > maxWidth)

        {

            /* We need to line wrap. */

            wrapFinder.setPosition(from + textWidth);

            const int currentWidthPos = wrapFinder.toPreviousBoundary();

            output.append(QLatin1Char('\n'));

            output.append(indent);

            output.append(input.mid(from, currentWidthPos - from).trimmed());

            from += (currentWidthPos - from);

        }

        else

        {

            /* Append the remains.  */

            output.append(QLatin1Char('\n'));

            output.append(indent);

            output.append(input.mid(from).trimmed());

            break;

        }

    }

    return output;

}

/*!

 Returns a list with the builtin options that the parser has

 */

QList<QApplicationArgument> QApplicationArgumentParserPrivate::builtinArguments()

{

    QList<QApplicationArgument> result;

    result.append(QApplicationArgument(QLatin1String("help"),

                                       QLatin1String("Displays this help.")));

    result.append(QApplicationArgument(QLatin1String("version"),

                                       QLatin1String("Displays version information.")));

    result.append(QApplicationArgument(QLatin1String("-"),

                                       QLatin1String("When appearing, any following options are not interpreted as switches.")));

    return result;

}

/* TODO, I don't think we want this function in a public API. Add it first when there is a demand. */

/*!

 Creates a QApplicationArgumentParser that will parse the input in \a argc and \a argv.

These arguments should be passed directly from the \c main() function, and the decoding

of the input will be taken care of appropriately, depending on platform.

 It is preferred to use the QStringList overload, in case the input is in the form of QStrings.

 */

QApplicationArgumentParser::QApplicationArgumentParser(int argc, char **argv) : d(new QApplicationArgumentParserPrivate(this, QApplicationArgumentParserPrivate::argumentsFromLocal(argc, argv)))

{

    Q_ASSERT_X(argv, Q_FUNC_INFO, "Argv cannot be null.");

    Q_ASSERT_X(argc >= 1, Q_FUNC_INFO,

               "argc must at least contain the application name. "

               "Use the QStringList overload instead.");

}