Este es un marco para escribir scripts bash que aceptan opciones y/o argumentos. Defina las opciones y argumentos aceptados por su script usando una sintaxis declarativa simple y deje bash-args :
Está diseñado para ser fácil de usar, no estorbar y brindar una experiencia de usuario refinada.
Su objetivo es ser portátil, el conjunto de pruebas pasa por todas las versiones principales de bash >= 3.2.
Para usar bash-args en sus scripts, simplemente obtenga el archivo init.sh
Aquí hay un script de ejemplo 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 "
fiIntentemos ejecutar este comando con opciones:
$ eval-command.sh --dry-run --directory /home 'echo hello'
cd /home && echo hello
Puede utilizar opciones cortas y se pueden agrupar:
$ eval-command.sh -nd /home 'echo hello'
cd /home && echo hello
Completar la pestaña de configuración con un comando simple:
$ eval $(eval-command.sh _register_completion)
Se proporciona una página de ayuda:
$ 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 también puede gestionar subcomandos:
main-script.sh help subcmd1 o main-script.sh subcmd1 --help . Para que esto suceda, llame a la función cmd_run al final de su script principal y defina subcomandos agregando scripts de shell al directorio cmd/ . La estructura de su proyecto debería verse así:
main-script.sh
cmd/
- subcmd1.sh
- subcmd2.sh
Para documentar los subcomandos y definir sus opciones y argumentos, escriba metadatos en los primeros bloques de comentarios de cada subcomando, tal como en el script principal.
Las opciones definidas en el script principal están disponibles para todos los subcomandos, mientras que las opciones definidas en un subcomando solo están disponibles para este subcomando específico.
Los metadatos del script siguen una sintaxis muy simple: en el primer bloque de comentarios, cada línea que comienza con una palabra seguida de un punto y coma define un nuevo campo, y todo lo que sigue al punto y coma define su valor. Las siguientes líneas, hasta el inicio del siguiente campo, se añaden al valor.
Estos son los campos utilizados por bash-args .
--version que imprime su nombre y versión.Las opciones se definen en los metadatos de Opciones , como en el script de ejemplo:
# 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)"
# Una opción comienza con un % seguido de su nombre. Los nombres de las opciones deben contener solo caracteres alfanuméricos, _ o - .
Las siguientes líneas definen los parámetros de la opción. Cuando se ejecuta el script, en realidad se evalúa como código bash. Las variables definidas son los parámetros de la opción. Esto significa que se aplican las reglas generales de citación de cadenas y que puede definir las opciones dinámicamente, como en el ejemplo anterior, en el que el parámetro default de la opción directory está establecido en $(pwd) .
Una opción debe definir al menos el type y el parámetro variable :
type puede ser flag u option . Las banderas no aceptan argumentos, las opciones sí.variable es el nombre de la variable bajo el cual el valor del argumento de la opción estará disponible en su secuencia de comandos.Una opción puede definir estos otros parámetros:
desc es una descripción de la opción, utilizada en las páginas de ayuda.short es una sola letra, utilizada para la opción corta.argument es el tipo de argumento. ver tipos de argumentosdefault es el valor que toma la opción cuando no se especifica en el comando escrito por el usuario.value es el valor que toma la opción cuando se especifica la opción, pero sin argumento. Se garantiza que las variables definidas por las opciones estarán definidas en su script: si bash-args no puede encontrar un valor para una opción, saldrá con un error. Esto significa que si no especifica default de una opción, ejecutar el script principal sin esta opción devolverá un error.
En otras palabras, si no desea que se requiera una opción, defina un parámetro default en su definición.
El parámetro value funciona de manera similar. Si no lo especifica, la opción, cuando se utiliza, requiere un argumento. Si lo hace, la opción se puede utilizar sin argumentos.
Las opciones de bandera funcionan de la misma manera y, como no aceptan argumentos, debes definir sus parámetros default y value .
Bash-args puede manejar la finalización automática de su script utilizando la API de finalización de Bash. Para activar la finalización automática de su comando, ejecute el siguiente comando:
eval $( my-command.sh _register_completion ) La función de tabulación sugerirá las opciones definidas si la palabra en el punto comienza con - y, en caso contrario, sugerirá subcomandos y argumentos.
Para decirle a bash-args qué sugerir como argumento, especifica un tipo de argumento en los metadatos del Argument de su script (o subcomando), o en el parámetro argument de una opción.
Estos son los tipos de argumentos integrados:
Para crear un nuevo tipo de argumento y configurarlo para que se complete automáticamente, defina una función llamada _complete_my_arg_type . Esta función debe estar disponible para el script init.sh , por lo que debe definirse antes del archivo . init.sh línea . init.sh
Se supone que las funciones de finalización agregan sus sugerencias a la matriz global COMP_REPLIES . Obtienen la palabra actual en el punto como parámetro para mayor comodidad, pero también puedes usar las variables globales COMP_LINE y COMP_POINT , como en todos los scripts de finalización de bash.
Así es como se define el tipo de argumento del archivo :
_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
}
