Affichage des commentaires d'utilisation dans les fonctions destinées à être utilisées de manière interactive


11

J'ai un certain nombre de fonctions définies dans mon .bashrc, destinées à être utilisées de manière interactive dans un terminal. Je les ai généralement précédés d'un commentaire décrivant son utilisation prévue:

# Usage: foo [bar]
# Foo's a bar into a baz
foo() {
  ...
}

C'est bien si vous parcourez le code source, mais il est agréable de l'exécuter typedans le terminal pour obtenir un rappel rapide de ce que fait la fonction. Cependant, cela (naturellement) ne comprend pas de commentaires:

$ type foo
foo is a function
foo ()
{
    ...
}

Ce qui m'a fait penser "ce ne serait pas bien si ce genre de commentaires persistait pour typepouvoir les afficher?" Et dans l'esprit des docstrings de Python, j'ai trouvé ceci:

foo() {
  : Usage: foo [bar]
  : "Foo's a bar into a baz"
  ...
}

$ type foo
foo is a function
foo ()
{
    : Usage: foo [bar];
    : "Foo's a bar into a baz";
    ...
}

Maintenant, l'utilisation est incluse dans la typesortie! Bien sûr, comme vous pouvez le voir, la citation devient un problème qui pourrait être source d'erreurs, mais c'est une expérience utilisateur plus agréable quand cela fonctionne.

Donc ma question est, est-ce une idée terrible? Existe-t-il de meilleures alternatives (comme les fonctions man/ infopour) pour fournir aux utilisateurs des fonctions Bash un contexte supplémentaire?

Idéalement, j'aimerais toujours que les instructions d'utilisation soient situées à proximité de la définition de la fonction afin que les personnes qui consultent le code source bénéficient également de l'avantage, mais s'il existe un moyen "approprié" de le faire, je suis ouvert à des alternatives.

Modifier ce sont toutes des fonctions de style d'assistance assez simples et je cherche juste à obtenir un peu de contexte supplémentaire de manière interactive. Certes, pour les scripts plus complexes qui analysent les indicateurs, j'ajouterais une --helpoption, mais pour ceux-ci, il serait quelque peu fastidieux d'ajouter des indicateurs d'aide à tout. C'est peut-être juste un coût que je devrais accepter, mais ce :hack semble fonctionner assez bien sans rendre la source beaucoup plus difficile à lire notre montage.

Réponses:


8

Je ne pense pas qu'il existe une seule bonne façon de procéder.

De nombreuses fonctions, scripts et autres exécutables fournissent un message d'aide si l'utilisateur fournit -hou --helpen option:

$ foo() {
[[ "$1" =~ (-h|--help) ]] && { cat <<EOF
Usage: foo [bar]
Foo's a bar into a baz
EOF
return;
}
: ...other stuff...
}

Par exemple:

$ foo -h
Usage: foo [bar]
Foo's a bar into a baz

$ foo --help
Usage: foo [bar]
Foo's a bar into a baz

Oui, j'aurais dû le mentionner. Ce sont des fonctions simples et j'essaie d'éviter de les rendre trop complexes. Pour les commandes qui méritent l'analyse des drapeaux, j'ajouterais certainement une --helpoption.
dimo414

En programmation, la cohérence est une vertu. Cela dépend aussi de ce que vous entendez par «complexe».
John1024

Et, votre approche est intelligente et bonne (et votre question a déjà mon +1).
John1024

1
Merci; votre implémentation --helpest également non invasive, ce qui, à mon avis, est mon principal critère dans ce cas. Je pourrais finir par utiliser l' :astuce car elle correspond plus directement à mon cas d'utilisation, mais je vous remercie de souligner qu'il n'est pas difficile à prendre en charge --helpet que la plupart des utilisateurs s'y attendront.
dimo414

1
+1. j'allais répondre "utiliser getopts" mais cela fonctionne assez bien s'il n'y a pas d'autres options. si la fonction a d'autres options, utilisez getopts.
cas
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.