Tengo una serie de funciones definidas en mi .bashrc
, con la intención de ser utilizadas de forma interactiva en un terminal. Generalmente los precedí con un comentario que describe su uso previsto:
# Usage: foo [bar]
# Foo's a bar into a baz
foo() {
...
}
Esto está bien si navega por el código fuente, pero es bueno ejecutarlo type
en la terminal para obtener un recordatorio rápido de lo que hace la función. Sin embargo, esto (comprensiblemente) no incluye comentarios:
$ type foo
foo is a function
foo ()
{
...
}
Lo que me hizo pensar "¿no sería bueno si este tipo de comentarios persistieran para type
poder mostrarlos?" Y en el espíritu de las cadenas de documentos de Python se me ocurrió esto:
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";
...
}
Ahora el uso se incluye en el mismo type
la salida! Por supuesto, como puede ver, las citas se convierten en un problema que podría ser propenso a errores, pero es una experiencia de usuario más agradable cuando funciona.
Entonces mi pregunta es, ¿es esta una idea terrible? ¿Existen mejores alternativas (como las funciones a man
/ info
para) para proporcionar a los usuarios de las funciones de Bash un contexto adicional?
Idealmente, todavía me gustaría que las instrucciones de uso se ubicaran cerca de la definición de la función para que las personas que vean el código fuente también obtengan el beneficio, pero si hay una forma "adecuada" de hacerlo, estoy abierto a alternativas.
Editar estas son funciones de estilo auxiliar bastante simples y solo estoy buscando obtener un poco de contexto adicional de forma interactiva. Ciertamente, para secuencias de comandos más complejas que analizan indicadores, agregaría una --help
opción, pero para estos sería un poco pesado agregar indicadores de ayuda a todo. Quizás sea solo un costo que debería aceptar, pero este :
truco parece funcionar razonablemente bien sin hacer que la fuente sea mucho más difícil de leer.
fuente
--help
opción.--help
también es no invasiva, lo cual creo que es mi criterio principal en este caso. Puede que termine usando el:
truco, ya que se ajusta más directamente a mi caso de uso, pero agradezco que señale que no es difícil de soportar--help
y que la mayoría de los usuarios lo esperarán.getopts
.