Ao escrever ferramentas para a CLI do UNIX, como devo fazer com que o programa imprima ajuda e / ou uso?
Eu costumo usar fprintf(stderr, "help text here");
, mas há vários problemas com isso.
- Primeiro, não tenho certeza se devo usar
stderr
. Está tudo bem ou devo usarstdout
? - Como você pode imaginar, o texto de ajuda é bastante longo, dependendo de quantas opções a ferramenta possui. Agora, normalmente, basta colocar vários
"strings like that\n"
no segundo parâmetro. No entanto, isso preenche meu código-fonte com cinquenta ou mais linhas de texto de ajuda. Não é nada fácil de gerenciar. O que devo fazer em vez disso? - Quando uma ferramenta não é escrita em C ou em uma linguagem semelhante a C, costumo usar os documentos aqui sempre que possível (principalmente com o Perl). Não posso usar isso em C, mas há algo assim que eu poderia usar?
- Eu estava pensando em colocá-lo
headerfile.h
dentro de um interior#define HELP "help text here"
, nunca o vi na natureza, não sei se devo usá-lo.
Idealmente, eu poderia colocar o texto em um arquivo externo e incluí-lo. Usar #include
para isso parece errado, no entanto. O que devo fazer então?
A idéia é, para ter um texto de ajuda, que seja facilmente gerenciável. Tê-lo dentro do código-fonte não é realmente conveniente.
programming-practices
code-quality
polemon
fonte
fonte
Respostas:
Inspire-se com os elementos internos da sua plataforma de destino
Veja o código fonte do BSD. Por exemplo, aqui estão os:
usage(void)
para a/usr/bin/uname
ferramenta do NetBSD [ fonte ]:usage(void)
para NetBSD's/usr/bin/telnet
[ fonte ]usage(void)
para OpenBSD's/bin/ls
[ fonte ]Veja alternativas
E decida por si mesmo se são melhores ou piores. Você pode usar o Google CodeSearch para encontrar outras pessoas, como:
Como você pode ver, um estilo diferente entre essas e as ferramentas integradas dos sistemas BSD listados acima. Isso não significa que você deve seguir um ou outro. Mas geralmente é bom olhar em volta e se contentar com a solução consistente.
Uma solução não padrão para as 50 linhas de ajuda ...
Se você não gosta de evitar 50 linhas de texto, pode simplesmente ler a ajuda de um arquivo de texto (em texto sem formatação, ou talvez analisar diretamente a
man
fonte da fonte, se tiver criado uma). Acho que é uma maneira bastante elegante (como você pode consultar o documento de texto), no entanto, para programas de sistemas principais que os tornariam inerentemente inseguros e apresentariam um ponto de falha. Outras pessoas argumentam que é pesado para uma mensagemusage
ouhelp
, mas não é como se elas fossem chamadas em loops rápidos e apertados ...Em caso de dúvida, siga os gigantes.
fonte
Eu uso
stdout
, porque uma ajuda não é um erro.Se essa é uma longa ajuda em C, tento imitar os documentos aqui:
Mas na maioria das vezes eu escrevo uma
man
página usandonroff -man
tags dedicadas. A ajuda no aplicativo consiste simplesmente em se referir a essaman
página.fonte
stdlog
?stdlog
padrão C?cin
,cout
,cerr
eclog
), então eu acho que eu penseistdlog
foi no padrão C. Foi mal.Se eu seria você eu apenas abriu fontes de
grep
,tail
,cat
,your_other_favorite_unix_shell_command
para ver como ele é feito lá. Tenho certeza de que seus caminhos são bem pensados e podem ser mantidos por muitas pessoas.Sobre
stderr
oustdout
. É realmente simples, se houver um erro - escreva parastderr
, se for apenas informação -stdout
. Por exemplo, se eu executar sua ferramenta com opções erradas, convém exibir um erro, digamosUse --help for usage
, em que este pertencestderr
. Se eu executar sua ferramenta com uma opção válida--help
, usestdout
.Se é sua preferência não ter longas seqüências de ajuda perto do seu código, não. #define em um arquivo de cabeçalho é perfeitamente adequado, mas é realmente uma preferência pessoal. Se eu precisasse ler o código de uma ferramenta de linha de comando, preferiria que sua string de ajuda estivesse dentro de um arquivo que lida com as opções fornecidas pelo usuário.
fonte
Eu uso a biblioteca gnu getopts . Para um exemplo com ajuda, consulte este projeto de amostra , especificamente o método principal na parte inferior de parser.y .
Uma vez que está envolto em chaves, o editor do vim que eu uso pode dobrar as linhas e nem as noto quando não preciso.
fonte
Se eu usar C ou preferir não depender das bibliotecas do Boost, continuo com o GNU
getopt
. Caso contrário, prefiro as Boost Program Options, que imprimem ajuda automaticamente.Também considero adivinhar a opção certa como uma das melhores práticas quando se trata de manipulação de opções. Eu aprendi com o Git e agora uso o mesmo em meus projetos. Ele basicamente usa a distância Damerau – Levenshtein para imprimir as melhores correspondências se o usuário digitar alguma opção de linha de comando desconhecida.
Escrevi um pequeno artigo sobre isso que você pode usar como exemplo.
Espero que ajude :)
fonte
Obviamente, escrever uma página de furo no código cout << ou printf () é complicado, principalmente se você precisar alterar e preencher novamente seus parágrafos. Portanto, é obviamente uma boa idéia editar esse texto em um arquivo separado, usando, por exemplo, o emacs, onde você pode formatar mais facilmente o seu texto.
Em seguida, você pode usar o seguinte script sed para converter esse arquivo de texto em um arquivo de cabeçalho C legal:
Depois, #include - inclua o arquivo de cabeçalho no código-fonte, você pode simplesmente escrever seu texto usando
fonte