QCommandLineParser Class

Documentación de las funciones miembro

QCommandLineParser::QCommandLineParser()

Construye un objeto analizador de línea de comandos.

[noexcept] QCommandLineParser::~QCommandLineParser()

Destruye el objeto analizador de línea de comandos.

QCommandLineOption QCommandLineParser::addHelpOption()

Añade opciones de ayuda al analizador sintáctico 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 extiende esto para incluir opciones genéricas de Qt, no definidas por este comando, en la salida.

Estas opciones son manejadas automáticamente por QCommandLineParser.

Recuerde 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 puede utilizarse para llamar a isSet().

bool QCommandLineParser::addOption(const QCommandLineOption &option)

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

Devuelve true si la opción se ha añadido correctamente; en caso contrario, devuelve false.

La adición de la opción falla si no hay ningún nombre asociado a la opción, o si la opción tiene un nombre que no coincide con el nombre de una opción añadida anteriormente.

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

Añade las opciones a buscar durante el análisis sintáctico. 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 cuándo 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, en beneficio del texto de ayuda.

Los argumentos name y description aparecerán bajo la sección Arguments: de la ayuda. Si se especifica syntax, se añadirá a la línea de uso; en caso 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 es gestionada automáticamente por QCommandLineParser.

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

Devuelve la instancia de la opción, que puede utilizarse 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()

Borra las definiciones de argumentos adicionales del texto de ayuda.

Esto sólo es necesario para el caso especial de las herramientas que admiten varios comandos con diferentes opciones. Una vez que se ha identificado el comando real, se pueden definir las opciones para este comando, y el texto de ayuda para el comando se puede ajustar en consecuencia.

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. Sólo debe invocarse cuando parse() devuelve false.

QString QCommandLineParser::helpText() const

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

Véase también showHelp().

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

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

Devuelve true si la opción name fue establecida, false en caso contrario.

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 tratan como equivalentes. Si el nombre no es reconocido o esa opción no estaba presente, se devuelve false.

Ejemplo:

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

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

Comprueba si option se ha pasado a la aplicación.

Devuelve true si se estableció option, false en caso contrario.

Esta es la forma recomendada de comprobar las opciones sin valores.

Ejemplo:

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

QStringList QCommandLineParser::optionNames() const

Devuelve una lista de los nombres de opciones encontrados.

Devuelve una lista de todos los nombres de opciones reconocidos encontrados por el analizador sintáctico, en el orden en que fueron encontrados. Para las opciones largas que tenían la forma {-opción=valor}, se habrá eliminado la parte del valor.

Los nombres de esta lista no incluyen los guiones anteriores. 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.

Cualquier entrada de la lista puede utilizarse con value() o con values() para obtener cualquier valor de opción relevante.

bool QCommandLineParser::parse(const QStringList &arguments)

Analiza la línea de comandos arguments.

La mayoría de los programas no necesitan llamar a esto, una simple llamada a process() es suficiente.

parse() es más de bajo nivel, y sólo hace el análisis sintáctico. La aplicación tendrá que encargarse de la gestión de errores, utilizando errorText() si parse() devuelve false. Esto puede ser útil, por ejemplo, para mostrar un mensaje gráfico de error en programas gráficos.

Llamar a parse() en lugar de a process() también puede ser útil para ignorar opciones desconocidas temporalmente, 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 olvide que arguments debe comenzar con el nombre del ejecutable (aunque se ignora).

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

Véase también process().

QStringList QCommandLineParser::positionalArguments() const

Devuelve una lista de argumentos posicionales.

Estos son todos los argumentos que no fueron reconocidos 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 los errores.

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

Cuando se invoca una de estas opciones, o cuando se produce un error (por ejemplo, se pasó una opción desconocida), el proceso actual se detendrá, utilizando 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 QCoreApplication app .

void QCommandLineParser::setApplicationDescription(const QString &description)

Establece la aplicación description mostrada por helpText().

Véase también applicationDescription().

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

Establece el modo de análisis sintáctico en parsingMode. Debe invocarse antes de process() o parse().

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

Establece el modo de análisis sintáctico en singleDashWordOptionMode. Debe invocarse antes de process() o parse().

void QCommandLineParser::showHelp(int exitCode = 0)

Muestra la información de ayuda y sale de 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 invoca la aplicación correctamente. El código de salida se establece en exitCode. Debe establecerse en 0 si el usuario solicitó ver la ayuda, y en cualquier otro valor en caso de error.

Véase 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 sale de la aplicación con el exitCode dado.

El message normalmente se imprimirá directamente en stdout o stderr de acuerdo con el type dado , o el mensaje puede mostrarse en un cuadro de mensaje bajo Windows cuando sea necesario, con un icono de información o un icono de error de acuerdo con el type dado (establezca la variable de entorno QT_COMMAND_LINE_PARSER_NO_GUI_MESSAGE_BOXES si no desea el cuadro de mensaje).

Es el mismo método de visualización de mensajes utilizado por showHelp, showVersion y las opciones incorporadas (--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.

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

void QCommandLineParser::showVersion()

Muestra la información de la versión de QCoreApplication::applicationVersion(), y sale de la aplicación. Esto se activa automáticamente con la opción -version, pero también puede utilizarse para mostrar la versión cuando no se utiliza process(). El código de salida es 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 de nombre largo como las de nombre corto que no hayan sido reconocidas. Para las opciones largas que tenían la forma {-opción=valor}, la parte del valor se habrá eliminado y sólo se añadirá el nombre largo.

Los nombres de esta lista no incluyen los guiones anteriores. 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 opción encontrado para el nombre de opción dado 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 opción se tratan como equivalentes. Si no se reconoce el nombre o la opción no estaba presente, se devuelve una cadena vacía.

Para las opciones encontradas por el analizador sintáctico, se devuelve el último valor encontrado para esa opción. Si la opción no se especificó en la línea de órdenes, se devuelve el valor por defecto.

Si la opción no tiene valor, se imprime 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 opción encontrado para la dirección option, o una cadena vacía si no se encuentra.

Para las opciones encontradas por el analizador sintáctico, se devuelve el último valor encontrado para esa opción. Si la opción no se especificó en la línea de comandos, se devuelve el valor por defecto.

Si la opción no tiene valor, se devuelve una cadena vacía.

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

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

Devuelve una lista de valores de opción encontrados para el nombre de opción dado optionName, o una lista vacía si no se encuentran.

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 tratan como equivalentes. Si no se reconoce el nombre o esa opción no estaba presente, se devuelve una lista vacía.

Para las opciones encontradas por el analizador sintáctico, la lista contendrá una entrada por cada vez que el analizador haya encontrado la opción. Si la opción no se especificó en la línea de órdenes, se devuelven los valores por defecto.

Si la opción no tiene valor, se devuelve una lista vacía.

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

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

Devuelve una lista de los valores de opción encontrados para option, o una lista vacía si no se encuentran.

Para las opciones encontradas 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 especificó en la línea de comandos, se devolverán los valores por defecto.

Si la opción no tiene valor, se devuelve una lista vacía.

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