En esta página

QCommandLineParser Class

La clase QCommandLineParser permite gestionar las opciones de la línea de comandos. Más información...

Encabezado: #include <QCommandLineParser>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

Tipos públicos

(since 6.9) enum class MessageType { Information, Error }
enum OptionsAfterPositionalArgumentsMode { ParseAsOptions, ParseAsPositionalArguments }
enum SingleDashWordOptionMode { ParseAsCompactedShortOptions, ParseAsLongOptions }

Funciones públicas

QCommandLineParser()
~QCommandLineParser()
QCommandLineOption addHelpOption()
bool addOption(const QCommandLineOption &option)
bool addOptions(const QList<QCommandLineOption> &options)
void addPositionalArgument(const QString &name, const QString &description, const QString &syntax = QString())
QCommandLineOption addVersionOption()
QString applicationDescription() const
void clearPositionalArguments()
QString errorText() const
QString helpText() const
bool isSet(const QString &name) const
bool isSet(const QCommandLineOption &option) const
QStringList optionNames() const
bool parse(const QStringList &arguments)
QStringList positionalArguments() const
void process(const QStringList &arguments)
void process(const QCoreApplication &app)
void setApplicationDescription(const QString &description)
void setOptionsAfterPositionalArgumentsMode(QCommandLineParser::OptionsAfterPositionalArgumentsMode parsingMode)
void setSingleDashWordOptionMode(QCommandLineParser::SingleDashWordOptionMode singleDashWordOptionMode)
void showHelp(int exitCode = 0)
void showVersion()
QStringList unknownOptionNames() const
QString value(const QString &optionName) const
QString value(const QCommandLineOption &option) const
QStringList values(const QString &optionName) const
QStringList values(const QCommandLineOption &option) const

Miembros públicos estáticos

(since 6.9) void showMessageAndExit(QCommandLineParser::MessageType type, const QString &message, int exitCode = 0)

Descripción detallada

QCoreApplication proporciona los argumentos de la línea de comandos como una simple lista de cadenas. QCommandLineParser permite definir un conjunto de opciones, analizar los argumentos de la línea de comandos y almacenar qué opciones se han utilizado realmente, así como los valores de las mismas.

Cualquier argumento que no sea una opción (es decir, que no comience por -) se almacena como un «argumento posicional».

El analizador gestiona nombres cortos, nombres largos, más de un nombre para la misma opción y los valores de las opciones.

Las opciones de la línea de comandos se reconocen porque comienzan con uno o dos caracteres « - », seguidos del nombre de la opción. La opción « - » (un solo guión) es un caso especial, que a menudo significa «entrada estándar», y no se trata como una opción. El analizador tratará todo lo que haya después de la opción « -- » (doble guión) como argumentos posicionales.

Las opciones cortas son letras sueltas. La opción v se especificaría pasando -v en la línea de comandos. En el modo de análisis predeterminado, las opciones cortas pueden escribirse de forma compacta; por ejemplo, -abc es equivalente a -a -b -c. El modo de análisis puede cambiarse a ParseAsLongOptions, en cuyo caso -abc se analizará como la opción larga abc.

Las opciones largas tienen más de una letra y no se pueden agrupar. La opción larga verbose se pasaría como --verbose o -verbose.

Los valores se pueden pasar a las opciones utilizando el operador de asignación (-v=value, --verbose=value) o con un espacio (-v value, --verbose value). Esto funciona incluso si el valor comienza por -.

El analizador no admite valores opcionales: si una opción está configurada para requerir un valor, este debe estar presente. Si dicha opción se coloca en último lugar y no tiene valor, se tratará como si no se hubiera especificado.

El analizador no admite automáticamente la negación o desactivación de opciones largas mediante el formato « --disable-option » o « --no-option ». Sin embargo, es posible gestionar este caso de forma explícita creando una opción con « no-option » como uno de sus nombres y gestionándola de forma explícita.

Ejemplo:

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCoreApplication::setApplicationName("my-copy-program");
    QCoreApplication::setApplicationVersion("1.0");

    QCommandLineParser parser;
    parser.setApplicationDescription("Test helper");
    parser.addHelpOption();
    parser.addVersionOption();
    parser.addPositionalArgument("source", QCoreApplication::translate("main", "Source file to copy."));
    parser.addPositionalArgument("destination", QCoreApplication::translate("main", "Destination directory."));

    // A boolean option with a single name (-p)
    QCommandLineOption showProgressOption("p", QCoreApplication::translate("main", "Show progress during copy"));
    parser.addOption(showProgressOption);

    // A boolean option with multiple names (-f, --force)
    QCommandLineOption forceOption(QStringList() << "f" << "force",
            QCoreApplication::translate("main", "Overwrite existing files."));
    parser.addOption(forceOption);

    // An option with a value
    QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory",
            QCoreApplication::translate("main", "Copy all source files into <directory>."),
            QCoreApplication::translate("main", "directory"));
    parser.addOption(targetDirectoryOption);

    // Process the actual command line arguments given by the user
    parser.process(app);

    const QStringList args = parser.positionalArguments();
    // source is args.at(0), destination is args.at(1)

    bool showProgress = parser.isSet(showProgressOption);
    bool force = parser.isSet(forceOption);
    QString targetDir = parser.value(targetDirectoryOption);
    // ...
}

Las tres llamadas a addOption() del ejemplo anterior pueden simplificarse utilizando addOptions():

    parser.addOptions({
        // A boolean option with a single name (-p)
        {"p",
            QCoreApplication::translate("main", "Show progress during copy")},
        // A boolean option with multiple names (-f, --force)
        {{"f", "force"},
            QCoreApplication::translate("main", "Overwrite existing files.")},
        // An option with a value
        {{"t", "target-directory"},
            QCoreApplication::translate("main", "Copy all source files into <directory>."),
            QCoreApplication::translate("main", "directory")},
    });

Limitación conocida: el análisis de las opciones de Qt dentro de ` QCoreApplication ` y sus subclases se produce antes de que exista `QCommandLineParser`, por lo que este no puede tenerlo en cuenta. Esto significa que cualquier valor de opción que se parezca a una opción integrada de Qt será tratado por ` QCoreApplication ` como una opción integrada de Qt. Ejemplo: « --profile -reverse » hará que « QGuiApplication » detecte que la opción «-reverse» está activada y la elimine de « QCoreApplication::arguments()» antes de que «QCommandLineParser» defina la opción « profile » y analice la línea de comandos.

Cómo utilizar QCommandLineParser en aplicaciones complejas

En la práctica, es necesario realizar comprobaciones de error adicionales en los argumentos posicionales y los valores de las opciones. Por ejemplo, deben comprobarse los rangos numéricos.

Por lo tanto, es recomendable introducir una función para realizar el análisis de la línea de comandos que tome una estructura o clase que reciba los valores de las opciones y devuelva un objeto que represente el resultado. El ejemplo dnslookup del módulo QtNetwork ilustra esto:

struct DnsQuery
{
    DnsQuery() : type(QDnsLookup::A) {}

    QDnsLookup::Type type;
    QHostAddress nameServer;
    QString name;
};

struct CommandLineParseResult
{
    enum class Status {
        Ok,
        Error,
        VersionRequested,
        HelpRequested
    };
    Status statusCode = Status::Ok;
    std::optional<QString> errorString = std::nullopt;
};

CommandLineParseResult parseCommandLine(QCommandLineParser &parser, DnsQuery *query)
{
    using Status = CommandLineParseResult::Status;

    parser.setSingleDashWordOptionMode(QCommandLineParser::ParseAsLongOptions);
    const QCommandLineOption nameServerOption("n", "The name server to use.", "nameserver");
    parser.addOption(nameServerOption);
    const QCommandLineOption typeOption("t", "The lookup type.", "type");
    parser.addOption(typeOption);
    parser.addPositionalArgument("name", "The name to look up.");
    const QCommandLineOption helpOption = parser.addHelpOption();
    const QCommandLineOption versionOption = parser.addVersionOption();

    if (!parser.parse(QCoreApplication::arguments()))
        return { Status::Error, parser.errorText() };

    if (parser.isSet(versionOption))
        return { Status::VersionRequested };

    if (parser.isSet(helpOption))
        return { Status::HelpRequested };

    if (parser.isSet(nameServerOption)) {
        const QString nameserver = parser.value(nameServerOption);
        query->nameServer = QHostAddress(nameserver);
        if (query->nameServer.isNull()
            || query->nameServer.protocol() == QAbstractSocket::UnknownNetworkLayerProtocol) {
            return { Status::Error,
                     u"Bad nameserver address: %1"_s.arg(nameserver) };
        }
    }

    if (parser.isSet(typeOption)) {
        const QString typeParameter = parser.value(typeOption);
        if (std::optional<QDnsLookup::Type> type = typeFromParameter(typeParameter))
            query->type = *type;
        else
            return { Status::Error, u"Bad record type: %1"_s.arg(typeParameter) };
    }

    const QStringList positionalArguments = parser.positionalArguments();
    if (positionalArguments.isEmpty())
        return { Status::Error, u"Argument 'name' missing."_s };
    if (positionalArguments.size() > 1)
        return { Status::Error, u"Several 'name' arguments specified."_s };
    query->name = positionalArguments.first();

    return { Status::Ok };
}

En la función principal, se debe mostrar la ayuda en la salida estándar si se ha pasado la opción «help», y la aplicación debe devolver el código de salida 0.

Si se detecta un error, el mensaje de error debe mostrarse en la salida de error estándar y la aplicación debe devolver un código de salida distinto de 0.

    QCoreApplication::setApplicationVersion(QT_VERSION_STR);
    QCoreApplication::setApplicationName(QCoreApplication::translate("QDnsLookupExample",
                                                                     "DNS Lookup Example"));
    QCommandLineParser parser;
    parser.setApplicationDescription(QCoreApplication::translate("QDnsLookupExample",
                                                                 "An example demonstrating the "
                                                                 "class QDnsLookup."));
    DnsQuery query;
    using Status = CommandLineParseResult::Status;
    CommandLineParseResult parseResult = parseCommandLine(parser, &query);
    switch (parseResult.statusCode) {
    case Status::Ok:
        break;
    case Status::Error:
        std::fputs(qPrintable(parseResult.errorString.value_or(u"Unknown error occurred"_s)),
                   stderr);
        std::fputs("\n\n", stderr);
        std::fputs(qPrintable(parser.helpText()), stderr);
        return 1;
    case Status::VersionRequested:
        parser.showVersion();
        Q_UNREACHABLE_RETURN(0);
    case Status::HelpRequested:
        parser.showHelp();
        Q_UNREACHABLE_RETURN(0);
    }

Un caso especial a tener en cuenta aquí son las aplicaciones GUI en Windows y en plataformas móviles. Es posible que estas aplicaciones no utilicen los canales de salida o de error estándar, ya que la salida se descarta o no es accesible.

En Windows, QCommandLineParser utiliza cuadros de mensaje para mostrar información de uso y errores si no se puede obtener una ventana de consola. Estos cuadros de mensaje se pueden omitir configurando la variable de entorno ` QT_COMMAND_LINE_PARSER_NO_GUI_MESSAGE_BOXES `.

Para otras plataformas, se recomienda mostrar los textos de ayuda y los mensajes de error utilizando un ` QMessageBox`. Para conservar el formato del texto de ayuda, se debe utilizar texto enriquecido con elementos ` <pre> `:

switch (parseResult.statusCode) {
case Status::Ok:
    break;
case Status::Error: {
    QString errorMessage = parseResult.errorString.value_or(u"Unknown error occurred"_qs);
    QMessageBox::warning(0, QGuiApplication::applicationDisplayName(),
                         "<html><head/><body><h2>" + errorMessage + "</h2><pre>"
                         + parser.helpText() + "</pre></body></html>");
    return 1;
}
case Status::VersionRequested:
    QMessageBox::information(0, QGuiApplication::applicationDisplayName(),
                             QGuiApplication::applicationDisplayName() + ' '
                             + QCoreApplication::applicationVersion());
    return 0;
case Status::HelpRequested:
    QMessageBox::warning(0, QGuiApplication::applicationDisplayName(),
                         "<html><head/><body><pre>"
                         + parser.helpText() + "</pre></body></html>");
    return 0;
}

Sin embargo, esto no se aplica al ejemplo «dnslookup», ya que se trata de una aplicación de consola.

Véase también QCommandLineOption y QCoreApplication.

Documentación sobre tipos de miembro

[since 6.9] enum class QCommandLineParser::MessageType

La enumeración se utiliza para especificar el tipo de mensaje y cómo se mostrará a los usuarios.

ConstanteValorDescripción
QCommandLineParser::MessageType::Information0Se utiliza para mostrar mensajes informativos. El mensaje se mostrará en stdout.
QCommandLineParser::MessageType::Error1Se utiliza para mostrar mensajes de error. El mensaje se mostrará en stderr.

Esta enumeración se introdujo en Qt 6.9.

Véase también ` showMessageAndExit()`.

enum QCommandLineParser::OptionsAfterPositionalArgumentsMode

Esta enumeración describe la forma en que el analizador interpreta las opciones que aparecen después de los argumentos posicionales.

ConstanteValorDescripción
QCommandLineParser::ParseAsOptions0application argument --opt -t se interpreta como si se establecieran las opciones opt y t, al igual que lo haría application --opt -t argument. Este es el modo de análisis predeterminado. Para especificar que --opt y -t son, en cambio, argumentos posicionales, el usuario puede utilizar --, como en application argument -- --opt -t.
QCommandLineParser::ParseAsPositionalArguments1application argument --opt se interpreta como si tuviera dos argumentos posicionales: argument y --opt. Este modo resulta útil para ejecutables cuyo objetivo es iniciar otros ejecutables (por ejemplo, envoltorios, herramientas de depuración, etc.) o que admiten comandos internos seguidos de opciones para el comando. argument es el nombre del comando, y todas las opciones que aparecen a continuación pueden ser recopiladas y analizadas por otro analizador de línea de comandos, posiblemente en otro ejecutable.

Véase también setOptionsAfterPositionalArgumentsMode().

enum QCommandLineParser::SingleDashWordOptionMode

Esta enumeración describe la forma en que el analizador interpreta las opciones de la línea de comandos que utilizan un solo guión seguido de varias letras, como « -abc ».

ConstanteValorDescripción
QCommandLineParser::ParseAsCompactedShortOptions0-abc se interpreta como « -a -b -c », es decir, como tres opciones cortas que se han compactado en la línea de comandos, si ninguna de las opciones toma un valor. Si « a » toma un valor, entonces se interpreta como « -a bc », es decir, la opción corta « a » seguida del valor « bc ». Esto se utiliza habitualmente en herramientas que se comportan como compiladores, con el fin de gestionar opciones como « -DDEFINE=VALUE » o « -I/include/path ». Este es el modo de análisis predeterminado. Se recomienda que las nuevas aplicaciones utilicen este modo.
QCommandLineParser::ParseAsLongOptions1-abc se interpreta como --abc, es decir, como la opción larga denominada abc. Así es como las propias herramientas de Qt (uic, rcc...) siempre han analizado los argumentos. Este modo debe utilizarse para mantener la compatibilidad en aplicaciones que analizaban los argumentos de esta forma. Hay una excepción si la opción « a » tiene activada la bandera « QCommandLineOption::ShortOptionStyle »; en ese caso, se sigue interpretando como « -a bc ».

Véase también setSingleDashWordOptionMode().

Documentación de funciones miembro

QCommandLineParser::QCommandLineParser()

Crea un objeto analizador de la línea de comandos.

[noexcept] QCommandLineParser::~QCommandLineParser()

Destruye el objeto analizador de la línea de comandos.

QCommandLineOption QCommandLineParser::addHelpOption()

Añade opciones de ayuda al analizador de la línea de comandos.

Las opciones especificadas para esta línea de comandos se describen en -h o --help. En Windows, también se admite la alternativa -?. La opción --help-all amplía esto para incluir en la salida opciones genéricas de Qt que no están definidas por este comando.

QCommandLineParser gestiona estas opciones automáticamente.

Recuerda utilizar setApplicationDescription() para establecer la descripción de la aplicación, que se mostrará cuando se utilice esta opción.

Ejemplo:

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCoreApplication::setApplicationName("my-copy-program");
    QCoreApplication::setApplicationVersion("1.0");

    QCommandLineParser parser;
    parser.setApplicationDescription("Test helper");
    parser.addHelpOption();
    parser.addVersionOption();
    parser.addPositionalArgument("source", QCoreApplication::translate("main", "Source file to copy."));
    parser.addPositionalArgument("destination", QCoreApplication::translate("main", "Destination directory."));

    // A boolean option with a single name (-p)
    QCommandLineOption showProgressOption("p", QCoreApplication::translate("main", "Show progress during copy"));
    parser.addOption(showProgressOption);

    // A boolean option with multiple names (-f, --force)
    QCommandLineOption forceOption(QStringList() << "f" << "force",
            QCoreApplication::translate("main", "Overwrite existing files."));
    parser.addOption(forceOption);

    // An option with a value
    QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory",
            QCoreApplication::translate("main", "Copy all source files into <directory>."),
            QCoreApplication::translate("main", "directory"));
    parser.addOption(targetDirectoryOption);

    // Process the actual command line arguments given by the user
    parser.process(app);

    const QStringList args = parser.positionalArguments();
    // source is args.at(0), destination is args.at(1)

    bool showProgress = parser.isSet(showProgressOption);
    bool force = parser.isSet(forceOption);
    QString targetDir = parser.value(targetDirectoryOption);
    // ...
}

Devuelve la instancia de la opción, que se puede utilizar para llamar a ` isSet()`.

bool QCommandLineParser::addOption(const QCommandLineOption &option)

Añade la opción « option » para buscarla durante el análisis.

Devuelve « true » si la adición de la opción se ha realizado correctamente; en caso contrario, devuelve « false ».

La adición de la opción falla si no hay ningún nombre asociado a ella, o si el nombre de la opción entra en conflicto con el de una opción añadida anteriormente.

bool QCommandLineParser::addOptions(const QList<QCommandLineOption> &options)

Añade las opciones que se deben buscar durante el análisis. Las opciones se especifican mediante el parámetro options.

Devuelve ` true ` si se han añadido correctamente todas las opciones; en caso contrario, devuelve ` false`.

Consulte la documentación de addOption() para saber en qué casos puede fallar esta función.

void QCommandLineParser::addPositionalArgument(const QString &name, const QString &description, const QString &syntax = QString())

Define un argumento adicional para la aplicación, con el fin de completar el texto de ayuda.

Los argumentos « name » y « description » aparecerán en la sección « Arguments: » de la ayuda. Si se especifica « syntax », se añadirá a la línea «Usage»; de lo contrario, se añadirá « name ».

Ejemplo:

// Usage: image-editor file
//
// Arguments:
//   file                  The file to open.
parser.addPositionalArgument("file", QCoreApplication::translate("main", "The file to open."));

// Usage: web-browser [urls...]
//
// Arguments:
//   urls                URLs to open, optionally.
parser.addPositionalArgument("urls", QCoreApplication::translate("main", "URLs to open, optionally."), "[urls...]");

// Usage: cp source destination
//
// Arguments:
//   source                Source file to copy.
//   destination           Destination directory.
parser.addPositionalArgument("source", QCoreApplication::translate("main", "Source file to copy."));
parser.addPositionalArgument("destination", QCoreApplication::translate("main", "Destination directory."));

Véase también addHelpOption() y helpText().

QCommandLineOption QCommandLineParser::addVersionOption()

Añade la opción -v / --version, que muestra la cadena de versión de la aplicación.

Esta opción se gestiona automáticamente mediante QCommandLineParser.

Puedes establecer la cadena de versión real utilizando QCoreApplication::setApplicationVersion().

Devuelve la instancia de la opción, que se puede utilizar para llamar a isSet().

QString QCommandLineParser::applicationDescription() const

Devuelve la descripción de la aplicación establecida en setApplicationDescription().

Véase también setApplicationDescription().

void QCommandLineParser::clearPositionalArguments()

Elimina las definiciones de los argumentos adicionales del texto de ayuda.

Esto solo es necesario en el caso concreto de las herramientas que admiten varios comandos con diferentes opciones. Una vez identificado el comando concreto, se pueden definir las opciones de dicho comando y ajustar el texto de ayuda correspondiente.

Ejemplo:

QCoreApplication app(argc, argv);
QCommandLineParser parser;

parser.addPositionalArgument("command", "The command to execute.");

// Call parse() to find out the positional arguments.
parser.parse(QCoreApplication::arguments());

const QStringList args = parser.positionalArguments();
const QString command = args.isEmpty() ? QString() : args.first();
if (command == "resize") {
    parser.clearPositionalArguments();
    parser.addPositionalArgument("resize", "Resize the object to a new size.", "resize [resize_options]");
    parser.addOption(QCommandLineOption("size", "New size.", "new_size"));
    parser.process(app);
    // ...
}

/*
This code results in context-dependent help:

$ tool --help
Usage: tool command

Arguments:
  command  The command to execute.

$ tool resize --help
Usage: tool resize [resize_options]

Options:
  --size <size>  New size.

Arguments:
  resize         Resize the object to a new size.
*/

QString QCommandLineParser::errorText() const

Devuelve un texto de error traducido para el usuario. Solo debe llamarse a esta función cuando parse() devuelva false.

QString QCommandLineParser::helpText() const

Devuelve una cadena que contiene toda la información de ayuda.

Véase también showHelp().

bool QCommandLineParser::isSet(const QString &name) const

Comprueba si se ha pasado a la aplicación la opción « name ».

Devuelve ` true ` si se ha establecido la opción ` name `; en caso contrario, devuelve `false`.

El nombre proporcionado puede ser cualquier nombre largo o corto de cualquier opción que se haya añadido con addOption(). Todos los nombres de opciones se consideran equivalentes. Si no se reconoce el nombre o si esa opción no estaba presente, se devuelve «false».

Ejemplo:

bool verbose = parser.isSet("verbose");

bool QCommandLineParser::isSet(const QCommandLineOption &option) const

Comprueba si se ha pasado el valor de « option » a la aplicación.

Devuelve ` true ` si se ha establecido el ` option `; en caso contrario, devuelve `false`.

Esta es la forma recomendada de comprobar si hay opciones sin valores.

Ejemplo:

QCoreApplication app(argc, argv);
QCommandLineParser parser;
QCommandLineOption verboseOption("verbose");
parser.addOption(verboseOption);
parser.process(app);
bool verbose = parser.isSet(verboseOption);

Esta es una función sobrecargada.

QStringList QCommandLineParser::optionNames() const

Devuelve una lista con los nombres de las opciones que se han encontrado.

Esto devuelve una lista de todos los nombres de opciones reconocidos que ha encontrado el analizador, en el orden en que se han encontrado. En el caso de las opciones largas que tenían la forma {–opción=valor}, se habrá omitido la parte del valor.

Los nombres de esta lista no incluyen los guiones que los preceden. Los nombres pueden aparecer más de una vez en esta lista si el analizador los ha encontrado más de una vez.

Cualquier entrada de la lista se puede utilizar con value() o con values() para obtener los valores de las opciones correspondientes.

bool QCommandLineParser::parse(const QStringList &arguments)

Analiza la línea de comandos arguments.

La mayoría de los programas no necesitan llamar a esta función; basta con una simple llamada a ` process()`.

parse() es una función de más bajo nivel y solo se encarga del análisis. La aplicación deberá ocuparse de la gestión de errores utilizando errorText() si parse() devuelve un valor de tipo « false ». Esto puede resultar útil, por ejemplo, para mostrar un mensaje de error gráfico en programas gráficos.

Llamar a parse() en lugar de a process() también puede resultar útil para ignorar temporalmente opciones desconocidas, ya que más adelante se proporcionarán más definiciones de opciones (dependiendo de uno de los argumentos), antes de llamar a process().

No olvides que ` arguments ` debe comenzar con el nombre del ejecutable (aunque se ignore).

Devuelve false en caso de error de análisis (opción desconocida o valor que falta); devuelve true en caso contrario.

Véase también process().

QStringList QCommandLineParser::positionalArguments() const

Devuelve una lista de argumentos posicionales.

Se trata de todos los argumentos que no se han reconocido como parte de una opción.

void QCommandLineParser::process(const QStringList &arguments)

Procesa la línea de comandos arguments.

Además de analizar las opciones (como parse()), esta función también gestiona las opciones integradas y se encarga de los errores.

Las opciones integradas son --version si se ha llamado a addVersionOption y --help / --help-all si se ha llamado a addHelpOption.

Al invocar una de estas opciones, o cuando se produce un error (por ejemplo, si se ha pasado una opción desconocida), el proceso actual se detendrá mediante la función exit().

Véase también QCoreApplication::arguments() y parse().

void QCommandLineParser::process(const QCoreApplication &app)

La línea de comandos se obtiene de la instancia de « QCoreApplication » app.

Se trata de una función sobrecargada.

void QCommandLineParser::setApplicationDescription(const QString &description)

Establece la aplicación description que muestra la función helpText().

Véase también applicationDescription().

void QCommandLineParser::setOptionsAfterPositionalArgumentsMode(QCommandLineParser::OptionsAfterPositionalArgumentsMode parsingMode)

Establece el modo de análisis en « parsingMode ». Esta función debe llamarse antes de « process()» o « parse()».

void QCommandLineParser::setSingleDashWordOptionMode(QCommandLineParser::SingleDashWordOptionMode singleDashWordOptionMode)

Establece el modo de análisis en « singleDashWordOptionMode ». Esta función debe llamarse antes de « process()» o « parse()».

void QCommandLineParser::showHelp(int exitCode = 0)

Muestra la información de ayuda y cierra la aplicación. Esto se activa automáticamente con la opción –help, pero también puede utilizarse para mostrar la ayuda cuando el usuario no está ejecutando la aplicación correctamente. El código de salida se establece en exitCode. Debe establecerse en 0 si el usuario ha solicitado ver la ayuda, y en cualquier otro valor en caso de error.

Véanse también helpText() y showMessageAndExit().

[static, since 6.9] void QCommandLineParser::showMessageAndExit(QCommandLineParser::MessageType type, const QString &message, int exitCode = 0)

Muestra un « message » y cierra la aplicación con el « exitCode » indicado.

El message se imprimirá normalmente directamente en stdout o stderr según el type especificado, o bien el mensaje se mostrará en un cuadro de mensaje en Windows cuando sea necesario, con un icono de información o de error según el type especificado (configura la variable de entorno QT_COMMAND_LINE_PARSER_NO_GUI_MESSAGE_BOXES si no deseas que aparezca el cuadro de mensaje).

Es el mismo método de visualización de mensajes que utilizan showHelp, showVersion y las opciones integradas (--version si se ha llamado a addVersionOption y --help / --help-all si se ha llamado a addHelpOption ).

Esta función se introdujo en Qt 6.9.

Véase también addVersionOption(), showHelp(), showVersion() y QCommandLineParser::MessageType.

void QCommandLineParser::showVersion()

Muestra la información de versión de QCoreApplication::applicationVersion() y cierra la aplicación. Esto se activa automáticamente con la opción –version, pero también se puede utilizar para mostrar la versión cuando no se utiliza process(). El código de salida se establece en EXIT_SUCCESS (0).

Véase también addVersionOption().

QStringList QCommandLineParser::unknownOptionNames() const

Devuelve una lista de nombres de opciones desconocidos.

Esta lista incluirá tanto las opciones con nombre largo como las que tienen nombre corto que no se hayan reconocido. En el caso de las opciones largas que tuvieran el formato {–option=value}, se habrá omitido la parte del valor y solo se añadirá el nombre largo.

Los nombres de esta lista no incluyen los guiones que los preceden. Los nombres pueden aparecer más de una vez en esta lista si el analizador sintáctico los ha encontrado más de una vez.

Véase también optionNames().

QString QCommandLineParser::value(const QString &optionName) const

Devuelve el valor de la opción correspondiente al nombre de opción proporcionado optionName, o una cadena vacía si no se encuentra.

El nombre proporcionado puede ser cualquier nombre largo o corto de cualquier opción que se haya añadido con addOption(). Todos los nombres de opciones se consideran equivalentes. Si no se reconoce el nombre o si esa opción no estaba presente, se devuelve una cadena vacía.

En el caso de las opciones detectadas por el analizador, se devuelve el último valor encontrado para dicha opción. Si la opción no se ha especificado en la línea de comandos, se devuelve el valor por defecto.

Si la opción no admite ningún valor, se muestra una advertencia y se devuelve una cadena vacía.

Véase también values(), QCommandLineOption::setDefaultValue() y QCommandLineOption::setDefaultValues().

QString QCommandLineParser::value(const QCommandLineOption &option) const

Devuelve el valor de la opción encontrado para el option especificado, o una cadena vacía si no se encuentra.

En el caso de las opciones detectadas por el analizador, se devuelve el último valor encontrado para dicha opción. Si la opción no se ha especificado en la línea de comandos, se devuelve el valor por defecto.

Se devuelve una cadena vacía si la opción no admite ningún valor.

Esta es una función sobrecargada.

Véase también values(), QCommandLineOption::setDefaultValue() y QCommandLineOption::setDefaultValues().

QStringList QCommandLineParser::values(const QString &optionName) const

Devuelve una lista con los valores de la opción especificada optionName, o una lista vacía si no se encuentra.

El nombre proporcionado puede ser cualquier nombre largo o corto de cualquier opción que se haya añadido con addOption(). Todos los nombres de opciones se consideran equivalentes. Si no se reconoce el nombre o si esa opción no estaba presente, se devuelve una lista vacía.

En el caso de las opciones encontradas por el analizador, la lista contendrá una entrada por cada vez que el analizador haya detectado la opción. Si la opción no se ha especificado en la línea de comandos, se devuelven los valores por defecto.

Se devuelve una lista vacía si la opción no admite ningún valor.

Véase también value(), QCommandLineOption::setDefaultValue() y QCommandLineOption::setDefaultValues().

QStringList QCommandLineParser::values(const QCommandLineOption &option) const

Devuelve una lista con los valores de las opciones encontradas para el ` option` indicado, o una lista vacía si no se encuentra ninguna.

En el caso de las opciones detectadas por el analizador, la lista contendrá una entrada por cada vez que el analizador haya encontrado la opción. Si la opción no se ha especificado en la línea de comandos, se devuelven los valores por defecto.

Se devuelve una lista vacía si la opción no admite ningún valor.

Esta es una función sobrecargada.

Véanse también value(), QCommandLineOption::setDefaultValue() y QCommandLineOption::setDefaultValues().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.