CLIs für Fox-Entwickler (4): Hilfe lesen und schreiben

Vierter Teil eines Kommandozeilen-Kurses für alle, die in Visual FoxPro programmieren: wie man ein Konsolenprogramm nach seiner Hilfe fragt, wie man ihre Notation liest (dieselbe wie in der VFP-Hilfe), Ausgaben für Maschinen und was in der Hilfe eines eigenen Programms stehen sollte.

Ein Konsolenprogramm hat keine Menüs, durch die Sie blättern könnten, um zu sehen, was es kann. Was es hat, ist seine Hilfe: ein Text, den es Ihnen zeigt, wenn Sie danach fragen. In diesem Teil sehen wir, wie man danach fragt, wie man sie liest und was in der Hilfe eines eigenen Programms stehen sollte.

Lesen können Sie sie schon, auch wenn es nicht so scheint. Die VFP-Hilfe erklärt jeden Befehl mit eckigen Klammern und senkrechten Strichen, und die Hilfen der Konsole benutzen dieselbe Notation.

Wie man danach fragt

Es gibt nicht nur einen Weg, es hängt von der Familie des Programms ab:

/? bei den klassischen Windows-Programmen: ping /?, dir /?, tasklist /?.
-h oder --help bei fast allem anderen: git log -h.
Ohne Argumente. Viele Programme zeigen, wie sie benutzt werden, wenn man ihnen nicht gibt, was sie brauchen. ping allein gibt seine Verwendungszeile aus.

Wenn Sie nicht wissen, was Sie nehmen sollen, probieren Sie es in dieser Reihenfolge: --help, -h und /?.

Und fast alle haben auch --version, das sagt, welche Version Sie installiert haben. Danach wird man als Erstes gefragt, wenn etwas nicht funktioniert:

git --version

git version 2.54.0.windows.1

Wie man sie liest

Das ist die Verwendungszeile von ping /? (auf meinem spanischen Windows; nombre_destino heißt „Zielname“):

Uso: ping [-t] [-a] [-n count] [-l size] [-f] [-i TTL] [-v TOS]
          [-r count] [-s count] [[-j host-list] | [-k host-list]]
          [-w timeout] [-R] [-S srcaddr] [-c compartment] [-p]
          [-4] [-6] nombre_destino

Das sieht nach viel aus, aber mit vier Zeichen liest man es ganz. Es sind dieselben, die die VFP-Hilfe benutzt, zum Beispiel bei USE (vereinfacht):

USE [TableName] [IN nWorkArea | cTableAlias] [AGAIN] [ALIAS cTableAlias] [EXCLUSIVE] [SHARED]

Zeichen	Bedeutet	Bei `ping`
keine Klammern	Pflicht	`nombre_destino`: Sie müssen sagen, wen Sie anpingen
`[ ]`	optional	`[-t]`: kann man angeben oder nicht
Wort nach einer Option	der Wert, den Sie einsetzen	`-n count`: `count` ist eine Zahl, eine beliebige
`a \| b`	das eine oder das andere, nicht beides	`[-j host-list] \| [-k host-list]`

[-t] ist ein optionaler Schalter. [-n count] ist eine optionale Option mit Wert. nombre_destino steht ohne Klammern und am Ende: Es ist das Pflicht-Positionsargument. Das ist dasselbe wie [IN nWorkArea | cTableAlias] bei USE: IN kann wegfallen, und wenn es dasteht, wird der Arbeitsbereich per Nummer oder per Alias angegeben, nicht mit beidem.

Zwei weitere Zeichen sehen Sie oft:

< > um ein Wort bedeutet „hier kommt ein Wert hin“. Das ist eine andere Schreibweise für das, was count in der ping-Zeile ist.
... nach etwas bedeutet, dass es sich wiederholen lässt.

Die Verwendungszeile von git log -h hat beide:

usage: git log [<options>] [<revision-range>] [[--] <path>...]

Alles ist optional. <path>... sind eine oder mehrere Dateien, und [--], der doppelte Bindestrich aus Teil 2, darf davorstehen. Klammern lassen sich verschachteln: [[--] <path>...] heißt, dass Sie die Dateien weglassen können, und wenn Sie sie angeben, bleibt das -- trotzdem optional.

Unter der Verwendungszeile kommt die Liste der Optionen, eine pro Zeile, mit dem, was jede tut. Die von ping beginnt so (bei mir auf Spanisch):

Opciones:
 -t                  Hacer ping al host especificado hasta que se detenga.
                     Para ver estadísticas y continuar, presione
                     Ctrl-Interrumpir; para detener, presione Ctrl+C.
 -a                  Resolver direcciones en nombres de host.
 -n count            Número de solicitudes de eco para enviar.

Und viele Hilfen enden mit Beispielen. Die von tasklist /? gehören zum Nützlichsten seiner Hilfe, weil sie Kombinationen zeigen, die funktionieren:

TASKLIST /V /FO CSV
TASKLIST /SVC /FO LIST
TASKLIST /S sistema /FO LIST

Eine Ausgabe für Menschen und eine für Maschinen

In diesen Beispielen taucht /FO auf, das Ausgabeformat. tasklist /? erklärt es so (bei mir auf Spanisch: „Gibt das Ausgabeformat an. Gültige Werte“):

/FO    formato            Especifica el formato de salida.
                          Valores válidos: "TABLE", "LIST", "CSV".

„Gültige Werte“ ist die lange Schreibweise von TABLE | LIST | CSV. Geben Sie etwas anderes an, versucht tasklist es gar nicht erst:

Error: Sintaxis no válida. El valor "xml" no está permitido para la opción "/fo".
Escriba "TASKLIST /?" para su uso.

Die Tabelle ist zum Lesen für Sie. Das CSV ist für ein anderes Programm:

tasklist /fi "imagename eq explorer.exe" /fo csv

"Nombre de imagen","PID","Nombre de sesión","Núm. de sesión","Uso de memoria"
"explorer.exe","8828","Console","1","429.304 KB"

Und ein CSV können Sie aus VFP lesen:

Die Windows-Prozesse in einem VFP-Cursor

RUN tasklist /fi "imagename eq explorer.exe" /fo csv > prozesse.csv
CREATE CURSOR prozesse (abbild C(40), pid I, sitzung C(20), sitznr I, speicher C(20))
APPEND FROM prozesse.csv TYPE CSV
BROWSE

Achtung bei einem Detail: APPEND FROM ... TYPE CSV geht davon aus, dass die erste Zeile die Kopfzeile ist, und überspringt sie. Verlangen Sie von tasklist das CSV ohne Kopfzeile (mit /NH), frisst TYPE CSV Ihren einzigen Datensatz, und der Cursor bleibt leer. Ohne Kopfzeile nehmen Sie TYPE DELIMITED.

Das Maschinenformat, das Ihnen heute am häufigsten begegnet, ist JSON, mit Optionen wie --format json oder --json. Die Idee ist dieselbe: Die normale Ausgabe ist zum Lesen am Bildschirm gedacht, und die für Maschinen ändert sich nicht, auch wenn das Programm sein Aussehen ändert. Um JSON aus VFP zu lesen, braucht man einen Parser wie JSONFox.

Was in der Hilfe eines eigenen Programms stehen sollte

Wenn Sie eines Tages ein Konsolenprogramm schreiben (in Teil 5 starten wir eines aus VFP, und auch eine VFP-.exe kann eines sein), erwartet ein Benutzer Folgendes. Ein Beispiel für ein erfundenes Programm, das Rechnungen per E-Mail verschickt:

rechnungen: verschickt die offenen Rechnungen per E-Mail

Verwendung: rechnungen senden [--von <datum>] [--bis <datum>] [--probe] [--format table|json]

Optionen:
  --von <datum>      Erstes Rechnungsdatum, JJJJ-MM-TT. Standard: heute.
  --bis <datum>      Letztes Rechnungsdatum. Standard: das von --von.
  --probe            Zeigt, was verschickt würde, ohne etwas zu verschicken.
  --format <f>       table (Standard) oder json.
  -h, --help         Diese Hilfe.
  --version          Die Version des Programms.

Beispiele:
  rechnungen senden --probe
  rechnungen senden --von 2026-09-01 --bis 2026-09-30

Exit-Codes:
  0  alles verschickt
  1  eine Rechnung konnte nicht verschickt werden (steht im Fehlerkanal)
  2  die Befehlszeile ist ungültig

Und rund um die Hilfe ein paar Gewohnheiten, über die sich jeder freut:

--help, -h und /? funktionieren bei jedem Unterbefehl, und rechnungen senden --help erklärt nur senden.
Ein Verwendungsfehler sagt, wie man die Hilfe bekommt, wie es tasklist mit „Escriba “TASKLIST /?” para su uso“ („Geben Sie TASKLIST /? ein“) macht, und endet mit einem Code ungleich 0, ohne etwas zu tun.
Die Standardwerte stehen da. „Standard: heute“ erspart eine Frage.
Daten gehen auf die Ausgabe und Meldungen auf den Fehlerkanal (Teil 3), damit das JSON sauber bleibt.
Was sich nicht rückgängig machen lässt, hat einen Probemodus, wie --probe, oder fragt nach einer Bestätigung.

Eine Warnung beim Lesen fremder Hilfen: Die Frage nach der Hilfe endet nicht immer mit Code 0. ping /? und tasklist /? enden mit 0, aber git log -h mit 129, weil Git die Frage nach der Hilfe als falsche Verwendung behandelt. Prüfen Sie in einem Skript nicht über die Hilfe, ob ein Programm installiert ist; dafür gibt es --version.

Zum Üben

Das ist die Verwendungszeile von where /? (patrón ist Spanisch für „Muster“):

WHERE [/R dir] [/Q] [/F] [/T] patrón...

Beantworten Sie, bevor Sie etwas ausprobieren: Was ist Pflicht? Welche Option hat einen Wert? Wie viele Muster können Sie angeben? Dann prüfen Sie es:

where /?
where notepad
where notepad calc
where /r C:\Windows\System32 ping.exe
tasklist /fo list /fi "imagename eq explorer.exe"
tasklist /fo xml

Im letzten Teil, Nummer 5, bringen wir alles in VFP zusammen: ein Konsolenprogramm starten, auf sein Ende warten oder nicht, einsammeln, was es auf jeden Kanal schreibt, und seinen Exit-Code lesen.