Concevoir des fonctions avec une portée locale et des codes de retour

Dans Bash, les variables sont globales par défaut. Une variable définie dans une fonction se propage dans la portée de l’appelant, sauf si vous la déclarez explicitement avec local. C’est une source courante de bogues subtils dans les scripts shell.

• Les fonctions sans local peuvent écraser silencieusement les variables de l’appelant.
• Les variables local sont détruites lorsque la fonction renvoie son résultat.
• Des limites de portée claires rendent les fonctions réutilisables et testables isolément.

Cette leçon vous apprend à écrire des fonctions autonomes : elles utilisent des variables local, communiquent leurs résultats par des codes de sortie et printf, et ne dépendent jamais d’un état global implicite.

Voici un exemple concret de fuite d'une variable globale. La fonction set_name définit une variable appelée result, ce qui écrase discrètement la propre variable result de l'appelant.

Exécutez ce script et observez la sortie inattendue : la variable result de l'appelant a disparu après l'appel de la fonction.

La commande intégrée local limite la portée d'une variable à la fonction englobante et aux fonctions qu'elle appelle. En dehors de la fonction, la variable n'est soit pas définie, soit conserve sa valeur précédente.

• local varname — déclare la variable sans lui attribuer de valeur.
• local varname="value" — déclare et attribue une valeur en une seule étape.
• local -i count=0 — déclare une variable locale de type entier.
• local -r PI=3.14159 — déclare une constante locale en lecture seule.

Bonne pratique : déclarez chaque variable à l'intérieur d'une fonction avec local, sauf si vous avez intentionnellement besoin qu'elle soit globale.

Les fonctions Bash ne peuvent pas return de chaînes de caractères : return définit uniquement un statut de sortie entier (0–255). Par convention :

• return 0 — réussite
• return 1 (ou toute valeur non nulle) — échec

L'appelant lit le statut de sortie avec $? immédiatement après l'appel, ou utilise directement la fonction dans une condition if. Les codes de sortie sont la manière idiomatique de signaler la réussite ou l'échec d'une fonction.

Lorsqu'une fonction doit renvoyer un résultat textuel, la méthode standard consiste à l'écrire sur la sortie standard, puis à le récupérer avec une substitution de commande $(). Il est préférable d'utiliser printf plutôt que echo, car :

• printf n'ajoute pas de saut de ligne final par défaut (sauf si vous incluez \n).
• Le comportement de printf est cohérent et défini par POSIX ; celui de echo varie selon les interpréteurs de commandes.
• La substitution de commande supprime les sauts de ligne finaux ; printf '%s' "$value" est donc précis.

Une fonction bien conçue peut à la fois afficher un résultat (en cas de réussite) et signaler un échec (au moyen du code de sortie). L'appelant décide de la marche à suivre en fonction du code de sortie avant de faire confiance à la sortie.

Le modèle ci-dessous est largement utilisé dans les bibliothèques Bash réelles :

• En cas de réussite : afficher le résultat avec printf et exécuter return 0.
• En cas d'échec : écrire un diagnostic sur la sortie d'erreur standard (et non sur la sortie standard), puis exécuter return 1.
• Écrire les erreurs sur la sortie d'erreur standard permet de conserver la sortie standard propre pour le chaînage.

La récursivité montre particulièrement clairement pourquoi local est indispensable. Chaque appel récursif reçoit sa propre copie indépendante de chaque variable local dans la pile d'appels. Sans local, chaque appel écraserait la même variable globale et produirait des résultats incorrects.

La fonction factorielle ci-dessous est sûre, car n et sub sont locaux à chaque cadre de pile.

La substitution de commande $() s'exécute dans un sous-interpréteur. Toute attribution de variable effectuée à l'intérieur est invisible pour l'interpréteur parent. Lorsque vous devez permettre à une fonction d'écrire dans une variable fournie par l'appelant sans utiliser de sous-interpréteur, utilisez une référence de nom (local -n), disponible dans Bash 4.3 et versions ultérieures.

• local -n ref="$1" fait de ref un alias de la variable dont le nom est stocké dans $1.
• Attribuer une valeur à ref à l'intérieur de la fonction modifie directement la variable de l'appelant.
• Cela évite un sous-interpréteur tout en conservant les détails d'implémentation dans une portée locale.

Dans les projets Bash réels, les fonctions réutilisables sont réparties dans des fichiers de bibliothèque chargés par les scripts avec source (ou l'opérateur point .). Règles de conception d'une bonne bibliothèque :

• Toute variable à l'intérieur d'une fonction de bibliothèque doit être local.
• Les fonctions de bibliothèque n'exécutent jamais exit : elles exécutent return, afin que l'appelant reste actif.
• Utilisez un préfixe d'espace de noms cohérent (par exemple str_, log_) pour éviter les collisions de noms.
• Protégez-vous contre les chargements multiples à l'aide d'une variable sentinelle.

Vous trouverez ci-dessous une bibliothèque minimale d'utilitaires pour les chaînes, qui respecte ces conventions.

Les fonctions qui reçoivent des arguments doivent les valider rapidement et renvoyer un code de sortie précis en cas d'entrée incorrecte. C'est le modèle de la clause de garde : échouer rapidement et clairement.

• Vérifiez le nombre d'arguments avec $#.
• Validez les types ou les formats avant d'effectuer le moindre travail.
• Affichez les messages de diagnostic uniquement sur la sortie d'erreur standard, jamais sur la sortie standard.
• Utilisez des codes de retour non nuls distincts (par exemple, 1 = arguments incorrects, 2 = fichier introuvable) afin que les appelants puissent réagir différemment selon le mode d'échec.

Voici un script complet et autonome qui montre tous les concepts de cette leçon utilisés ensemble :

• Des variables local dans chaque fonction.
• Des codes de sortie pour signaler la réussite ou l'échec.
• printf pour communiquer des résultats textuels.
• Les erreurs écrites sur la sortie d'erreur standard et les résultats sur la sortie standard.
• Des clauses de garde pour valider les arguments.

Étudiez le déroulement : parse_version extrait les données, version_ge les compare et main utilise les deux proprement.

Considérez la fonction Bash suivante. Quelle est la bonne manière de récupérer son résultat textuel dans l'appelant, et quelle affirmation concernant la variable tmp est vraie ?

transform() {
    local tmp="${1,,}"   # lowercase
    printf '%s' "$tmp"
    return 0
}

Dans cette leçon, vous avez appris à écrire des fonctions Bash propres, composables et sûres :

• Utilisez toujours local pour les variables à l'intérieur des fonctions afin d'éviter de polluer la portée de l'appelant.
• Utilisez les codes de sortie (return 0/1/N) pour signaler la réussite ou l'échec : ils s'intègrent naturellement à if, && et ||.
• Utilisez printf vers la sortie standard pour communiquer les résultats textuels ; récupérez-les avec $() dans l'appelant.
• Écrivez les erreurs sur la sortie d'erreur standard (>&2) afin de garder la sortie standard propre pour le flux de données et le chaînage.
• Utilisez local -n (référence de nom) lorsque vous devez écrire dans une variable fournie par l'appelant sans le coût d'un sous-interpréteur.
• Les clauses de garde (valider rapidement les arguments et retourner immédiatement en cas d'entrée incorrecte) rendent les fonctions robustes et explicites.
• Les fichiers de bibliothèque doivent être chargés, utiliser des préfixes d'espace de noms, ne jamais appeler exit et se protéger contre les chargements multiples.

Maîtriser ces modèles fait la différence entre des scripts ponctuels fragiles et des bases de code Bash professionnelles et faciles à maintenir.