Exibindo comentários de uso em funções destinadas a serem usadas interativamente

11

Eu tenho várias funções definidas no meu .bashrc, destinadas a serem usadas interativamente em um terminal. Geralmente, eu os precedia com um comentário descrevendo o uso pretendido:

# Usage: foo [bar]
# Foo's a bar into a baz
foo() {
  ...
}

Isso é bom se você estiver navegando no código-fonte, mas é bom rodar typeno terminal para obter um lembrete rápido do que a função faz. No entanto, isso (compreensivelmente) não inclui comentários:

$ type foo
foo is a function
foo ()
{
    ...
}

O que me fez pensar "não seria legal se esse tipo de comentário persistisse para typepoder exibi-lo?" E no espírito das doutrinas de Python, eu vim com isso:

foo() {
  : Usage: foo [bar]
  : "Foo's a bar into a baz"
  ...
}

$ type foo
foo is a function
foo ()
{
    : Usage: foo [bar];
    : "Foo's a bar into a baz";
    ...
}

Agora, o uso está incluído na typesaída! Obviamente, como você pode ver, a citação se torna um problema que pode ser propenso a erros, mas é uma experiência melhor do usuário quando funciona.

Então, minha pergunta é: essa é uma péssima idéia? Existem alternativas melhores (como funções a man/ infopara) para fornecer aos usuários das funções do Bash um contexto adicional?

Idealmente, eu ainda gostaria que as instruções de uso estivessem localizadas próximas à definição da função, para que as pessoas que visualizam o código-fonte também obtenham o benefício, mas se houver uma maneira "adequada" de fazer isso, estou aberto a alternativas.

Editar estas são todas as funções de estilo auxiliar bastante simples e só estou procurando obter um pouco de contexto extra interativamente. Certamente, para scripts mais complexos que analisam sinalizadores, eu adicionaria uma --helpopção, mas para esses seria um pouco oneroso adicionar sinalizadores de ajuda a tudo. Talvez seja apenas um custo que devo aceitar, mas esse :hack parece funcionar razoavelmente bem sem tornar a fonte muito mais difícil de ler nossa edição.

dimo414
fonte

Respostas:

8

Não acho que exista apenas uma boa maneira de fazer isso.

Muitas funções, scripts e outros executáveis ​​fornecem uma mensagem de ajuda se o usuário fornecer -hou --helpcomo uma opção:

$ foo() {
[[ "$1" =~ (-h|--help) ]] && { cat <<EOF
Usage: foo [bar]
Foo's a bar into a baz
EOF
return;
}
: ...other stuff...
}

Por exemplo:

$ foo -h
Usage: foo [bar]
Foo's a bar into a baz

$ foo --help
Usage: foo [bar]
Foo's a bar into a baz
John1024
fonte
Sim, eu deveria ter mencionado isso. Essas são funções simples e estou tentando evitar torná-las excessivamente complexas. Para comandos que merecem análise de sinalizadores, certamente adicionaria uma --helpopção.
dimo414
Na programação, consistência é uma virtude. Além disso, depende do que você quer dizer com "complexo".
John1024
E sua abordagem é inteligente e boa (e sua pergunta já tem o meu +1).
John1024
1
Obrigado; sua implementação --helptambém não é invasiva, o que eu acho que é o meu principal critério neste caso. Posso acabar usando o :truque, uma vez que ele se encaixa mais diretamente no meu caso de uso, mas agradeço por você salientar que não é difícil dar suporte --helpe que a maioria dos usuários espera isso.
Dimo414
1
+1. eu ia responder "use getopts", mas isso funciona bem o suficiente se não houver outras opções. se a função tiver outras opções, use getopts.
12286