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.
| Constante | Valor | Descripción |
|---|---|---|
QCommandLineParser::MessageType::Information | 0 | Se utiliza para mostrar mensajes informativos. El mensaje se mostrará en stdout. |
QCommandLineParser::MessageType::Error | 1 | Se 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.
| Constante | Valor | Descripción |
|---|---|---|
QCommandLineParser::ParseAsOptions | 0 | application 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::ParseAsPositionalArguments | 1 | application 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 ».
| Constante | Valor | Descripción |
|---|---|---|
QCommandLineParser::ParseAsCompactedShortOptions | 0 | -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::ParseAsLongOptions | 1 | -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.