QCommandLineParser Class

Documentation des fonctions membres

QCommandLineParser::QCommandLineParser()

Construit un objet d'analyseur de ligne de commande.

[noexcept] QCommandLineParser::~QCommandLineParser()

Détruit l'objet analyseur de ligne de commande.

QCommandLineOption QCommandLineParser::addHelpOption()

Ajoute des options d'aide à l'analyseur de la ligne de commande.

Les options spécifiées pour cette ligne de commande sont décrites par -h ou --help. Sous Windows, l'alternative -? est également prise en charge. L'option --help-all permet d'inclure des options génériques de Qt XML, non définies par cette commande, dans la sortie.

Ces options sont gérées automatiquement par QCommandLineParser.

N'oubliez pas d'utiliser setApplicationDescription() pour définir la description de l'application, qui sera affichée lorsque cette option est utilisée.

Exemple :

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);
    // ...
}

Renvoie l'instance de l'option, qui peut être utilisée pour appeler isSet().

bool QCommandLineParser::addOption(const QCommandLineOption &option)

Ajoute l'option option à rechercher lors de l'analyse.

Renvoie true si l'ajout de l'option a réussi ; sinon, renvoie false.

L'ajout de l'option échoue s'il n'y a pas de nom attaché à l'option, ou si l'option a un nom qui entre en conflit avec un nom d'option ajouté auparavant.

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

Ajoute les options à rechercher lors de l'analyse. Les options sont spécifiées par le paramètre options.

Renvoie true si l'ajout de toutes les options a réussi ; sinon, renvoie false.

Voir la documentation de addOption() pour savoir quand cette fonction peut échouer.

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

Définit un argument supplémentaire pour l'application, au profit du texte d'aide.

Les arguments name et description apparaîtront sous la section Arguments: de l'aide. Si syntax est spécifié, il sera ajouté à la ligne d'utilisation, sinon name sera ajouté.

Exemple :

// 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."));

Voir aussi addHelpOption() et helpText().

QCommandLineOption QCommandLineParser::addVersionOption()

Ajoute l'option -v / --version, qui affiche la chaîne de version de l'application.

Cette option est gérée automatiquement par QCommandLineParser.

Vous pouvez définir la chaîne de version actuelle en utilisant QCoreApplication::setApplicationVersion().

Renvoie l'instance de l'option, qui peut être utilisée pour appeler isSet().

QString QCommandLineParser::applicationDescription() const

Renvoie la description de l'application définie dans setApplicationDescription().

Voir aussi setApplicationDescription().

void QCommandLineParser::clearPositionalArguments()

Efface les définitions des arguments supplémentaires du texte d'aide.

Cette opération n'est nécessaire que dans le cas particulier des outils qui prennent en charge plusieurs commandes avec des options différentes. Une fois la commande identifiée, les options de cette commande peuvent être définies et le texte d'aide de la commande peut être ajusté en conséquence.

Exemple :

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

Renvoie un texte d'erreur traduit pour l'utilisateur. Cette fonction ne doit être appelée que lorsque parse() renvoie false.

QString QCommandLineParser::helpText() const

Renvoie une chaîne de caractères contenant les informations d'aide complètes.

Voir aussi showHelp().

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

Vérifie si l'option name a été transmise à l'application.

Retourne true si l'option name a été définie, false sinon.

Le nom fourni peut être n'importe quel nom long ou court d'une option qui a été ajoutée avec addOption(). Tous les noms d'options sont considérés comme équivalents. Si le nom n'est pas reconnu ou si l'option n'était pas présente, false est renvoyé.

Exemple :

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

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

Vérifie si l'adresse option a été transmise à l'application.

Retourne true si l'option option a été définie, false dans le cas contraire.

C'est la méthode recommandée pour vérifier les options sans valeur.

Exemple :

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

QStringList QCommandLineParser::optionNames() const

Renvoie une liste des noms d'options trouvés.

Ceci renvoie une liste de tous les noms d'options reconnus par l'analyseur, dans l'ordre dans lequel ils ont été trouvés. Pour les options longues qui se présentaient sous la forme {-option=valeur}, la partie valeur a été supprimée.

Les noms de cette liste n'incluent pas les tirets qui les précèdent. Les noms peuvent apparaître plus d'une fois dans cette liste s'ils ont été rencontrés plus d'une fois par l'analyseur.

Toute entrée de la liste peut être utilisée avec value() ou avec values() pour obtenir toutes les valeurs d'option pertinentes.

bool QCommandLineParser::parse(const QStringList &arguments)

Analyse la ligne de commande arguments.

La plupart des programmes n'ont pas besoin d'appeler cette fonction, un simple appel à process() suffit.

parse() est plus bas niveau, et ne fait que l'analyse. L'application devra s'occuper de la gestion des erreurs, en utilisant errorText() si parse() renvoie false. Cela peut être utile, par exemple, pour afficher un message d'erreur graphique dans les programmes graphiques.

Appeler parse() au lieu de process() peut également être utile pour ignorer temporairement des options inconnues, car d'autres définitions d'options seront fournies plus tard (en fonction de l'un des arguments), avant d'appeler process().

N'oubliez pas que arguments doit commencer par le nom de l'exécutable (ignoré, cependant).

Retourne false en cas d'erreur d'analyse (option inconnue ou valeur manquante) ; retourne true sinon.

Voir aussi process().

QStringList QCommandLineParser::positionalArguments() const

Renvoie une liste d'arguments positionnels.

Il s'agit de tous les arguments qui n'ont pas été reconnus comme faisant partie d'une option.

void QCommandLineParser::process(const QStringList &arguments)

Traite la ligne de commande arguments.

En plus d'analyser les options (comme parse()), cette fonction gère également les options intégrées et les erreurs.

Les options intégrées sont --version si addVersionOption a été appelé et --help / --help-all si addHelpOption a été appelé.

Lors de l'invocation de l'une de ces options, ou en cas d'erreur (par exemple, une option inconnue a été transmise), le processus en cours s'arrête, à l'aide de la fonction exit().

Voir aussi QCoreApplication::arguments() et parse().

void QCommandLineParser::process(const QCoreApplication &app)

La ligne de commande est obtenue à partir de l'instance QCoreApplication app .

void QCommandLineParser::setApplicationDescription(const QString &description)

Définit l'application description montrée par helpText().

Voir aussi applicationDescription().

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

Définit le mode d'analyse à parsingMode et doit être appelé avant process() ou parse().

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

Définit le mode d'analyse à singleDashWordOptionMode et doit être appelé avant process() ou parse().

void QCommandLineParser::showHelp(int exitCode = 0)

Affiche les informations d'aide et quitte l'application. Cette action est automatiquement déclenchée par l'option -help, mais peut également être utilisée pour afficher l'aide lorsque l'utilisateur n'invoque pas l'application correctement. Le code de sortie est fixé à exitCode. Il doit être fixé à 0 si l'utilisateur a demandé à voir l'aide, et à n'importe quelle autre valeur en cas d'erreur.

Voir également helpText() et showMessageAndExit().

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

Affiche un message message, et quitte l'application avec le message exitCode.

Le message message est généralement imprimé directement à l'adresse stdout ou stderr en fonction de l'adresse type, ou peut être affiché dans une boîte de message sous Windows si nécessaire, avec une icône d'information ou une icône d'erreur en fonction de l'adresse type (définissez la variable d'environnement QT_COMMAND_LINE_PARSER_NO_GUI_MESSAGE_BOXES si vous ne voulez pas de boîte de message).

Il s'agit de la même méthode d'affichage de message que celle utilisée par showHelp, showVersion et les options intégrées (--version si addVersionOption a été appelé et --help / --help-all si addHelpOption a été appelé).

Cette fonction a été introduite dans Qt 6.9.

Voir aussi addVersionOption(), showHelp(), showVersion(), et QCommandLineParser::MessageType.

void QCommandLineParser::showVersion()

Affiche les informations de version provenant de QCoreApplication::applicationVersion(), et quitte l'application. Ceci est automatiquement déclenché par l'option -version, mais peut également être utilisé pour afficher la version lorsque l'on n'utilise pas process(). Le code de sortie est EXIT_SUCCESS (0).

Voir aussi addVersionOption().

QStringList QCommandLineParser::unknownOptionNames() const

Renvoie une liste des noms d'options inconnus.

Cette liste comprend les options à nom long et à nom court qui n'ont pas été reconnues. Pour toutes les options longues qui étaient sous la forme {-option=valeur}, la partie valeur aura été supprimée et seul le nom long aura été ajouté.

Les noms figurant dans cette liste ne comprennent pas les tirets qui les précèdent. Les noms peuvent apparaître plus d'une fois dans cette liste s'ils ont été rencontrés plus d'une fois par l'analyseur.

Voir aussi optionNames().

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

Renvoie la valeur de l'option trouvée pour le nom d'option donné optionName, ou une chaîne vide si elle n'a pas été trouvée.

Le nom fourni peut être n'importe quel nom long ou court d'une option qui a été ajoutée avec addOption(). Tous les noms d'options sont considérés comme équivalents. Si le nom n'est pas reconnu ou si l'option n'est pas présente, une chaîne vide est renvoyée.

Pour les options trouvées par l'analyseur, la dernière valeur trouvée pour cette option est renvoyée. Si l'option n'a pas été spécifiée sur la ligne de commande, la valeur par défaut est renvoyée.

Si l'option ne prend pas de valeur, un avertissement est affiché et une chaîne vide est renvoyée.

Voir aussi values(), QCommandLineOption::setDefaultValue() et QCommandLineOption::setDefaultValues().

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

Renvoie la valeur de l'option trouvée pour l'adresse option, ou une chaîne vide si elle n'a pas été trouvée.

Pour les options trouvées par l'analyseur, la dernière valeur trouvée pour cette option est renvoyée. Si l'option n'a pas été spécifiée sur la ligne de commande, la valeur par défaut est renvoyée.

Une chaîne vide est renvoyée si l'option ne prend pas de valeur.

Voir aussi values(), QCommandLineOption::setDefaultValue() et QCommandLineOption::setDefaultValues().

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

Renvoie une liste des valeurs d'options trouvées pour le nom d'option donné optionName, ou une liste vide si aucune valeur n'a été trouvée.

Le nom fourni peut être n'importe quel nom long ou court d'une option qui a été ajoutée avec addOption(). Tous les noms d'options sont considérés comme équivalents. Si le nom n'est pas reconnu ou si l'option n'est pas présente, une liste vide est renvoyée.

Pour les options trouvées par l'analyseur, la liste contiendra une entrée pour chaque fois que l'option a été rencontrée par l'analyseur. Si l'option n'a pas été spécifiée sur la ligne de commande, les valeurs par défaut sont renvoyées.

Une liste vide est renvoyée si l'option ne prend pas de valeur.

Voir aussi value(), QCommandLineOption::setDefaultValue(), et QCommandLineOption::setDefaultValues().

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

Renvoie une liste des valeurs d'options trouvées pour le site option donné, ou une liste vide si elles n'ont pas été trouvées.

Pour les options trouvées par l'analyseur, la liste contiendra une entrée pour chaque fois que l'option a été rencontrée par l'analyseur. Si l'option n'a pas été spécifiée sur la ligne de commande, les valeurs par défaut sont renvoyées.

Une liste vide est renvoyée si l'option ne prend pas de valeur.

Voir aussi value(), QCommandLineOption::setDefaultValue(), et QCommandLineOption::setDefaultValues().