Anzeigen von Nutzungskommentaren in Funktionen, die interaktiv verwendet werden sollen

11

Ich habe eine Reihe von Funktionen in meinem .bashrcdefiniert, die interaktiv in einem Terminal verwendet werden sollen. Ich habe ihnen im Allgemeinen einen Kommentar vorangestellt, in dem die beabsichtigte Verwendung beschrieben wird:

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

Dies ist in Ordnung, wenn Sie den Quellcode durchsuchen, aber es ist schön, typeim Terminal ausgeführt zu werden, um eine schnelle Erinnerung an die Funktionsweise der Funktion zu erhalten. Dies beinhaltet jedoch (verständlicherweise) keine Kommentare:

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

Was mich zum Nachdenken brachte: "Wäre es nicht schön, wenn diese Art von Kommentaren fortbestehen würde, damit typesie angezeigt werden könnten?" Und im Geiste von Pythons Docstrings habe ich mir Folgendes ausgedacht :

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";
    ...
}

Jetzt ist die Nutzung direkt in der enthalten type Ausgabe enthalten! Wie Sie sehen, wird das Zitieren natürlich zu einem Problem, das fehleranfällig sein kann, aber es ist eine schönere Benutzererfahrung, wenn es funktioniert.

Meine Frage ist also, ist das eine schreckliche Idee? Gibt es bessere Alternativen (wie ein man/ infofür Funktionen), um Benutzern von Bash-Funktionen zusätzlichen Kontext bereitzustellen?

Idealerweise möchte ich immer noch, dass sich die Gebrauchsanweisungen in der Nähe der Funktionsdefinition befinden, damit die Benutzer des Quellcodes ebenfalls den Vorteil erhalten. Wenn es jedoch einen "richtigen" Weg gibt, bin ich offen für Alternativen.

Bearbeiten Sie diese sind alles ziemlich einfache Funktionen im Helfer-Stil und ich möchte nur interaktiv einen zusätzlichen Kontext erhalten. Sicherlich würde ich für komplexere Skripte, die Flags analysieren, eine --helpOption hinzufügen , aber für diese wäre es etwas mühsam, allen Hilfe-Flags hinzuzufügen. Vielleicht ist das nur ein Preis, den ich akzeptieren sollte, aber dieser :Hack scheint ziemlich gut zu funktionieren, ohne dass die Quelle viel schwieriger zu lesen ist.

dimo414
quelle

Antworten:

8

Ich glaube nicht, dass es nur einen guten Weg gibt, dies zu tun.

Viele Funktionen, Skripte und andere ausführbare Dateien bieten eine Hilfemeldung, wenn der Benutzer -hoder --helpals Option Folgendes bereitstellt :

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

Beispielsweise:

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

$ foo --help
Usage: foo [bar]
Foo's a bar into a baz
John1024
quelle
Ja, das hätte ich erwähnen sollen. Dies sind einfache Funktionen, und ich versuche zu vermeiden, dass sie zu komplex werden. Für Befehle, die Parsing-Flags verdienen, würde ich sicherlich eine --helpOption hinzufügen .
dimo414
Bei der Programmierung ist Konsistenz eine Tugend. Es kommt auch darauf an, was Sie unter "komplex" verstehen.
John1024
Und Ihr Ansatz ist klug und gut (und Ihre Frage hat bereits meine +1).
John1024
1
Vielen Dank; Ihre Implementierung von --helpist auch nicht invasiv, was meiner Meinung nach in diesem Fall mein Hauptkriterium ist. Möglicherweise verwende ich den :Trick, da er direkter zu meinem Anwendungsfall passt, aber ich schätze es, dass Sie darauf hinweisen, dass es nicht schwer zu unterstützen ist --helpund dass die meisten Benutzer ihn erwarten werden.
dimo414
1
+1. Ich wollte antworten "benutze getopts", aber das funktioniert gut genug, wenn es keine anderen Optionen gibt. Wenn die Funktion andere Optionen hat, verwenden Sie getopts.
Cas