↓Zum Hauptinhalt springen

Befehlszeilenhilfe

·1666 Wörter
Befehlszeile Systemverständnis Shell
Inhaltsverzeichnis

Meine Intention mit diesem Artikel ist es, dabei zu unterstützen Benutzerhandbücher und Hilfetexte für Befehlszeilenprogramme besser zu verstehen. Das Publikum soll in die Lage versetzt werden, schnell zu erfassen, welche Argumente ein Befehlszeilenprogramm unterstützt und in welcher Reihenfolge es die Argumente erwartet.

Dieser Artikel ist Teil der Serie Befehlszeile.

Dieser Artikel nimmt Bezug auf:

Einleitung #

Wenn man beginnt, sich mit Befehlszeilenprogrammen vertraut zu machen, stößt man schnell auf Hilfetexte oder Man-Pages, die die Syntax der unterstützten Befehlszeilenargumente erläutern. Dabei kommen Formeln bzw. Ausdrücke zum Einsatz, die anfänglich etwas kryptisch wirken. In diesem Artikel sollen die üblichen Schreibweisen und die Bedeutung dieser Syntaxausdrücke erklärt werden.

Beispiele für Syntax-Beschreibungen in Hilfetexten:

Usage: find [-H] [-L] [-P] [-Olevel] [-D debugopts] [path...] [expression]

usage: ffmpeg [options] [[infile options] -i infile]... {[outfile options] outfile}...

Usage: magick.exe tool [ {option} | {image} ... ] {output_image}

bench.exe (<flag> | <option>)* <command> ...

Aufruf der Hilfe #

Fast alle Befehlszeilenprogramme unterstützten einen Modus zur direkten Ausgabe von Hilfetexten. Dieser Modus wird je nach Ökosystem oder Tradition mit -h, --help, -? oder /? aufgerufen. Viele Programme unterstützen mehrere dieser Hilfeschalter.

In Unix-ähnlichen Betriebssystemen kann das Handbuch eines Befehlszeilenprogramms auch durch den Befehl man [<topic>] <command> aufgerufen werden1,2. Dabei sind die Hilfeseiten der Programme in neun Themenbereiche <topic> gegliedert. Und für einen gegebenen Befehl <command> lässt sich gezielt das Thema auswählen.

Themen in den Linux-Manuals:

  • 1: Benutzerkommandos
  • 2: Systemaufruf
  • 3: Funktionen der Programmiersprache C
  • 4: Dateiformate
  • 5: Konfigurationsdateien
  • 6: Spiele
  • 7: Diverses
  • 8: Kommandos zur Systemadministration
  • 9: Kernelfunktionen

Als Anwender hat man es am häufigsten mit den Themen 1 und 5 zu tun. Um also das Handbuch für den Befehl find aufzurufen, eignet sich der Befehl man 1 find. Die Beschreibung der Befehlszeilensyntax findet sich dann unter SYNOPSIS.

Syntax #

Zur Beschreibung der unterstützten Befehlszeilenargumente, also der Syntax der Befehlszeile eines Programms, wird ebenfalls eine Syntax benötigt. Man könnte sie Meta-Syntax nennen. Die üblicherweise in Hilfetexten verwendete Meta-Syntax hat ihre Wurzeln in der Backus-Naur-Form (BNF)3. Aber es gibt Variationen in der konkreten Schreibweise. Denn obwohl es für verschiedene Betriebs- und Ökosysteme Leitfäden und Richtlinien für die Syntax von Befehlszeilenargumenten und die Form der Hilfetexte gibt, so gibt es dennoch keinen global anerkannten Standard der die Meta-Syntax für die Hilfetexte fest vorgeben würde.

Die in diesem Artikel beschriebenen Muster beruhen daher auf Beobachtungen aus mehr als 20 Jahren Programmierpraxis. Sie können zwar nicht als präzise Referenz aber wenigstens als Hilfestellung für den Einstieg in die Benutzung von Befehlszeilenprogrammen dienen.

Im Hilfetext eines Befehlszeilenprogramms (das in folgenden Beispielen einfach prog heißen soll) findet sich üblicherweise mindestens eine Zeile wie Usage: prog… welche die unterstützten Argumente beschreibt. Manchmal fehlt auch das vorangestellte Usage:.

Alternativen des Aufrufs #

Wenn in dem Hilfetext eines Befehlszeilenprogramms eine Syntaxzeile mehrfach mit Abweichungen genannt wird, stellt jede Zeile eine alternative Form dar, in der das Programm aufgerufen werden kann.

Usage: prog command [options] {output file}
Usage: prog [options] {output file}
       prog [options] --script {filename} [ {script arguments} ...]
       prog --help | --version | --list {option}

In diesem Beispiel sind vier alternative Formen des Aufrufs möglich.

  1. Der Aufruf eines Unterprogramms command
  2. Der Aufruf ohne Unterprogramm
  3. Der Aufruf mit einem Skript --script {filename}
  4. Der Aufruf von Hilfetexten in drei alternativen Varianten

Platzhalter #

Platzhalter für Optionswerte oder Positionsargumente sind üblicherweise durch die folgenden Schreibweisen erkennbar:

  • Kapitalschrift PARAM_VALUE
  • Geschweifte Klammern {param value}
  • Spitze Klammern <Param Value> (BNF)

Manchmal werden Platzhalter auch ohne jede Kennzeichnung verwendet. Und zwar in der Regel genau dann, wenn Schalter und Optionsschlüsselworte immer durch ein Steuerzeichen, z. B. einen führenden Bindestrich, gekennzeichnet sind. Alle Worte in der Syntax, die dann nicht durch das Steuerzeichen gekennzeichnet sind, sind Platzhalter.

Usage: prog [-v] [-O level] filename

Folglich sind hier level und filename Platzhalter.

Optionale Argumente #

Optionale Argumente oder Gruppen von optionalen Argumenten werden immer in eckigen Klammern dargestellt (BNF).

Usage: prog [-x] [--value VALUE] FILENAME

Hier sind sowohl der Schalter -x, als auch die Option --value mit einem Wert VALUE optional. Sie können also angegeben werden, müssen aber nicht vorhanden sein. Das Positionsargument FILENAME hingegen ist erforderlich.

Wiederholungen #

Wiederholungen von einzelnen Argumenten oder Argumentgruppen werden mit einer angehängten Ellipsis ... oder mit einem Stern * gekennzeichnet. Wenn Gruppen von Argumenten wiederholt werden dürfen, sind sie oft in eckigen Klammern zusammengefasst; manchmal aber auch in runden.

Usage: prog [ INPUTFILE ]...

Usage: prog [--param parameter]...

Usage: prog (-p <X> <Y>)*

Soll deutlich gemacht werden, dass ein Argument oder eine Argumentgruppe mindestens einmal aber auch mehrfach verwendet werden kann, sind die folgenden Schreibweisen üblich.

Usage: prog INPUTFILE...

Usage: prog (<Input File>)+

Alternativen #

Häufig werden für eine Option oder ein Positionsargument verschiedene zulässige Werte oder Werttypen genannt. Diese sind also Alternativen für den Optionswert oder das Positionsargument. Alternativen werden eigentlich immer mit einem Pipe-Symbol | getrennt (BNF). Um deutlich zu machen, was alles zu den Alternativen gehört, werden diese oft in geschweifte oder runde Klammern eingefasst.

Usage: prog [--level low | mid | high]

Usage: prog { input_file | - }

Usage: prog ( -v {value} | -p {percent} )

Beispiele mit Erläuterung #

Die beiden folgenden, etwas kompliziertere Beispiele verdeutlichen das Zusammenspiel der verschiedenen Elemente in den Syntaxausdrücken.

FFmpeg #

Das Audio- und Videoverarbeitungsprogramm FFmpeg gibt im Hilfetext die folgende Syntaxzeile an:

usage: ffmpeg [options] [[infile options] -i infile]... {[outfile options] outfile}...

Zunächst kann man nach einem Teil der Befehlszeile suchen, der nicht optional ist. options ist in eckige Klammern eingeschlossen, also optional. Die Gruppe mit der Option -i infile ist ebenfalls optional. Die letzte Gruppe für das Positionsargument outfile ist aber in geschweifte Klammern eingefasst und damit nicht optional. Dem Positionsargument outfile dürfen outfile options vorangestellt werden. Welche dies genau sind, wird an anderer Stelle im Hilfetext erläutert. Der ganzen Gruppe {[outfile options] outfile} ist eine Ellipsis nachgestellt. Sie kann also mehrfach auftreten.

Die Gruppe [infile options] -i infile ist in eckige Klammern mit Ellipsis eingefasst. Sie kann also weggelassen werden, einmal oder auch mehrfach angegeben werden. Der Option -i infile dürfen ähnlich dem Argument outfile eine Reihe von infile options vorangestellt werden, die an anderer Stelle im Hilfetext erläutert werden.

Und zuletzt, in der Befehlszeile aber am Anfang, dürfen options angegeben werden. Auch diese werden an anderer Stelle im Hilfetext erläutert.

FFmpeg gibt also für seine Befehlszeile die folgende Struktur vor:

  • Globale Optionen
  • Keine, eine oder mehrere Eingabedateien, denen jeweils Eingabeoptionen vorangestellt werden können
  • Ein oder mehrere Ausgabedateien, denen jeweils Ausgabeoptionen vorangestellt werden können

PowerShell #

Die PowerShell und ihre Commandlets besitzen eine sonst untypische Syntax für die Befehlszeilenargumente. Sie prägt damit eine eigene Tradition.

Der Hilfetext der moderneren Variante (vormals PowerShell Core) beginnt mit:

Usage: pwsh[.exe] [-Login] [[-File] <filePath> [args]]
                  [-Command { - | <script-block> [-args <arg-array>]
                                | <string> [<CommandParameters>] } ]
                  [-CommandWithArgs <string> [<CommandParameters>]
                  [-ConfigurationName <string>] [-ConfigurationFile <filePath>]
                  [-CustomPipeName <string>] [-EncodedCommand <Base64EncodedCommand>]
                  [-ExecutionPolicy <ExecutionPolicy>] [-InputFormat {Text | XML}]
                  [-Interactive] [-MTA] [-NoExit] [-NoLogo] [-NonInteractive] [-NoProfile]
                  [-NoProfileLoadTime] [-OutputFormat {Text | XML}]
                  [-SettingsFile <filePath>] [-SSHServerMode] [-STA]
                  [-Version] [-WindowStyle <style>]
                  [-WorkingDirectory <directoryPath>]

       pwsh[.exe] -h | -Help | -? | /?

Zunächst lassen sich zwei alternative Aufrufformen erkennen:

  1. Der normale Aufruf zur Ausführung von Befehlen oder eines Skripts
  2. Der Aufruf der Hilfe

Dem Befehlsname pwsh ist hier ein [.exe] angehängt. Der Befehl kann also entweder pwsh.exe oder nur pwsh heißen. Vielleicht will Microsoft so darauf aufmerksam machen, dass PowerShell plattformübergreifend (Windows, Linux, MacOS) nutzbar ist. Oder es will deutlich machen, dass die PowerShell, auch unter Windows, entweder mit oder ohne der Dateiendung aufgerufen werden kann. Das ist möglich, weil die Dateiendung .EXE in der Umgebungsvariable PATHEXT enthalten ist.

Kurz zur zweiten Aufrufform, dem Aufruf der Hilfe: Es wird einer der alternativen Schalter -h, -Help, -? oder /? akzeptiert. Für diese Aufrufform muss einer der vier Schalter übergeben werden. Und wenn einer dieser Schalter übergeben wird, ist kein weiteres Argument erlaubt. Denn die vier Alternativen bilden die einzig erlaubten Argumente dieser Aufrufform und sind nicht von eckigen Klammern umgeben.

Nun zur normalen Aufrufform: Es werden eine ganze Reihe von Schaltern (z. B.-Login, -Interactive, -NoExit) und Optionen (z. B. -ConfigurationName <string>, -EncodedCommand <Base64EncodedCommand>) unterstützt.

Interessanter ist aber der Teil [[-File] <filePath> [args]]. Der ganze Ausdruck ist eine optionale Gruppe, gekennzeichnet durch umschließende eckige Klammern. An den spitzen Klammern lässt sich der innerhalb der Gruppe erforderliche Platzhalter <filePath> erkennen. Diesem darf das optionale Optionsschlüsselwort -File vorangestellt werden. Mit dieser Syntax setzt die PowerShell Standardoptionen um, die entweder als Option mit dem Optionsschlüsselwort oder als Positionsargument auftreten dürfen. Nach dem Platzhalter <filePath> dürfen optional Argumente für die genannte Skriptdatei übergeben werden.

Man kann die PowerShell also mit den folgenden Zeilen zur Ausführung eines Skriptes bewegen, wobei der Platzhalter <filePath> durch einen Pfad zum Skript .\Projecte\MeinSkript.ps1 ersetzt wird:

  • pwsh .\Projekte\MeinSkript.ps1 (ohne Argumente für das Skript)
  • pwsh -File .\Projekte\MeinSkript.ps1 "Argument 1" "Argument 2"

Auch der folgende Ausdruck ist interessant:

[-Command { - | <script-block> [-args <arg-array>]
              | <string> [<CommandParameters>] } ]

Der ganze Ausdruck ist eine Option mit dem Schlüsselwort Command. Als Optionswert werden drei Alternativen erwartet:

  1. Ein einzelner Bindestrich - um anzugeben, dass der auszuführende Befehl von der Standardeingabe gelesen werden soll
  2. Ein PowerShell-Skriptblock dem mit der optional folgenden Option -args <arg-array> ein PowerShell-Array mit Argumenten übergeben werden kann
    (Diese Alternative kann nur aus einer laufenden PowerShell-Instanz heraus genutzt werden.)
  3. Ein PowerShell-Befehlsname auf den optional Befehlsparameter folgen dürfen

In der Anwendung könnte das wie folgt aussehen:

  1. Get-Content mycommand.txt | pwsh -Command -
  2. pwsh -Command { param($x, $y); Write-Output "$x/$y" } -args @("A", "B")
  3. pwsh -Command Get-ChildItem -Path C:\Users

Hilfetexte schreiben #

Beim Verfassen von Hilfetexten für ein eigenes Programm ist es sinnvoll, sich an einer weit verbreiteten Tradition zu orientieren. Dazu nimmt man am besten ein bereits existierendes Programm, welches in der entsprechenden Tradition entwickelt wurde, und übernimmt die Schreibweisen aus dessen Hilfetexten. Das wichtigste für den Leser der Hilfetexte ist, dass die Schreibweise für die Syntaxdefinitionen der Befehlszeilenargumente konsistent ist.

Global akzeptiert sind eckige Klammern […] für optionale Argumente und das Pipe-Symbol | für Alternativen aus der BNF. Um sich darüber hinaus an der BNF zu orientieren, können Platzhalter in spitze Klammern <…> und Gruppen für Wiederholungen in runde Klammern (…) gesetzt werden.

  1. Manpage in der Wikipedia: https://de.wikipedia.org/wiki/Manpage ↩︎

  2. man-Befehl für Ubuntu: https://wiki.ubuntuusers.de/man/ ↩︎

  3. Backus-Naur-Form in der Wikipedia: https://de.wikipedia.org/wiki/Backus-Naur-Form ↩︎