Mostrar comentarios de uso en funciones destinadas a ser utilizadas interactivamente

11

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 typeen 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 typepoder 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 typela 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/ infopara) 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 --helpopció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.

dimo414
fuente

Respuestas:

8

No creo que haya una buena manera de hacer esto.

Muchas funciones, scripts y otros ejecutables proporcionan un mensaje de ayuda si el usuario proporciona -ho --helpcomo una opción:

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

Por ejemplo:

$ 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
fuente
Sí, debería haber mencionado eso. Estas son funciones simples y estoy tratando de evitar que sean demasiado complejas. Para los comandos que merecen indicadores de análisis, ciertamente agregaría una --helpopción.
dimo414
En programación, la consistencia es una virtud. Además, depende de lo que quieras decir con "complejo".
John1024
Y, su enfoque es inteligente y bueno (y su pregunta ya tiene mi +1).
John1024
1
Gracias; su implementación --helptambié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 --helpy que la mayoría de los usuarios lo esperarán.
dimo414
1
+1. Iba a responder "usar getopts" pero esto funciona bastante bien si no hay otras opciones. si la función tiene otras opciones, use getopts.
cas