qcommandlineparser.cpp

Go to the documentation of this file.

/****************************************************************************
**
** Copyright (C) 2013 Laszlo Papp <lpapp@kde.org>
** Copyright (C) 2013 David Faure <faure@kde.org>
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
 
#include "qcommandlineparser.h"
 
#include <qcoreapplication.h>
#include <private/qcoreapplication_p.h>
#include <qhash.h>
#include <qlist.h>
#include <qdebug.h>
#if defined(Q_OS_WIN) && !defined(QT_BOOTSTRAPPED)
#  include <qt_windows.h>
#endif
#include <stdio.h>
#include <stdlib.h>
 
QT_BEGIN_NAMESPACE
 
extern void Q_CORE_EXPORT qt_call_post_routines();
 
typedef QHash<QString, int> NameHash_t;
 
class QCommandLineParserPrivate
{
public:
    inline QCommandLineParserPrivate()
        : singleDashWordOptionMode(QCommandLineParser::ParseAsCompactedShortOptions),
          optionsAfterPositionalArgumentsMode(QCommandLineParser::ParseAsOptions),
          builtinVersionOption(false),
          builtinHelpOption(false),
          needsParsing(true)
    { }
 
    bool parse(const QStringList &args);
    void checkParsed(const char *method);
    QStringList aliases(const QString &name) const;
    QString helpText(bool includeQtOptions) const;
    bool registerFoundOption(const QString &optionName);
    bool parseOptionValue(const QString &optionName, const QString &argument,
                          QStringList::const_iterator *argumentIterator,
                          QStringList::const_iterator argsEnd);
    Q_NORETURN void showHelp(int exitCode, bool includeQtOptions);
 
    QString errorText;
 
    QList<QCommandLineOption> commandLineOptionList;
 
    NameHash_t nameHash;
 
    QHash<int, QStringList> optionValuesHash;
 
    QStringList optionNames;
 
    QStringList positionalArgumentList;
 
    QStringList unknownOptionNames;
 
    QString description;
 
    struct PositionalArgumentDefinition
    {
        QString name;
        QString description;
        QString syntax;
    };
    QList<PositionalArgumentDefinition> positionalArgumentDefinitions;
 
    QCommandLineParser::SingleDashWordOptionMode singleDashWordOptionMode;
 
    QCommandLineParser::OptionsAfterPositionalArgumentsMode optionsAfterPositionalArgumentsMode;
 
    bool builtinVersionOption;
 
    bool builtinHelpOption;
 
    bool needsParsing;
};
Q_DECLARE_TYPEINFO(QCommandLineParserPrivate::PositionalArgumentDefinition, Q_RELOCATABLE_TYPE);
 
QStringList QCommandLineParserPrivate::aliases(const QString &optionName) const
{
    const NameHash_t::const_iterator it = nameHash.constFind(optionName);
    if (it == nameHash.cend()) {
        qWarning("QCommandLineParser: option not defined: \"%ls\"", qUtf16Printable(optionName));
        return QStringList();
    }
    return commandLineOptionList.at(*it).names();
}
 
QCommandLineParser::QCommandLineParser()
    : d(new QCommandLineParserPrivate)
{
}
 
QCommandLineParser::~QCommandLineParser()
{
    delete d;
}
 
void QCommandLineParser::setSingleDashWordOptionMode(QCommandLineParser::SingleDashWordOptionMode singleDashWordOptionMode)
{
    d->singleDashWordOptionMode = singleDashWordOptionMode;
}
 
void QCommandLineParser::setOptionsAfterPositionalArgumentsMode(QCommandLineParser::OptionsAfterPositionalArgumentsMode parsingMode)
{
    d->optionsAfterPositionalArgumentsMode = parsingMode;
}
 
bool QCommandLineParser::addOption(const QCommandLineOption &option)
{
    const QStringList optionNames = option.names();
 
    if (!optionNames.isEmpty()) {
        for (const QString &name : optionNames) {
            if (d->nameHash.contains(name)) {
                qWarning() << "QCommandLineParser: already having an option named" << name;
                return false;
            }
        }
 
        d->commandLineOptionList.append(option);
 
        const int offset = d->commandLineOptionList.size() - 1;
        for (const QString &name : optionNames)
            d->nameHash.insert(name, offset);
 
        return true;
    }
 
    return false;
}
 
bool QCommandLineParser::addOptions(const QList<QCommandLineOption> &options)
{
    // should be optimized (but it's no worse than what was possible before)
    bool result = true;
    for (QList<QCommandLineOption>::const_iterator it = options.begin(), end = options.end(); it != end; ++it)
        result &= addOption(*it);
    return result;
}
 
QCommandLineOption QCommandLineParser::addVersionOption()
{
    QCommandLineOption opt(QStringList() << QStringLiteral("v") << QStringLiteral("version"), tr("Displays version information."));
    addOption(opt);
    d->builtinVersionOption = true;
    return opt;
}
 
QCommandLineOption QCommandLineParser::addHelpOption()
{
    QCommandLineOption opt(QStringList()
#ifdef Q_OS_WIN
                << QStringLiteral("?")
#endif
                << QStringLiteral("h")
                << QStringLiteral("help"), tr("Displays help on commandline options."));
    addOption(opt);
    QCommandLineOption optHelpAll(QStringLiteral("help-all"), tr("Displays help including Qt specific options."));
    addOption(optHelpAll);
    d->builtinHelpOption = true;
    return opt;
}
 
void QCommandLineParser::setApplicationDescription(const QString &description)
{
    d->description = description;
}
 
QString QCommandLineParser::applicationDescription() const
{
    return d->description;
}
 
void QCommandLineParser::addPositionalArgument(const QString &name, const QString &description, const QString &syntax)
{
    QCommandLineParserPrivate::PositionalArgumentDefinition arg;
    arg.name = name;
    arg.description = description;
    arg.syntax = syntax.isEmpty() ? name : syntax;
    d->positionalArgumentDefinitions.append(arg);
}
 
void QCommandLineParser::clearPositionalArguments()
{
    d->positionalArgumentDefinitions.clear();
}
 
bool QCommandLineParser::parse(const QStringList &arguments)
{
    return d->parse(arguments);
}
 
QString QCommandLineParser::errorText() const
{
    if (!d->errorText.isEmpty())
        return d->errorText;
    if (d->unknownOptionNames.count() == 1)
        return tr("Unknown option '%1'.").arg(d->unknownOptionNames.first());
    if (d->unknownOptionNames.count() > 1)
        return tr("Unknown options: %1.").arg(d->unknownOptionNames.join(QStringLiteral(", ")));
    return QString();
}
 
enum MessageType { UsageMessage, ErrorMessage };
 
#if defined(Q_OS_WIN) && !defined(QT_BOOTSTRAPPED)
// Return whether to use a message box. Use handles if a console can be obtained
// or we are run with redirected handles (for example, by QProcess).
static inline bool displayMessageBox()
{
    if (GetConsoleWindow())
        return false;
    STARTUPINFO startupInfo;
    startupInfo.cb = sizeof(STARTUPINFO);
    GetStartupInfo(&startupInfo);
    return !(startupInfo.dwFlags & STARTF_USESTDHANDLES);
}
#endif // Q_OS_WIN && !QT_BOOTSTRAPPED
 
static void showParserMessage(const QString &message, MessageType type)
{
#if defined(Q_OS_WIN) && !defined(QT_BOOTSTRAPPED)
    if (displayMessageBox()) {
        const UINT flags = MB_OK | MB_TOPMOST | MB_SETFOREGROUND
            | (type == UsageMessage ? MB_ICONINFORMATION : MB_ICONERROR);
        QString title;
        if (QCoreApplication::instance())
            title = QCoreApplication::instance()->property("applicationDisplayName").toString();
        if (title.isEmpty())
            title = QCoreApplication::applicationName();
        MessageBoxW(0, reinterpret_cast<const wchar_t *>(message.utf16()),
                    reinterpret_cast<const wchar_t *>(title.utf16()), flags);
        return;
    }
#endif // Q_OS_WIN && !QT_BOOTSTRAPPED
    fputs(qPrintable(message), type == UsageMessage ? stdout : stderr);
}
 
void QCommandLineParser::process(const QStringList &arguments)
{
    if (!d->parse(arguments)) {
        showParserMessage(QCoreApplication::applicationName() + QLatin1String(": ") + errorText() + QLatin1Char('\n'), ErrorMessage);
        qt_call_post_routines();
        ::exit(EXIT_FAILURE);
    }
 
    if (d->builtinVersionOption && isSet(QStringLiteral("version")))
        showVersion();
 
    if (d->builtinHelpOption && isSet(QStringLiteral("help")))
        d->showHelp(EXIT_SUCCESS, false);
 
    if (d->builtinHelpOption && isSet(QStringLiteral("help-all")))
        d->showHelp(EXIT_SUCCESS, true);
}
 
void QCommandLineParser::process(const QCoreApplication &app)
{
    // QCoreApplication::arguments() is static, but the app instance must exist so we require it as parameter
    Q_UNUSED(app);
    process(QCoreApplication::arguments());
}
 
void QCommandLineParserPrivate::checkParsed(const char *method)
{
    if (needsParsing)
        qWarning("QCommandLineParser: call process() or parse() before %s", method);
}
 
bool QCommandLineParserPrivate::registerFoundOption(const QString &optionName)
{
    if (nameHash.contains(optionName)) {
        optionNames.append(optionName);
        return true;
    } else {
        unknownOptionNames.append(optionName);
        return false;
    }
}
 
bool QCommandLineParserPrivate::parseOptionValue(const QString &optionName, const QString &argument,
                                                 QStringList::const_iterator *argumentIterator, QStringList::const_iterator argsEnd)
{
    const QLatin1Char assignChar('=');
    const NameHash_t::const_iterator nameHashIt = nameHash.constFind(optionName);
    if (nameHashIt != nameHash.constEnd()) {
        const int assignPos = argument.indexOf(assignChar);
        const NameHash_t::mapped_type optionOffset = *nameHashIt;
        const bool withValue = !commandLineOptionList.at(optionOffset).valueName().isEmpty();
        if (withValue) {
            if (assignPos == -1) {
                ++(*argumentIterator);
                if (*argumentIterator == argsEnd) {
                    errorText = QCommandLineParser::tr("Missing value after '%1'.").arg(argument);
                    return false;
                }
                optionValuesHash[optionOffset].append(*(*argumentIterator));
            } else {
                optionValuesHash[optionOffset].append(argument.mid(assignPos + 1));
            }
        } else {
            if (assignPos != -1) {
                errorText = QCommandLineParser::tr("Unexpected value after '%1'.").arg(argument.left(assignPos));
                return false;
            }
        }
    }
    return true;
}
 
bool QCommandLineParserPrivate::parse(const QStringList &args)
{
    needsParsing = false;
    bool error = false;
 
    const QString     doubleDashString(QStringLiteral("--"));
    const QLatin1Char dashChar('-');
    const QLatin1Char assignChar('=');
 
    bool forcePositional = false;
    errorText.clear();
    positionalArgumentList.clear();
    optionNames.clear();
    unknownOptionNames.clear();
    optionValuesHash.clear();
 
    if (args.isEmpty()) {
        qWarning("QCommandLineParser: argument list cannot be empty, it should contain at least the executable name");
        return false;
    }
 
    QStringList::const_iterator argumentIterator = args.begin();
    ++argumentIterator; // skip executable name
 
    for (; argumentIterator != args.end() ; ++argumentIterator) {
        QString argument = *argumentIterator;
 
        if (forcePositional) {
            positionalArgumentList.append(argument);
        } else if (argument.startsWith(doubleDashString)) {
            if (argument.length() > 2) {
                QString optionName = argument.mid(2).section(assignChar, 0, 0);
                if (registerFoundOption(optionName)) {
                    if (!parseOptionValue(optionName, argument, &argumentIterator, args.end()))
                        error = true;
                } else {
                    error = true;
                }
            } else {
                forcePositional = true;
            }
        } else if (argument.startsWith(dashChar)) {
            if (argument.size() == 1) { // single dash ("stdin")
                positionalArgumentList.append(argument);
                continue;
            }
            switch (singleDashWordOptionMode) {
            case QCommandLineParser::ParseAsCompactedShortOptions:
            {
                QString optionName;
                bool valueFound = false;
                for (int pos = 1 ; pos < argument.size(); ++pos) {
                    optionName = argument.mid(pos, 1);
                    if (!registerFoundOption(optionName)) {
                        error = true;
                    } else {
                        const NameHash_t::const_iterator nameHashIt = nameHash.constFind(optionName);
                        Q_ASSERT(nameHashIt != nameHash.constEnd()); // checked by registerFoundOption
                        const NameHash_t::mapped_type optionOffset = *nameHashIt;
                        const bool withValue = !commandLineOptionList.at(optionOffset).valueName().isEmpty();
                        if (withValue) {
                            if (pos + 1 < argument.size()) {
                                if (argument.at(pos + 1) == assignChar)
                                    ++pos;
                                optionValuesHash[optionOffset].append(argument.mid(pos + 1));
                                valueFound = true;
                            }
                            break;
                        }
                        if (pos + 1 < argument.size() && argument.at(pos + 1) == assignChar)
                            break;
                    }
                }
                if (!valueFound && !parseOptionValue(optionName, argument, &argumentIterator, args.end()))
                    error = true;
                break;
            }
            case QCommandLineParser::ParseAsLongOptions:
            {
                if (argument.size() > 2) {
                    const QString possibleShortOptionStyleName = argument.mid(1, 1);
                    const auto shortOptionIt = nameHash.constFind(possibleShortOptionStyleName);
                    if (shortOptionIt != nameHash.constEnd()) {
                        const auto &arg = commandLineOptionList.at(*shortOptionIt);
                        if (arg.flags() & QCommandLineOption::ShortOptionStyle) {
                            registerFoundOption(possibleShortOptionStyleName);
                            optionValuesHash[*shortOptionIt].append(argument.mid(2));
                            break;
                        }
                    }
                }
                const QString optionName = argument.mid(1).section(assignChar, 0, 0);
                if (registerFoundOption(optionName)) {
                    if (!parseOptionValue(optionName, argument, &argumentIterator, args.end()))
                        error = true;
                } else {
                    error = true;
                }
                break;
            }
            }
        } else {
            positionalArgumentList.append(argument);
            if (optionsAfterPositionalArgumentsMode == QCommandLineParser::ParseAsPositionalArguments)
                forcePositional = true;
        }
        if (argumentIterator == args.end())
            break;
    }
    return !error;
}
 
bool QCommandLineParser::isSet(const QString &name) const
{
    d->checkParsed("isSet");
    if (d->optionNames.contains(name))
        return true;
    const QStringList aliases = d->aliases(name);
    for (const QString &optionName : qAsConst(d->optionNames)) {
        if (aliases.contains(optionName))
            return true;
    }
    return false;
}
 
QString QCommandLineParser::value(const QString &optionName) const
{
    d->checkParsed("value");
    const QStringList valueList = values(optionName);
 
    if (!valueList.isEmpty())
        return valueList.last();
 
    return QString();
}
 
QStringList QCommandLineParser::values(const QString &optionName) const
{
    d->checkParsed("values");
    const NameHash_t::const_iterator it = d->nameHash.constFind(optionName);
    if (it != d->nameHash.cend()) {
        const int optionOffset = *it;
        QStringList values = d->optionValuesHash.value(optionOffset);
        if (values.isEmpty())
            values = d->commandLineOptionList.at(optionOffset).defaultValues();
        return values;
    }
 
    qWarning("QCommandLineParser: option not defined: \"%ls\"", qUtf16Printable(optionName));
    return QStringList();
}
 
bool QCommandLineParser::isSet(const QCommandLineOption &option) const
{
    // option.names() might be empty if the constructor failed
    const auto names = option.names();
    return !names.isEmpty() && isSet(names.first());
}
 
QString QCommandLineParser::value(const QCommandLineOption &option) const
{
    return value(option.names().constFirst());
}
 
QStringList QCommandLineParser::values(const QCommandLineOption &option) const
{
    return values(option.names().constFirst());
}
 
QStringList QCommandLineParser::positionalArguments() const
{
    d->checkParsed("positionalArguments");
    return d->positionalArgumentList;
}
 
QStringList QCommandLineParser::optionNames() const
{
    d->checkParsed("optionNames");
    return d->optionNames;
}
 
QStringList QCommandLineParser::unknownOptionNames() const
{
    d->checkParsed("unknownOptionNames");
    return d->unknownOptionNames;
}
 
Q_NORETURN void QCommandLineParser::showVersion()
{
    showParserMessage(QCoreApplication::applicationName() + QLatin1Char(' ')
                      + QCoreApplication::applicationVersion() + QLatin1Char('\n'),
                      UsageMessage);
    qt_call_post_routines();
    ::exit(EXIT_SUCCESS);
}
 
Q_NORETURN void QCommandLineParser::showHelp(int exitCode)
{
    d->showHelp(exitCode, false);
}
 
Q_NORETURN void QCommandLineParserPrivate::showHelp(int exitCode, bool includeQtOptions)
{
    showParserMessage(helpText(includeQtOptions), UsageMessage);
    qt_call_post_routines();
    ::exit(exitCode);
}
 
QString QCommandLineParser::helpText() const
{
    return d->helpText(false);
}
 
static QString wrapText(const QString &names, int optionNameMaxWidth, const QString &description)
{
    const QLatin1Char nl('\n');
    const QLatin1String indentation("  ");
 
    // In case the list of option names is very long, wrap it as well
    int nameIndex = 0;
    auto nextNameSection = [&]() {
        QString section = names.mid(nameIndex, optionNameMaxWidth);
        nameIndex += section.size();
        return section;
    };
 
    QString text;
    int lineStart = 0;
    int lastBreakable = -1;
    const int max = 79 - (indentation.size() + optionNameMaxWidth + 1);
    int x = 0;
    const int len = description.length();
 
    for (int i = 0; i < len; ++i) {
        ++x;
        const QChar c = description.at(i);
        if (c.isSpace())
            lastBreakable = i;
 
        int breakAt = -1;
        int nextLineStart = -1;
        if (x > max && lastBreakable != -1) {
            // time to break and we know where
            breakAt = lastBreakable;
            nextLineStart = lastBreakable + 1;
        } else if ((x > max - 1 && lastBreakable == -1) || i == len - 1) {
            // time to break but found nowhere [-> break here], or end of last line
            breakAt = i + 1;
            nextLineStart = breakAt;
        } else if (c == nl) {
            // forced break
            breakAt = i;
            nextLineStart = i + 1;
        }
 
        if (breakAt != -1) {
            const int numChars = breakAt - lineStart;
            //qDebug() << "breakAt=" << description.at(breakAt) << "breakAtSpace=" << breakAtSpace << lineStart << "to" << breakAt << description.mid(lineStart, numChars);
            text += indentation + nextNameSection().leftJustified(optionNameMaxWidth) + QLatin1Char(' ');
            text += QStringView{description}.mid(lineStart, numChars) + nl;
            x = 0;
            lastBreakable = -1;
            lineStart = nextLineStart;
            if (lineStart < len && description.at(lineStart).isSpace())
                ++lineStart; // don't start a line with a space
            i = lineStart;
        }
    }
 
    while (nameIndex < names.size()) {
        text += indentation + nextNameSection() + nl;
    }
 
    return text;
}
 
QString QCommandLineParserPrivate::helpText(bool includeQtOptions) const
{
    const QLatin1Char nl('\n');
    QString text;
    QString usage;
    // executable name
    usage += qApp ? QCoreApplication::arguments().constFirst() : QStringLiteral("<executable_name>");
    QList<QCommandLineOption> options = commandLineOptionList;
    if (includeQtOptions && qApp)
        qApp->d_func()->addQtOptions(&options);
    if (!options.isEmpty())
        usage += QLatin1Char(' ') + QCommandLineParser::tr("[options]");
    for (const PositionalArgumentDefinition &arg : positionalArgumentDefinitions)
        usage += QLatin1Char(' ') + arg.syntax;
    text += QCommandLineParser::tr("Usage: %1").arg(usage) + nl;
    if (!description.isEmpty())
        text += description + nl;
    text += nl;
    if (!options.isEmpty())
        text += QCommandLineParser::tr("Options:") + nl;
    QStringList optionNameList;
    optionNameList.reserve(options.size());
    int longestOptionNameString = 0;
    for (const QCommandLineOption &option : qAsConst(options)) {
        if (option.flags() & QCommandLineOption::HiddenFromHelp)
            continue;
        const QStringList optionNames = option.names();
        QString optionNamesString;
        for (const QString &optionName : optionNames) {
            const int numDashes = optionName.length() == 1 ? 1 : 2;
            optionNamesString += QLatin1String("--", numDashes) + optionName + QLatin1String(", ");
        }
        if (!optionNames.isEmpty())
            optionNamesString.chop(2); // remove trailing ", "
        const auto valueName = option.valueName();
        if (!valueName.isEmpty())
            optionNamesString += QLatin1String(" <") + valueName + QLatin1Char('>');
        optionNameList.append(optionNamesString);
        longestOptionNameString = qMax(longestOptionNameString, optionNamesString.length());
    }
    ++longestOptionNameString;
    const int optionNameMaxWidth = qMin(50, longestOptionNameString);
    auto optionNameIterator = optionNameList.cbegin();
    for (const QCommandLineOption &option : qAsConst(options)) {
        if (option.flags() & QCommandLineOption::HiddenFromHelp)
            continue;
        text += wrapText(*optionNameIterator, optionNameMaxWidth, option.description());
        ++optionNameIterator;
    }
    if (!positionalArgumentDefinitions.isEmpty()) {
        if (!options.isEmpty())
            text += nl;
        text += QCommandLineParser::tr("Arguments:") + nl;
        for (const PositionalArgumentDefinition &arg : positionalArgumentDefinitions)
            text += wrapText(arg.name, optionNameMaxWidth, arg.description);
    }
    return text;
}
 
QT_END_NAMESPACE