Dies ist ein Framework zum Schreiben von Bash-Skripten, die Optionen und/oder Argumente akzeptieren. Definieren Sie die von Ihrem Skript akzeptierten Optionen und Argumente mithilfe einer einfachen deklarativen Syntax und lassen Sie bash-args Folgendes zu:
Es ist so konzipiert, dass es einfach zu bedienen ist, nicht im Weg steht und ein ausgefeiltes Benutzererlebnis bietet.
Ziel ist es, portabel zu sein. Die Testsuite unterstützt alle Hauptversionen von Bash >= 3.2.
Um bash-args in Ihren Skripten zu verwenden, beziehen Sie einfach die Datei init.sh als Quelle.
Hier ist ein Beispielskript eval-command.sh :
#! /usr/bin/env bash
# Summary : My first bash script using bash-args.
#
# Description : This takes a command as argument, and runs it.
#
# Argument : command
#
# Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
#
. path/to/bash-args/init.sh
# After sourcing the script, you can use the $directory and the $dry_run
# variables to get the values of the options typed (or not) in the command line.
# The other arguments are available as standard bash arguments $1, $2, etc.
command= " cd $directory && $1 "
if [[ $dry_run -eq 1 ]] ; then
echo " $command "
else
eval " $command "
fiVersuchen wir, diesen Befehl mit Optionen auszuführen:
$ eval-command.sh --dry-run --directory /home 'echo hello'
cd /home && echo hello
Sie können kurze Optionen verwenden und diese können gruppiert werden:
$ eval-command.sh -nd /home 'echo hello'
cd /home && echo hello
Vervollständigung der Setup-Registerkarte mit einem einfachen Befehl:
$ eval $(eval-command.sh _register_completion)
Es gibt eine Hilfeseite:
$ eval-command.sh --help
My first bash script using bash-args.
Usage : eval-command.sh [OPTIONS] [COMMAND]
This takes a command as argument, and runs it.
Options :
--help | -h
Show this help.
--dry-run | -n
Don't execute, just print.
--directory | -d [DIRECTORY]
The directory in which to run the command.
Bash-Args können auch Unterbefehle verwalten:
main-script.sh help subcmd1 oder main-script.sh subcmd1 --help verfügbar. Rufen Sie dazu die Funktion cmd_run am Ende Ihres Hauptskripts auf und definieren Sie Unterbefehle, indem Sie Shell-Skripte zum Verzeichnis cmd/ hinzufügen. Die Struktur Ihres Projekts sollte wie folgt aussehen:
main-script.sh
cmd/
- subcmd1.sh
- subcmd2.sh
Um die Unterbefehle zu dokumentieren und ihre Optionen und Argumente zu definieren, schreiben Sie Metadaten in die ersten Kommentarblöcke jedes Unterbefehls, genau wie im Hauptskript.
Im Hauptskript definierte Optionen sind für alle Unterbefehle verfügbar, während in einem Unterbefehl definierte Optionen nur für diesen bestimmten Unterbefehl verfügbar sind.
Die Skriptmetadaten folgen einer sehr einfachen Syntax: Im ersten Kommentarblock definiert jede Zeile, die mit einem Wort gefolgt von einem Semikolon beginnt, ein neues Feld, und alles, was auf das Semikolon folgt, definiert seinen Wert. Die folgenden Zeilen werden bis zum nächsten Feldanfang an den Wert angehängt.
Hier sind die von bash-args verwendeten Felder.
--version , die seinen Namen und seine Version ausgibt.Die Optionen werden in den Optionsmetadaten definiert, wie im Beispielskript:
# Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
# Eine Option beginnt mit einem % gefolgt von ihrem Namen. Optionsnamen dürfen nur alphanumerische Zeichen, _ oder - enthalten.
Die folgenden Zeilen definieren die Parameter der Option. Wenn das Skript ausgeführt wird, wird dies tatsächlich als Bash-Code ausgewertet. Die definierten Variablen sind die Parameter der Option. Dies bedeutet, dass die allgemeinen Anführungszeichenregeln für Zeichenfolgen gelten und Sie die Optionen dynamisch definieren können, wie im obigen Beispiel, in dem der default der directory auf $(pwd) gesetzt ist.
Eine Option muss mindestens den type und variable definieren:
type kann entweder flag oder option sein. Flags akzeptieren keine Argumente, Optionen schon.variable ist der Variablenname, unter dem der Argumentwert der Option in Ihrem Skript verfügbar sein wird.Eine Option kann diese anderen Parameter definieren:
desc ist eine Beschreibung der Option, die auf den Hilfeseiten verwendet wird.short ist ein einzelner Buchstabe, der für die kurze Option verwendet wird.argument ist der Argumenttyp. siehe Argumenttypendefault ist der Wert, den die Option annimmt, wenn die Option nicht in dem vom Benutzer eingegebenen Befehl angegeben ist.value ist der Wert, den die Option annimmt, wenn die Option angegeben wird , jedoch ohne Argument. Die durch Optionen definierten Variablen sind garantiert in Ihrem Skript definiert: Wenn bash-args keinen Wert für eine Option finden kann, wird es mit einem Fehler beendet. Das bedeutet, dass die Ausführung des Hauptskripts ohne diese Option einen Fehler zurückgibt, wenn Sie den default einer Option nicht angeben.
Mit anderen Worten: Wenn Sie nicht möchten, dass eine Option erforderlich ist, definieren Sie in ihrer Definition einen default .
Der value funktioniert auf ähnliche Weise. Wenn Sie es nicht angeben, erfordert die Option bei Verwendung ein Argument. Wenn Sie dies tun, kann die Option ohne Argument verwendet werden.
Flag-Optionen funktionieren auf die gleiche Weise, und da sie keine Argumente akzeptieren, müssen Sie sowohl ihre default als auch value definieren.
Bash-args kann die automatische Vervollständigung Ihres Skripts mithilfe der Vervollständigungs-API von Bash durchführen. Um die automatische Vervollständigung für Ihren Befehl zu aktivieren, führen Sie den folgenden Befehl aus:
eval $( my-command.sh _register_completion ) Die Tab-Vervollständigung schlägt dann die definierten Optionen vor, wenn das Wort an der Stelle mit einem - beginnt, und schlägt andernfalls Unterbefehle und Argumente vor.
Um bash-args mitzuteilen, was als Argument vorgeschlagen werden soll, geben Sie einen Argumenttyp in den Argument Ihres Skripts (oder Unterbefehls) oder im argument einer Option an.
Hier sind die integrierten Argumenttypen:
Um einen neuen Argumenttyp zu erstellen und ihn für die automatische Vervollständigung einzurichten, definieren Sie eine Funktion namens _complete_my_arg_type . Diese Funktion muss für das init.sh -Skript verfügbar sein, daher muss sie vor dem definiert werden . init.sh Zeile.
Die Vervollständigungsfunktionen sollen ihre Vorschläge zum globalen COMP_REPLIES Array hinzufügen. Der Einfachheit halber erhalten sie das aktuelle Wort an Punkt als Parameter, Sie können aber auch die globalen Variablen COMP_LINE und COMP_POINT verwenden, genau wie in allen Bash-Vervollständigungsskripten.
So wird der Dateiargumenttyp definiert:
_complete_file () {
# $1 is the word being typed that we want to complete.
for file in " ${1-} " * ; do
# add each file to the completion candidates.
COMP_REPLIES+=( " $file " )
done
}
