Terminábamos la lección anterior con un diagnóstico incómodo: los bucles nos habían quitado la repetición entre ejecuciones del script, pero dentro del fichero seguíamos escribiendo tres veces el mismo bloque de validación y cuatro veces el mismo printf de formato. En Bash no hay clases, ni módulos, ni objetos: la función es la única unidad de reutilización que existe. Todo lo que quieras escribir una vez y usar muchas —validar, formatear, registrar, calcular— tiene que ser una función. En esta lección aprenderás a definirlas, a pasarles datos, a recuperar resultados (que no es lo que parece) y a documentarlas; y al final refactorizarás informe-diario.sh para que deje de ser una pared de código y pase a ser un conjunto de piezas con nombre.

1. Las dos sintaxis y cuál preferir
2. Dónde se definen: definiciones arriba, main abajo
3. Parámetros: las funciones son mini-scripts
4. local, y el bug que te espera si lo olvidas
5. return devuelve un código de salida, no un dato
6. Cómo devolver datos de verdad
7. Funciones que fallan, y recursividad
8. Funciones frente a scripts y alias
9. Documentar una función
10. Refactor de informe-diario.sh

Bash admite dos formas de declarar una función, y una tercera que las mezcla:

Usaremos nombre() { ... } en todo el curso. Es la que espera ShellCheck (08-05) y la que sigue funcionando si algún día el script tiene que correr bajo sh (08-07).

Reglas de nombre: letras, dígitos y guiones bajos; por convención, minúsculas con _. No pongas paréntesis al llamarla: se invoca como un comando cualquiera, saludar, no saludar().

Bash lee el script de arriba abajo. Una función solo existe después de que el intérprete haya pasado por su definición:

De aquí nace el patrón estructural que usarás en todos tus scripts a partir de ahora:

Ventajas concretas de este esqueleto: el lector encuentra el flujo del programa en main y no hurgando entre 300 líneas; nada se ejecuta hasta la última línea, así que el orden de definición entre funciones deja de importar (cuando main corre, todas están cargadas); y main "$@" reenvía los argumentos del script a la función, con las comillas alrededor de $@ que 03-05 declaró obligatorias.

Aquí está la sorpresa para quien viene de otros lenguajes: los parámetros no se declaran en la firma. Una función recibe argumentos exactamente igual que un script: $1, $2, $#, "$@", shift.

Dos matices que sorprenden: $0 no cambia dentro de una función (sigue siendo el nombre del script; para el nombre de la función está ${FUNCNAME[0]}), y $1 son los argumentos de la función, no los del script, así que si los necesitas dentro hay que pasárselos con mi_funcion "$@".

Por defecto, todas las variables de Bash son globales, incluidas las que asignas dentro de una función. Esto produce uno de los bugs más difíciles de rastrear del lenguaje:

La función ha destruido una variable del programa principal sin avisar. La solución es declarar local toda variable de trabajo interno:

Detalles de local: solo es válido dentro de una función; admite varias a la vez (local a b c=0); su ámbito es dinámico, de modo que una función llamada desde otra ve las local de quien la llamó (no lo aproveches). Y cuidado con local var=$(comando): el $? que queda es el de local, siempre 0, no el del comando; si necesitas comprobarlo, sepáralo en local var; var=$(comando) || return 1.

Regla de oro: si una variable no está declarada local, es porque quieres deliberadamente que sobreviva a la función.

return N termina la función y fija $? con N. Es el mismo mecanismo de los códigos de salida de 03-01, con las mismas limitaciones: un entero entre 0 y 255, donde 0 significa éxito.

Como la función devuelve un código, puede usarse directamente en un if, en un &&, en un while… igual que cualquier comando. Esa es la razón por la que las funciones de comprobación se llaman con nombres tipo pregunta (csv_utilizable, es_ciudad_valida) y devuelven 0/1.

Lo que no puedes hacer es return 3.5, return "Valencia" ni return 1000 (se trunca a 1000 % 256 = 232). Si omites return, la función devuelve el código del último comando ejecutado.

Hay tres técnicas, en orden de preferencia:

a) Escribir a stdout y capturar con $( ). Es la forma idiomática:

Su coste: $( ) crea un subshell, y la función no puede escribir nada más en stdout —mensajes de progreso incluidos— sin contaminar el resultado. Por eso los mensajes informativos siempre van a stderr, como verás en log_info más abajo.

b) Asignar a una variable global acordada (resultado=...). Rápido y sin subshell, pero acopla la función a un nombre concreto.

c) Nameref con local -n (Bash 4.3+). El llamante decide el nombre de la variable de salida y la función escribe en ella indirectamente:

local -n es la versión con ámbito de declare -n. Es la técnica que usarás para "devolver" arrays (04-03), donde $( ) perdería la separación entre elementos. Trampa: el nombre local no puede coincidir con el que pasa el llamante o Bash da error de referencia circular; por eso se prefija con _.

Encadenar funciones con &&, || y $? funciona igual que con comandos externos: validar_entorno || exit $? propaga el código de la función al sistema operativo, y csv_utilizable && procesar_csv encadena. Ojo: exit dentro de una función mata el script entero, no solo la función. Es correcto en funciones de aborto como morir(), pero en una función reutilizable prefiere return y deja que el llamante decida.

Bash admite recursividad —factorial() { local n="$1"; (( n <= 1 )) && { echo 1; return; }; echo $(( n * $(factorial $(( n - 1 )) ) )); }— pero cada nivel crea un subshell por el $( ), así que es lento; el límite lo fija FUNCNEST. En scripts de operaciones, un bucle es casi siempre más claro y más rápido.

Traducción práctica: los alias son atajos de teclado personales (alias ll='ls -l'), las funciones son la reutilización dentro de un programa, y los scripts son la unidad que se invoca desde fuera —cron, systemd, otro script—. informe-diario.sh es un script; validar_entorno es una función suya.

Una función sin cabecera obliga a leer su cuerpo para saber cómo se usa. Adopta este formato desde hoy:

Cuatro apartados fijos —uso, argumentos, salida, código de retorno— y una línea de descripción. Es barato de escribir y elimina la mitad de las preguntas sobre el script.

Aplicamos todo lo anterior. Este es el esqueleto del script tras el refactor (omitimos el parseo de opciones, que ya tienes de 03-05):

Qué hemos ganado: un solo sitio que valida (si mañana hay que comprobar el fichero de configuración, se toca validar_entorno y nada más); mensajes separados de datos, porque log_info escribe en stderr y así informe-diario.sh > informe.txt guarda la tabla limpia mientras los avisos siguen en pantalla —la separación de flujos de 02-04 aplicada con criterio—; un bucle de cuatro líneas en lugar de cuatro bloques idénticos, de modo que añadir Zaragoza es añadir una palabra a CIUDADES; y un main que cabe en una pantalla y se lee como el enunciado del problema.

El || true de contar_errores merece explicación: grep -c devuelve código 1 cuando cuenta 0 coincidencias, lo que en un script con set -e (05-03) abortaría el programa. || true fuerza un código 0 sin alterar la salida.

Estas funciones son genéricas y las querrás también en otros scripts del toolkit. En 05-06 las moverás a ~/veloz-ops/lib/comun.sh y las cargarás con source, convirtiendo el toolkit en una librería de verdad.

• Llamar a la función con paréntesis: resumen_ciudad("Valencia") no es un error de sintaxis, es otra cosa y fallará de forma rara. Se llama resumen_ciudad Valencia.
• Olvidar local. El bug más caro de la lección. Declara local todo lo interno, siempre.
• Mezclar mensajes y resultado en stdout. Si la función se captura con $( ), cualquier echo de progreso acaba dentro del resultado. Mensajes → stderr.
• Creer que return devuelve datos. Devuelve un código 0-255. return $(wc -l < fichero) con 300 líneas devolvería 44.
• Definir una función después de usarla. Definiciones arriba, main "$@" al final.
• Consejo: nombra las funciones con verbo (validar_, contar_, generar_) y las de comprobación como predicados (es_valida, existe_). El nombre debe hacer innecesario leer el cuerpo.

Ejercicio 1. Escribe es_ciudad_valida() que reciba una ciudad y devuelva 0 si está entre las cuatro operativas y 1 en caso contrario, sin imprimir nada. Úsala en un if.

Ejercicio 2. Escribe envios_de() que reciba un repartidor y escriba en stdout su número de envíos, y demuestra que se captura con $( ). Añade la cabecera de documentación completa.

Ejercicio 3. Corrige esta función, que tiene dos defectos:

Solución 1.

En 04-05 verás que un case hace esto en tres líneas, y en 04-03 que un array asociativo lo hace en una.

Solución 2.

Solución 3. Los dos defectos son que suma es global y que return no puede devolver un total (se trunca a módulo 256):

De paso: ${importe%.*} recorta la parte decimal —una expansión que dominarás en 04-04— porque Bash no suma decimales, algo que resolverás del todo en 04-06.

Las funciones convierten un guion en un programa. Se definen con nombre() { }, se colocan todas arriba con un main "$@" como última línea, reciben argumentos igual que un script mediante $1 y "$@", protegen su estado interno con local, señalan éxito o fracaso con return (un código, nunca un dato) y entregan resultados escribiendo a stdout para que el llamante los capture con $( ) —o mediante un nameref cuando eso no basta—. Con validar_entorno, contar_errores, resumen_ciudad y las dos funciones de registro, informe-diario.sh ya tiene esqueleto.

Le falta memoria. Nuestro main ya usa "${CIUDADES[@]}" sin haber explicado qué es esa sintaxis, y el bucle vuelve a leer el CSV entero una vez por ciudad porque no tiene dónde acumular un contador por cada una. Eso son los arrays (04-03): listas indexadas y, mejor aún, mapas de clave→valor que permiten contar incidencias por ciudad y por repartidor en una sola pasada, sustituyendo al viejo sort | uniq -c que arrastramos desde el Módulo 2.