bash args

Bash-args

Esta é uma estrutura para escrever scripts bash que aceitam opções e/ou argumentos. Defina as opções e argumentos aceitos pelo seu script usando uma sintaxe declarativa simples e deixe bash-args :

• Analise os argumentos do comando
• Gerar páginas de ajuda
• Lidar com o preenchimento automático

Ele foi projetado para ser simples de usar, sair do caminho e fornecer uma experiência de usuário refinada.

Pretende ser portátil, o conjunto de testes passa em todas as versões principais do bash >= 3.2.

Índice

• Início rápido
  • Subcomandos
• Metadados de script
• Definindo opções
• Preenchimento automático
  • Tipos de argumento
  • Tipos de argumentos personalizados

Início rápido

Para usar bash-args em seus scripts, basta obter o arquivo init.sh

Aqui está um exemplo de script 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 "
fi

Vamos tentar executar este comando com opções:

 $ eval-command.sh --dry-run --directory /home 'echo hello'
cd /home && echo hello

Você pode usar opções curtas e elas podem ser agrupadas:

 $ eval-command.sh -nd /home 'echo hello'
cd /home && echo hello

Conclusão da guia de configuração com um comando simples:

 $ eval $(eval-command.sh _register_completion)

Uma página de ajuda é fornecida:

 $ 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.

Subcomandos

Bash-args também pode gerenciar subcomandos:

• As páginas de ajuda estão disponíveis para cada comando usando main-script.sh help subcmd1 ou main-script.sh subcmd1 --help .
• O preenchimento automático sugere subcomandos, suas opções e seus argumentos.

Para que isso aconteça, chame a função cmd_run no final do seu script principal e defina subcomandos adicionando scripts shell ao diretório cmd/ . A estrutura do seu projeto deve ser semelhante a:

 main-script.sh
cmd/
  - subcmd1.sh
  - subcmd2.sh

Para documentar os subcomandos e definir suas opções e argumentos, escreva metadados nos primeiros blocos de comentários de cada subcomando, assim como no script principal.

As opções definidas no script principal estão disponíveis para todos os subcomandos, enquanto as opções definidas em um subcomando estão disponíveis apenas para este subcomando específico.

Metadados de script

Os metadados do script seguem uma sintaxe muito simples: no primeiro bloco de comentários, cada linha que começa com uma palavra seguida de ponto e vírgula define um novo campo, e tudo que segue o ponto e vírgula define seu valor. As linhas seguintes, até o início do próximo campo, são anexadas ao valor.

Aqui estão os campos usados ​​por bash-args .

• Resumo: uma descrição de uma linha do script.
• Descrição: uma longa descrição do script.
• Versão: uma string de versão. Se o seu script principal tiver um metacampo de versão, ele receberá uma opção --version que imprime seu nome e versão.
• Uso: Se a linha de uso padrão na página de ajuda não for adequada para você, você pode substituí-la aqui.
• Argumento: Define o tipo de argumento usado para preenchimento automático. veja Tipos de argumentos
• Opções: Defina as opções do seu script. consulte Definindo opções

Definindo opções

As opções são definidas nos metadados de Opções , como no script de exemplo:

 # 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)"
#

Uma opção começa com % seguido de seu nome. Os nomes das opções devem conter apenas caracteres alfanuméricos, _ ou - .

As linhas a seguir definem os parâmetros da opção. Quando o script é executado, ele é avaliado como código bash. As variáveis ​​definidas são os parâmetros da opção. Isso significa que as regras gerais de cotação para strings se aplicam e que você pode definir as opções dinamicamente, como no exemplo acima, no qual o parâmetro default da opção de directory é definido como $(pwd) .

Uma opção deve definir pelo menos o type e o parâmetro variable :

• type pode ser flag ou option . Os sinalizadores não aceitam argumentos, as opções aceitam.
• variable é o nome da variável sob a qual o valor do argumento da opção estará disponível em seu script.

Uma opção pode definir estes outros parâmetros:

• desc é uma descrição da opção, usada nas páginas de ajuda.
• short é uma única letra, usada para a opção curta.
• argument é o tipo de argumento. veja Tipos de argumento
• default é o valor que a opção assume quando a opção não é especificada no comando digitado pelo usuário.
• value é o valor que a opção assume quando a opção é especificada, mas sem argumento.

As variáveis ​​definidas pelas opções são garantidamente definidas em seu script: se bash-args não conseguir encontrar um valor para uma opção, ele sairá com um erro. Isso significa que se você não especificar default de uma opção, executar o script principal sem essa opção retornará um erro.

Em outras palavras, se você não quiser que uma opção seja obrigatória, defina um parâmetro default em sua definição.

O parâmetro value funciona de maneira semelhante. Se você não especificar, a opção, quando usada, exigirá um argumento. Se você fizer isso, a opção poderá ser usada sem argumento.

As opções de sinalização funcionam da mesma maneira e, como não aceitam argumentos, você deve definir seus parâmetros default e value .

Preenchimento automático

Bash-args pode lidar com o preenchimento automático do seu script usando a API de conclusão do Bash. Para ativar o preenchimento automático do seu comando, execute o seguinte comando:

 eval $( my-command.sh _register_completion )

O preenchimento de tabulação irá então sugerir as opções definidas se a palavra no ponto começar com - e sugerir subcomandos e argumentos caso contrário.

Tipos de argumento

Para dizer ao bash-args o que sugerir como argumento, você especifica um tipo de argumento nos metadados Argument do seu script (ou subcomando) ou no parâmetro argument de uma opção.

Aqui estão os tipos de argumentos integrados:

• file irá sugerir arquivos.
• directory irá sugerir diretórios.

Tipos de argumentos personalizados

Para criar um novo tipo de argumento e configurá-lo para preenchimento automático, defina uma função chamada _complete_my_arg_type . Esta função deve estar disponível para o script init.sh , portanto deve ser definida antes do arquivo . init.sh linha . init.sh

As funções de conclusão devem adicionar suas sugestões ao array global COMP_REPLIES . Eles obtêm a palavra atual no ponto como parâmetro por conveniência, mas você também pode usar as variáveis ​​globais COMP_LINE e COMP_POINT , assim como em todos os scripts de conclusão do bash.

Aqui está como o tipo de argumento do arquivo é definido:

 _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
}