Arribem a la fita del mòdul, i a una promesa que arrosseguem des de 04-02. informe-diari.sh és avui un programa robust: valida el seu entorn, es protegeix amb flock, avorta amb diagnòstic, valida text amb regex i dirigeix la seva sortida amb precisió. Però és també un únic fitxer de diversos centenars de línies on conviuen log_info, morir, validar_entorn i percentatge —funcions que no tenen res a veure amb informes i que qualsevol altre script del toolkit necessitaria—. La temptació, quan escriguis arxivar-historic.sh la setmana vinent, serà copiar i enganxar. I aquí comença el deteriorament: dues còpies que divergeixen, una fallada corregida en una i no en l'altra, tres convenis de registre diferents. En aquesta lliçó converteixes aquest fitxer en un projecte amb arquitectura.

1. source enfront d'executar
2. Què és una llibreria en Bash
3. Localitzar la llibreria sense que les rutes et traeixin
4. Guardes d'inclusió
5. Noms: què és públic i què és privat
6. Fitxers de configuració
7. Ordre de precedència
8. L'estructura final del toolkit
9. lib/comu.sh
10. informe-diari.sh com a orquestrador
11. Provar la llibreria a mà

A 03-01 vas veure les formes d'executar un script. La que ara importa és la que no crea un procés: enfront de ./script.sh o bash script.sh, que llancen un procés nou del qual no torna res, source script.sh (o la seva forma POSIX . script.sh) executa el fitxer en aquest shell.

Les dues últimes files expliquen per què una llibreria no és un script normal. Com que es carrega amb source, no necessita ni shebang executable ni permís d'execució. I sobretot: un exit en una llibreria mata qui la carrega, inclosa la teva sessió interactiva si l'estaves provant; dins d'una llibreria es fa servir return. Això no és nou: és el mateix mecanisme pel qual ~/.bashrc defineix funcions que el teu shell coneix (01-02). Una llibreria és un .bashrc per als teus scripts.

Una llibreria és un fitxer que conté només definicions: funcions, constants i, com a molt, valors per defecte. Res que actuï per si mateix.

La regla és que carregar la llibreria ha de ser silenciós i sense efectes. El set -euo pipefail dins d'una llibreria és especialment traïdor: en fer source s'aplica al shell que la carrega, així que pot canviar el comportament d'errors d'un script que no s'ho esperava. La política estricta la decideix l'executable, no la llibreria. Convencions: extensió .sh (o .bash), sense shebang executable —opcionalment un #!/usr/bin/env bash com a pista per a editors i per a shellcheck, però sense permís +x—, i una capçalera de comentari que digui què ofereix.

Aquí hi ha el problema tècnic de debò. Com troba bin/informe-diari.sh la lib/comu.sh?

Les rutes relatives es resolen des del directori de treball actual, que és on sigui qui llança l'script, no on viu l'script. Com que ~/veloz-ops/bin és al PATH (el vam posar allà a 01-02), el normal és invocar-lo des de qualsevol lloc, i el source falla. L'idioma canònic és aquest:

Desmuntat de dins cap a fora:

• ${BASH_SOURCE[0]} és la ruta del fitxer en execució. Es fa servir en comptes de $0 per dos motius: $0 val bash quan l'script s'invoca com a bash script.sh, i dins d'un fitxer carregat amb source, $0 segueix sent el de l'script principal mentre que BASH_SOURCE[0] és la llibreria. Per a una llibreria que necessita saber on és, $0 dona sempre la resposta equivocada.
• dirname dona el directori que la conté (04-04) i /.. puja a l'arrel del projecte; cd ... && pwd converteix aquesta ruta, que pot ser relativa (./bin/..), en absoluta i normalitzada; i tot va entre cometes, per si la ruta conté un espai.

Amb això, l'script funciona invocat com a ./bin/informe-diari.sh, com a ~/veloz-ops/bin/informe-diari.sh, des del PATH o des de cron amb qualsevol directori de treball. Si a més vols seguir enllaços simbòlics fins al fitxer real, readlink -f (05-01) sobre ${BASH_SOURCE[0]} abans del dirname ho resol.

Si informe-diari.sh carrega comu.sh i també informe.sh, que al seu torn carrega comu.sh, el fitxer es processa dues vegades. Redefinir funcions és inofensiu, però un readonly duplicat provoca un error fatal sota mode estricte (VELOZ_VERSION: variable de només lectura). La solució és la mateixa idea que els include guards de C:

El return 0 a nivell superior d'un fitxer carregat amb source és legal i significa «acaba de llegir aquest fitxer». El :- és obligatori perquè l'script que la carrega té set -u (05-03) i la variable encara no existeix la primera vegada. El guionet baix inicial marca la variable com a interna.

Bash no té espais de noms: tot viu en un únic àmbit global. Si la teva llibreria defineix log() i la del company també, l'última carregada guanya silenciosament. El remei és un prefix:

Bash permet :: en noms de funció i queda molt llegible, però no és POSIX i algunes eines antigues s'hi ennueguen; veloz_ és l'opció segura. Tria'n un i sigues consistent. La distinció públic/privat és per conveni, no la imposa l'intèrpret: el guionet baix inicial és una promesa de «això pot canviar sense avís, no en depenguis». El que sí que pots controlar de debò és l'àmbit de les variables: tota variable dins d'una funció va amb local (04-02), i així no contamina l'script que la faci servir.

~/veloz-ops/etc/veloz-ops.conf existeix des del principi del curs amb permisos 600. La seva forma més simple és un fitxer d'assignacions (VELOZ_CSV=/srv/veloz/dades/enviaments.csv, VELOZ_LOG_NIVELL=info, VELOZ_CIUTATS="Valencia Sevilla Bilbao Madrid") que es carrega amb [[ -r "$BASE_DIR/etc/veloz-ops.conf" ]] && source "$BASE_DIR/etc/veloz-ops.conf". És còmode —admet comentaris, cometes, fins i tot $(...)— i té un risc que has de conèixer: source executa codi arbitrari. Una línia rm -rf ~ en aquest fitxer s'executa amb els teus permisos. Per això els 600 no són decoratius: si algú pot escriure al teu fitxer de configuració, pot executar el que vulgui com tu. Les implicacions completes es tracten a 08-03.

L'alternativa segura és analitzar clau=valor sense executar res, fent servir el que has après a 05-04:

Aquí es troben tres mòduls: la regex amb BASH_REMATCH de 05-04 (que a més descarta comentaris i línies buides en no encaixar), les expansions ${v%\"} de 04-04 i el bucle while read de 04-01. El filtre VELOZ_* impedeix que el fitxer redefineixi PATH o HOME, i printf -v assigna a la variable el nom de la qual és a $clau: la manera segura de fer assignació indirecta sense eval.

Tanquem aquí el disseny d'opcions començat a 03-05. Quan el mateix valor pot venir de quatre llocs, cal un ordre explícit i documentat, de menor a major prioritat:

El principi: com més a prop de l'usuari i del moment de l'execució, més prioritat. Implementar-ho és senzill si respectes l'ordre de càrrega, i : "${VAR:=valor}" és l'idioma per a «assigna només si és buida o no definida» —el := assigna, a diferència del :- que només substitueix, i el : inicial és l'ordre nul·la—, de manera que una variable d'entorn ja definida sobreviu:

La regla de repartiment en una frase: a bin/ va el que s'invoca, a lib/ el que es reutilitza, a etc/ el que canvia entre màquines i a logs/ el que es genera. És la mateixa lògica de l'FHS que vas veure a 01-03, aplicada a escala de projecte, i per això resulta familiar a qualsevol que obri el repositori. Un criteri pràctic per decidir on va una funció: si la necessitaria un script que no tingués res a veure amb informes, va a comu.sh; si només té sentit parlant d'enviaments i ciutats, va a informe.sh.

Fixa't en el que no hi ha: ni set -euo pipefail, ni shebang executable, ni una sola línia que actuï en carregar-se més enllà de la guarda i les constants. veloz_morir és l'única que crida exit, i és correcte perquè està pensada per fer-se servir des d'un executable, no des d'una sessió interactiva.

Aquest és el resultat de cinc mòduls. L'executable ja no implementa gairebé res: localitza la seva base, carrega les seves llibreries, resol la configuració, processa opcions, es protegeix amb flock i un trap, i despatxa. Tota la lògica reutilitzable viu a lib/. Quan escriguis arxivar-historic.sh, les tres primeres línies seran idèntiques i tindràs de franc el registre, els errors i les validacions.

Una llibreria ben feta es pot carregar en una sessió interactiva, i això és el que la fa verificable:

declare -F llista els noms de les funcions definides i type mostra el cos (01-04). Si en fer source apareix qualsevol sortida, hi ha codi de nivell superior que hi sobra. Per a proves automàtiques de debò —afirmacions, casos límit, informe de resultats— l'eina és bats, a 08-06. I shellcheck -x segueix els source per analitzar també les llibreries, a 08-05.

• source lib/comu.sh amb ruta relativa. Funciona al teu directori i falla des de cron o el PATH.
• Fer servir $0 per localitzar l'script. Dona bash amb bash script.sh i el fitxer equivocat dins d'una llibreria. Fes servir ${BASH_SOURCE[0]}.
• exit dins d'una llibreria carregada al teu shell. Tanca el teu terminal. Fes servir return.
• Codi de nivell superior a la llibreria, i en especial un set -euo pipefail: embruta la sortida i imposa la seva política a l'script que la carrega, potser sense que s'ho esperi.
• readonly sense guarda d'inclusió, que en carregar-se dues vegades dona error fatal, i funcions sense local, que esclafen variables de l'script que les crida setmanes després.
• Consell: documenta cada funció amb una línia # nom — què fa. Ús: nom <args> just a sobre. És el que llegiràs d'aquí a sis mesos, i el que permet generar l'ajuda del toolkit amb un simple grep '^# [a-z]' lib/*.sh.

Exercici 1. Escriu la capçalera completa d'arxivar-historic.sh (a bin/) que localitzi BASE_DIR de manera robusta, carregui lib/comu.sh, apliqui mode estricte i falli amb un missatge clar si la llibreria no és on hauria de ser.

Exercici 2. Afegeix a comu.sh una funció veloz_config que retorni el valor d'una clau de configuració respectant l'ordre de precedència (defecte < fitxer < entorn), amb guarda d'inclusió i sense fer servir eval.

Exercici 3. Divideix el toolkit: decideix per a cadascuna d'aquestes funcions si va a comu.sh, a informe.sh o al mateix executable, i justifica-ho: veloz_log_info, taula_ciutats, veloz_percentatge, acumular_dia, us, veloz_validar_data.

Solució 1.

La comprovació prèvia al source importa: sense ella, el missatge seria source: lib/comu.sh: No such file or directory, que no diu on s'ha buscat. El codi 78 (EX_CONFIG, de la taula de 05-03) és l'adequat: la instal·lació està malament, no les dades. I el missatge fa servir printf directe perquè veloz_log_error encara no existeix.

Solució 2.

${!clau} és l'expansió indirecta: obté el valor de la variable el nom de la qual és a $clau. És la lectura equivalent al printf -v de la secció 6, i totes dues eviten eval, que executaria el contingut del fitxer de configuració —justament el risc del qual fugim—. L'ordre de les tres branques és la taula de precedència.

Solució 3.

El criteri és una sola pregunta: ho necessitaria un script que no parli d'enviaments? Si la resposta és sí, va a comu.sh. us és el cas interessant: encara que tots els scripts en tinguin una, el seu contingut és diferent a cadascun, així que el que es pot compartir no és la funció sinó el conveni que existeixi.

source executa un fitxer al shell actual, i d'aquí en surt tota la resta: les funcions i variables que defineix queden disponibles, no cal shebang ni permís d'execució, i un exit mataria qui la carrega —dins d'una llibreria es fa servir return—. Una llibreria conté només definicions, sense codi que actuï, sense set -euo pipefail que imposi polítiques alienes i sense missatges en carregar-se. Es localitza amb BASE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)", mai amb $0 ni amb rutes relatives, perquè un script s'invoca des de qualsevol directori i des del PATH. Una guarda [[ -n ${_COMU_SH:-} ]] && return 0 evita la doble càrrega i l'error dels readonly duplicats, i un prefix veloz_ substitueix els espais de noms que Bash no té, amb el guionet baix inicial marcant el que és privat. La configuració viu a etc/veloz-ops.conf amb permisos 600 —perquè carregar-lo amb source executa el que contingui— o s'analitza com a clau=valor amb BASH_REMATCH i printf -v, i resol els seus conflictes amb una precedència explícita: defecte < fitxer < entorn < línia d'ordres. El resultat és ~/veloz-ops/ amb bin/, lib/, etc/ i logs/, i un informe-diari.sh que ja no implementa: orquestra.

Amb això es tanca el Mòdul 5, i amb ell la part del curs dedicada al que Bash sap fer per si mateix. El toolkit de Veloz Envíos és avui robust, segur amb els seus fitxers i processos, capaç de diagnosticar les seves pròpies fallades, precís en validar text, amo de la seva entrada i sortida, i modular. Però continua sent maldestre en un terreny concret: cada vegada que cal fer comptes per columnes sobre el CSV, encadena cut, sort, uniq i bucles que llegeixen el fitxer diverses vegades; cada vegada que cal reescriure text, falten eines; i quan la veloz-api deixi de ser un procés que es comprova amb pgrep i passi a ser una API que cal consultar, Bash sol no hi arriba.

Al Mòdul 6 entren les eines externes que multipliquen el que Bash sap fer: awk, que processa columnes i agrega en una sola passada el que avui et costa vint línies (06-01); sed, per transformar text en flux amb les regex que ja domines (06-02); les ordres per interrogar el sistema —disc, memòria, usuaris, maquinari— (06-03); les eines de xarxa i el /dev/tcp que vam deixar apuntat (06-04); i curl amb jq per parlar amb la veloz-api i manejar JSON de debò, que és on el teu toolkit deixarà de llegir fitxers per començar a integrar-se amb la resta del sistema (06-05).