pflag
1.0.5
pflag est un remplacement instantané du package flag de Go, implémentant --flags de style POSIX/GNU.
pflag est compatible avec les extensions GNU des recommandations POSIX pour les options de ligne de commande. Pour une description plus précise, consultez la section « Syntaxe des indicateurs de ligne de commande » ci-dessous.
pflag est disponible sous le même style de licence BSD que le langage Go, qui se trouve dans le fichier LICENSE.
pflag est disponible à l'aide de la commande standard go get .
Installez en exécutant :
go get github.com/spf13/pflag
Exécutez des tests en exécutant :
go test github.com/spf13/pflag
pflag est un remplacement instantané du package de drapeaux natif de Go. Si vous importez pflag sous le nom "flag", alors tout le code devrait continuer à fonctionner sans changement.
import flag "github.com/spf13/pflag"Il y a une exception à cela : si vous instanciez directement la structure Flag, il y a un champ "Shorthand" supplémentaire que vous devrez définir. La plupart du code n'instancie jamais directement cette structure et utilise à la place des fonctions telles que String(), BoolVar() et Var(), et n'est donc pas affecté.
Définissez des indicateurs en utilisant flag.String(), Bool(), Int(), etc.
Ceci déclare un indicateur entier, -flagname, stocké dans l'adresse IP du pointeur, de type *int.
var ip * int = flag . Int ( "flagname" , 1234 , "help message for flagname" )Si vous le souhaitez, vous pouvez lier le drapeau à une variable en utilisant les fonctions Var().
var flagvar int
func init () {
flag . IntVar ( & flagvar , "flagname" , 1234 , "help message for flagname" )
}Ou vous pouvez créer des indicateurs personnalisés qui satisfont à l'interface Value (avec des récepteurs de pointeurs) et les coupler à l'analyse des indicateurs par
flag . Var ( & flagVal , "name" , "help message for flagname" )Pour de tels indicateurs, la valeur par défaut est simplement la valeur initiale de la variable.
Une fois tous les indicateurs définis, appelez
flag . Parse ()pour analyser la ligne de commande dans les indicateurs définis.
Les drapeaux peuvent alors être utilisés directement. Si vous utilisez les drapeaux eux-mêmes, ce sont tous des pointeurs ; si vous liez à des variables, ce sont des valeurs.
fmt . Println ( "ip has value " , * ip )
fmt . Println ( "flagvar has value " , flagvar )Il existe des fonctions d'assistance disponibles pour obtenir la valeur stockée dans un Flag si vous avez un FlagSet mais que vous avez du mal à suivre tous les pointeurs de votre code. Si vous avez un pflag.FlagSet avec un indicateur appelé 'flagname' de type int, vous pouvez utiliser GetInt() pour obtenir la valeur int. Mais notez que 'flagname' doit exister et qu'il doit s'agir d'un entier. GetString("flagname") échouera.
i , err := flagset . GetInt ( "flagname" )Après l'analyse, les arguments après le drapeau sont disponibles sous forme de tranche flag.Args() ou individuellement sous forme de flag.Arg(i). Les arguments sont indexés de 0 à flag.NArg()-1.
Le package pflag définit également de nouvelles fonctions qui ne sont pas dans flag, qui donnent des raccourcis à une lettre pour les drapeaux. Vous pouvez les utiliser en ajoutant « P » au nom de toute fonction qui définit un indicateur.
var ip = flag . IntP ( "flagname" , "f" , 1234 , "help message" )
var flagvar bool
func init () {
flag . BoolVarP ( & flagvar , "boolname" , "b" , true , "help message" )
}
flag . VarP ( & flagVal , "varname" , "v" , "help message" )Les lettres abrégées peuvent être utilisées avec des tirets simples sur la ligne de commande. Les drapeaux booléens raccourcis peuvent être combinés avec d’autres drapeaux raccourcis.
L'ensemble par défaut d'indicateurs de ligne de commande est contrôlé par des fonctions de niveau supérieur. Le type FlagSet permet de définir des ensembles indépendants d'indicateurs, par exemple pour implémenter des sous-commandes dans une interface de ligne de commande. Les méthodes de FlagSet sont analogues aux fonctions de niveau supérieur pour le jeu d'indicateurs de ligne de commande.
Après avoir créé un indicateur, il est possible de définir pflag.NoOptDefVal pour l'indicateur donné. Cela modifie légèrement la signification du drapeau. Si un indicateur a un NoOptDefVal et que l'indicateur est défini sur la ligne de commande sans option, l'indicateur sera défini sur NoOptDefVal. Par exemple donné :
var ip = flag . IntP ( "flagname" , "f" , 1234 , "help message" )
flag . Lookup ( "flagname" ). NoOptDefVal = "4321"Cela donnerait quelque chose comme
| Arguments analysés | Valeur résultante |
|---|---|
| --nom du drapeau = 1357 | IP = 1357 |
| --nom du drapeau | IP = 4321 |
| [rien] | IP = 1234 |
--flag // boolean flags, or flags with no option default values
--flag x // only on flags without a default value
--flag=x
Contrairement au package flag, un simple tiret avant une option signifie quelque chose de différent d’un double tiret. Les tirets simples signifient une série de lettres abrégées pour les drapeaux. Toutes les lettres abrégées, sauf la dernière, doivent être des indicateurs booléens ou un indicateur avec une valeur par défaut.
// boolean or flags where the 'no option default value' is set
-f
-f=true
-abc
but
-b true is INVALID
// non-boolean and flags without a 'no option default value'
-n 1234
-n=1234
-n1234
// mixed
-abcs "hello"
-absd="hello"
-abcs1234
L'analyse des indicateurs s'arrête après le terminateur "--". Contrairement au package flag, les flags peuvent être entrecoupés d'arguments n'importe où sur la ligne de commande avant ce terminateur.
Les indicateurs entiers acceptent 1234, 0664, 0x1234 et peuvent être négatifs. Les indicateurs booléens (sous leur forme longue) acceptent 1, 0, t, f, true, false, TRUE, FALSE, True, False. Les indicateurs de durée acceptent toute entrée valide pour time.ParseDuration.
Il est possible de définir un nom d'indicateur personnalisé « fonction de normalisation ». Il permet aux noms d'indicateurs d'être mutés à la fois lorsqu'ils sont créés dans le code et lorsqu'ils sont utilisés sur la ligne de commande vers une forme « normalisée ». La forme « normalisée » est utilisée à des fins de comparaison. Deux exemples d'utilisation de la fonction de normalisation personnalisée suivent.
Exemple n°1 : Vous voulez -, _ et . dans les drapeaux pour comparer la même chose. autrement dit --my-flag == --my_flag == --my.flag
func wordSepNormalizeFunc ( f * pflag. FlagSet , name string ) pflag. NormalizedName {
from := [] string { "-" , "_" }
to := "."
for _ , sep := range from {
name = strings . Replace ( name , sep , to , - 1 )
}
return pflag . NormalizedName ( name )
}
myFlagSet . SetNormalizeFunc ( wordSepNormalizeFunc )Exemple n°2 : Vous souhaitez créer un alias pour deux drapeaux. autrement dit --old-flag-name == --new-flag-name
func aliasNormalizeFunc ( f * pflag. FlagSet , name string ) pflag. NormalizedName {
switch name {
case "old-flag-name" :
name = "new-flag-name"
break
}
return pflag . NormalizedName ( name )
}
myFlagSet . SetNormalizeFunc ( aliasNormalizeFunc )Il est possible de déprécier un drapeau, ou simplement son raccourci. La dépréciation d'un indicateur/d'un raccourci le masque du texte d'aide et imprime un message d'utilisation lorsque l'indicateur/le raccourci obsolète est utilisé.
Exemple n°1 : Vous souhaitez rendre obsolète un indicateur nommé "badflag" et informer les utilisateurs quel indicateur ils doivent utiliser à la place.
// deprecate a flag by specifying its name and a usage message
flags . MarkDeprecated ( "badflag" , "please use --good-flag instead" ) Cela masque "badflag" du texte d'aide et affiche Flag --badflag has been deprecated, please use --good-flag instead lorsque "badflag" est utilisé.
Exemple n°2 : Vous souhaitez conserver un nom de drapeau "noshorthandflag" mais déprécier son nom court "n".
// deprecate a flag shorthand by specifying its flag name and a usage message
flags . MarkShorthandDeprecated ( "noshorthandflag" , "please use --noshorthandflag only" ) Cela masque le nom abrégé "n" du texte d'aide et imprime Flag shorthand -n has been deprecated, please use --noshorthandflag only lorsque le raccourci "n" est utilisé.
Notez que le message d'utilisation est essentiel ici et qu'il ne doit pas être vide.
Il est possible de marquer un indicateur comme masqué, ce qui signifie qu'il fonctionnera toujours normalement, mais n'apparaîtra pas dans le texte d'utilisation/d'aide.
Exemple : Vous disposez d'un indicateur nommé "secretFlag" dont vous avez besoin pour un usage interne uniquement et vous ne souhaitez pas qu'il apparaisse dans le texte d'aide, ni que son texte d'utilisation soit disponible.
// hide a flag by specifying its name
flags . MarkHidden ( "secretFlag" ) pflag vous permet de désactiver le tri des indicateurs pour l'aide et les messages d'utilisation.
Exemple :
flags . BoolP ( "verbose" , "v" , false , "verbose output" )
flags . String ( "coolflag" , "yeaah" , "it's really cool flag" )
flags . Int ( "usefulflag" , 777 , "sometimes it's very useful" )
flags . SortFlags = false
flags . PrintDefaults ()Sortir :
-v, --verbose verbose output
--coolflag string it's really cool flag (default "yeaah")
--usefulflag int sometimes it's very useful (default 777)
Afin de prendre en charge les indicateurs définis à l'aide du package flag de Go, ils doivent être ajoutés au jeu d'indicateurs pflag . Ceci est généralement nécessaire pour prendre en charge les indicateurs définis par des dépendances tierces (par exemple golang/glog ).
Exemple : Vous souhaitez ajouter les drapeaux Go au jeu de drapeaux CommandLine
import (
goflag "flag"
flag "github.com/spf13/pflag"
)
var ip * int = flag . Int ( "flagname" , 1234 , "help message for flagname" )
func main () {
flag . CommandLine . AddGoFlagSet ( goflag . CommandLine )
flag . Parse ()
} Vous pouvez consulter la documentation de référence complète du package pflag sur godoc.org ou via le système de documentation standard de go en exécutant godoc -http=:6060 et en accédant à http://localhost:6060/pkg/github.com/spf13/pflag. après l'installation.
