QCommandLineParser Class

Documentation des fonctions membres

QCommandLineParser::QCommandLineParser()

Crée un objet 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 ligne de commande.

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

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

N'oubliez pas d'utiliser setApplicationDescription() pour définir la description de l'application, qui s'affichera lorsque cette option sera 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 » à prendre en compte 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 associé à l'option, ou si le nom de l'option entre en conflit avec celui d'une option ajoutée précédemment.

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`.

Consultez la documentation relative à la fonction ` addOption()` pour savoir dans quels cas 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, à des fins d'aide.

Les arguments name et description apparaîtront dans la section « Arguments: » de l'aide. Si syntax est spécifié, il sera ajouté à la ligne « Usage » ; sinon, c'est name qui 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 également 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 réelle à l’aide de 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 la fonction setApplicationDescription().

Voir également la fonction setApplicationDescription().

void QCommandLineParser::clearPositionalArguments()

Supprime 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 prenant en charge plusieurs commandes avec différentes options. Une fois la commande effective identifiée, les options de cette commande peuvent être définies et le texte d'aide correspondant peut être adapté 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 destiné à 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 toutes les informations d'aide.

Voir aussi showHelp().

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

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

Renvoie « true » si l'option « name » a été définie, « false » dans le cas contraire.

Le nom fourni peut être n'importe quel nom long ou court d'une option ajoutée à l'aide de la fonction ` addOption()`. Tous les noms d'options sont considérés comme équivalents. Si le nom n'est pas reconnu ou si l'option n'existe pas, la fonction renvoie `false`.

Exemple :

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

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

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

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

C'est la méthode recommandée pour vérifier la présence d'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 qui ont été détectés.

Cette fonction renvoie une liste de tous les noms d’options reconnus par l’analyseur syntaxique, dans l’ordre où ils ont été trouvés. Pour toutes les options longues de la forme {–option=valeur}, la partie « valeur » aura été supprimée.

Les noms de cette liste ne comprennent pas les tirets qui les précèdent. Un nom peut apparaître plusieurs fois dans cette liste s’il a été rencontré plusieurs fois par l’analyseur syntaxique.

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

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.

La fonction `parse()` est de niveau plus bas et se contente d’effectuer l’analyse. L’application devra se charger de la gestion des erreurs, en utilisant ` errorText()` si `parse()` renvoie ` false`. Cela peut s’avérer utile, par exemple, pour afficher un message d’erreur graphique dans les programmes graphiques.

Appeler parse() au lieu de process() peut également s’avérer utile pour ignorer temporairement des options inconnues, car d’autres définitions d’options seront fournies ultérieurement (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 (qui est toutefois ignoré).

Renvoie false en cas d’erreur d’analyse (option inconnue ou valeur manquante) ; renvoie true dans le cas contraire.

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.

Outre l'analyse des options (comme parse()), cette fonction gère également les options intégrées et traite les erreurs.

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

Lorsqu'une de ces options est invoquée, ou lorsqu'une erreur se produit (par exemple, si une option inconnue a été passée), le processus en cours s'arrête alors à l'aide de la fonction exit().

Voir également QCoreApplication::arguments() et parse().

void QCommandLineParser::process(const QCoreApplication &app)

La ligne de commande est fournie par l'instance « QCoreApplication » app.

void QCommandLineParser::setApplicationDescription(const QString &description)

Définit l'description de l'application affichée par la fonction helpText().

Voir également applicationDescription().

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

Définit le mode d'analyse sur « parsingMode ». Cette fonction doit être appelée avant « process()» ou « parse()».

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

Définit le mode d'analyse sur « singleDashWordOptionMode ». Cette fonction doit être appelée avant process() ou parse().

void QCommandLineParser::showHelp(int exitCode = 0)

Affiche les informations d'aide et quitte l'application. Cette commande est automatiquement déclenchée par l'option –help, mais peut également être utilisée pour afficher l'aide lorsque l'utilisateur n'a pas lancé l'application correctement. Le code de sortie est défini sur exitCode. Il doit être défini sur 0 si l'utilisateur a demandé à consulter l'aide, et sur 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 une « message » et quitte l'application avec l'exitCode spécifiée.

Le message « message » est généralement affiché directement sur « stdout » ou « stderr » selon la valeur de « type » fournie ; il peut également s’afficher dans une boîte de message sous Windows si nécessaire, accompagné d’une icône d’information ou d’erreur selon la valeur de « type » fournie (définissez la variable d’environnement « QT_COMMAND_LINE_PARSER_NO_GUI_MESSAGE_BOXES » si vous ne souhaitez pas que la boîte de message s’affiche).

Il s'agit de la même méthode d'affichage des messages 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 également addVersionOption(), showHelp(), showVersion() et QCommandLineParser::MessageType.

void QCommandLineParser::showVersion()

Affiche les informations de version à partir de la commande ` QCoreApplication::applicationVersion()` et quitte l'application. Cette fonction est automatiquement déclenchée par l'option `–version`, mais peut également être utilisée pour afficher la version lorsque la commande ` process()` n'est pas utilisée. Le code de sortie est défini sur `EXIT_SUCCESS` (0).

Voir également addVersionOption().

QStringList QCommandLineParser::unknownOptionNames() const

Renvoie une liste des noms d'options inconnus.

Cette liste comprendra à la fois les options à nom long et à nom court qui n’ont pas été reconnues. Pour toute option à nom long se présentant sous la forme {–option=valeur}, la partie « valeur » aura été supprimée et seul le nom long sera ajouté.

Les noms de cette liste ne comportent pas le tiret qui les précède. Un nom peut apparaître plusieurs fois dans cette liste s’il a été rencontré plusieurs fois par l’analyseur syntaxique.

Voir également optionNames().

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

Renvoie la valeur de l'option correspondant au nom d'option fourni optionName, ou une chaîne vide si celle-ci n'est pas trouvée.

Le nom fourni peut être n'importe quel nom long ou court d'une option ajoutée à l'aide de la fonction addOption(). Tous les noms d'options sont considérés comme équivalents. Si le nom n'est pas reconnu ou si l'option n'existe pas, une chaîne vide est renvoyée.

Pour les options détecté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 également values(), QCommandLineOption::setDefaultValue() et QCommandLineOption::setDefaultValues().

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

Renvoie la valeur de l'option trouvée pour l'option on donnée, ou une chaîne vide si elle n'est pas trouvée.

Pour les options détecté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 également values(), QCommandLineOption::setDefaultValue() et QCommandLineOption::setDefaultValues().

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

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

Le nom fourni peut être n'importe quel nom long ou court d'une option ayant é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'existe pas, une liste vide est renvoyée.

Pour les options détectées par l'analyseur, la liste contiendra une entrée pour chaque occurrence de l'option détecté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 également value(), QCommandLineOption::setDefaultValue() et QCommandLineOption::setDefaultValues().

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

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

Pour les options détectées par l'analyseur, la liste contiendra une entrée pour chaque occurrence de l'option détecté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 également value(), QCommandLineOption::setDefaultValue() et QCommandLineOption::setDefaultValues().