nutools/doc/ulib_base.twp

# -*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8
##@creator: jclain
##@created: 27/04/2016 03:19
##@modifier: jclain
##@changecount: 1
##@tags:
##@title: ulib/base

!! {{{setyesval}}}
{{{
mettre la valeur normalisée de la valeur "oui" de $2 dans la variable $1
}}}
!! {{{normyesval}}}
{{{
remplacer la valeur de la variable $1 par la valeur normalisée de sa valeur "oui"
Si $2 est non vide, prendre cette valeur plutôt que la valeur de la variable $1
}}}
!! {{{normyesvals}}}
{{{
remplacer les valeur des variables $1..* par les valeurs normalisées
respectives de leur valeur "oui"
}}}
!! {{{quote_in}}}
{{{
Comme quote_arg pour une chaine lue sur stdin
}}}
!! {{{quote_sin}}}
{{{
Pour la chaine lue sur stdin, remplacer ' par '\''. Cela permet de protéger une
chaine à mettre entre quotes
}}}
!! {{{quote_sarg}}}
{{{
Dans la chaine $1, remplacer ' par '\''. Cette fonction utilise quote_sin,
puisque le shell a des difficultés à faire le rechercher/remplacer approprié
}}}
!! {{{quoted_sarg}}}
{{{
Dans la chaine $1, remplacer ' par '\'', et afficher la chaine entourée de
quotes
}}}
!! {{{quoted_sargs}}}
{{{
Comme quoted_sarg, mais tous les arguments sont quotés et affichés entourés de
quotes, ce qui permet de construire des arguments d'une ligne de commande
}}}
!! {{{set_array_cmd}}}
{{{
Afficher la commande permettant d'initialiser le tableau $1 avec les valeurs:
soit du tableau $2, soit de $3..$n si $2=="@"
S'il n'y a que l'argument $1, alors afficher la commande permettant de
recréer le tableau $1
}}}
!! {{{set_array}}}
{{{
Soit $1 un tableau à créer. Si $2=="@", créer le tableau $1 avec les valeurs
$3..$n. Sinon, créer le tableau $1 avec les valeurs du tableau $2.
Cette fonction n'existe que comme un pendant de set_var(), mais le véritable
intérêt est la fonction set_array_cmd(). cf array_copy() pour une version plus
efficace de la copie de tableaux
}}}
!! {{{array_count}}}
{{{
retourner le nombre d'éléments du tableau $1
}}}
!! {{{array_isempty}}}
{{{
tester si le tableau $1 est vide
}}}
!! {{{array_new}}}
{{{
créer un tableau vide dont le nom est $1
}}}
!! {{{array_add}}}
{{{
ajouter les valeurs $2..@ au tableau dont le nom est $1
}}}
!! {{{array_ins}}}
{{{
insérer les valeurs $2..@ au début du tableau dont le nom est $1
}}}
!! {{{array_del}}}
{{{
supprimer *les* valeurs $2 du tableau dont le nom est $1
}}}
!! {{{array_addu}}}
{{{
ajouter la valeur $2 au tableau dont le nom est $1, si la valeur n'y est pas
déjà. Retourner vrai si la valeur a été ajoutée
}}}
!! {{{array_set}}}
!! {{{array_insu}}}
{{{
insérer la valeur $2 au début du tableau tableau dont le nom est $1, si la
valeur n'y est pas déjà. Retourner vrai si la valeur a été ajoutée.
}}}
!! {{{array_fillrange}}}
{{{
Initialiser le tableau $1 avec les nombres de $2(=1) à $3(=10) avec un step de $4(=1)
}}}
!! {{{array_eq}}}
{{{
tester l'égalité des tableaux $1 et $2
}}}
!! {{{array_contains}}}
{{{
tester si le tableau dont le nom est $1 contient la valeur $2
}}}
!! {{{array_icontains}}}
{{{
tester si le tableau dont le nom est $1 contient la valeur $2, sans tenir
compte de la casse
}}}
!! {{{array_find}}}
{{{
si le tableau $1 contient la valeur $2, retourner l'index de la valeur. Si le
tableau $3 est spécifié, retourner la valeur à l'index dans ce tableau
}}}
!! {{{array_reverse}}}
{{{
Inverser l'ordre des élément du tableau $1
}}}
!! {{{array_replace}}}
{{{
dans le tableau $1, remplacer toutes les occurences de $2 par $3..*
}}}
!! {{{array_each}}}
{{{
Pour chacune des valeurs 'v' du tableau $1, appeler la fonction $2 avec les
arguments '$v $3..$n'
}}}
!! {{{array_map}}}
{{{
Pour chacune des valeurs 'v' du tableau $1, appeler la fonction $2 avec les
arguments '$v $3..$n', et remplacer la valeur par le résultat de la fonction
}}}
!! {{{first_value}}}
{{{
retourner la première valeur du tableau $1
}}}
!! {{{last_value}}}
{{{
retourner la dernière valeur du tableau $1
}}}
!! {{{array_copy}}}
{{{
copier le contenu du tableau $2 dans le tableau $1
}}}
!! {{{array_copy_firsts}}}
{{{
copier tous les valeurs du tableau $2(=$1) dans le tableau $1, excepté la dernière
}}}
!! {{{array_del_last}}}
!! {{{array_copy_lasts}}}
{{{
copier tous les valeurs du tableau $2(=$1) dans le tableau $1, excepté la première
}}}
!! {{{array_del_first}}}
!! {{{array_extend}}}
{{{
ajouter le contenu du tableau $2 au tableau $1
}}}
!! {{{array_extendu}}}
{{{
ajouter chacune des valeurs du tableau $2 au tableau $1, si ces valeurs n'y
sont pas déjà. Retourner vrai si au moins une valeur a été ajoutée
}}}
!! {{{array_extend_firsts}}}
{{{
ajouter toutes les valeurs du tableau $2 dans le tableau $1, excepté la dernière
}}}
!! {{{array_extend_lasts}}}
{{{
ajouter toutes les valeurs du tableau $2 dans le tableau $1, excepté la première
}}}
!! {{{array_xsplit}}}
{{{
créer le tableau $1 avec chaque élément de $2 (un ensemble d'éléments séparés
par $3, qui vaut ':' par défaut).
}}}
!! {{{array_split}}}
{{{
créer le tableau $1 avec chaque élément de $2 (un ensemble d'éléments séparés
par $3, qui vaut ':' par défaut). Les éléments vides sont ignorés. par exemple
"a::b" est équivalent à "a:b"
}}}
!! {{{array_from_path}}}
!! {{{array_from_xlines}}}
{{{
créer le tableau $1 avec chaque ligne de $2.
}}}
!! {{{array_from_lines}}}
{{{
créer le tableau $1 avec chaque ligne de $2. Les lignes vides sont ignorés.
}}}
!! {{{array_join}}}
{{{
afficher le contenu du tableau dont le nom est $1 sous forme d'une liste de
valeurs séparées par $2 (par défaut, une virgule)
Si $1=="@", alors les éléments du tableaux sont les arguments de la fonction à
partir de $3
Si $1!="@" et que le tableau est vide, afficher $3
Si $1!="@", $4 et $5 sont des préfixes et suffixes à rajouter à chaque élément
}}}
!! {{{array_mapjoin}}}
{{{
map le tableau $1 avec la fonction $2, puis afficher le résultat en séparant
chaque élément par $3. Les arguments et la sémantique sont les mêmes que pour
array_join en tenant compte de l'argument supplémentaire $2 qui est la
fonction pour array_map (les autres arguments sont décalés en conséquence)
}}}
!! {{{array_to_lines}}}
{{{
afficher le tableau dont le nom est $1 sous forme de lignes
}}}
!! {{{array_to_path}}}
{{{
afficher le tableau dont le nom est $1 sous forme d'une liste de chemins
séparés par ':')
}}}
!! {{{array_fix_paths}}}
{{{
Corriger les valeurs du tableau $1. Les valeurs contenant le séparateur
$2(=':') sont séparées en plusieurs valeurs. Par exemple avec le tableau
input=(a b:c), le résultat est input=(a b c)
}}}
!! {{{get_date_rfc822}}}
!! {{{get_date_fr}}}
!! {{{get_time_fr}}}
!! {{{parse_date}}}
!! {{{udelpath}}}
{{{
supprimer le chemin $1 de $2(=PATH)
}}}
!! {{{uaddpath}}}
{{{
Ajouter le chemin $1 à la fin, dans $2(=PATH), s'il n'y existe pas déjà
}}}
!! {{{uinspathm}}}
{{{
Ajouter le chemin $1 au début, dans $2(=PATH), s'il n'y existe pas déjà
}}}
!! {{{uinspath}}}
{{{
S'assurer que le chemin $1 soit au début de $2(=PATH)
}}}
!! {{{withpath}}}
{{{
tester si le chemin est relatif à . ou à .., ou est absolu. i.e 'withpath a/b'
renvoie faux alors que 'withpath ./a/b' renvoie vrai
}}}
!! {{{withext}}}
{{{
tester si le fichier a une extension
}}}
!! {{{normpath}}}
{{{
normaliser le chemin $1, qui est soit absolu, soit relatif à $2 (qui vaut
$(pwd) par défaut)
}}}
!! {{{abspath}}}
{{{
Retourner un chemin absolu vers $1. Si $2 est non nul et si $1 est un chemin
relatif, alors $1 est exprimé par rapport à $2, sinon il est exprimé par
rapport au répertoire courant.
Si le chemin n'existe pas, il n'est PAS normalisé. Sinon, les meilleurs
efforts sont faits pour normaliser le chemin.
}}}
!! {{{parentdirs}}}
{{{
Obtenir la liste de tous les parents du répertoire $2 dans le tableau $1, du
répertoire $2 vers la racine. Si $3 commence par 'r' (comme reverse), l'ordre
est inversé: le tableau contient les répertoire de la racine vers $2.
}}}
!! {{{ppath}}}
{{{
Dans un chemin *absolu*, remplacer "$HOME" par "~" et "$(pwd)/" par "", afin
que le chemin soit plus facile à lire. Le répertoire courant est spécifié par
$2 ou $(pwd) si $2 est vide
}}}
!! {{{relpath}}}
{{{
Afficher le chemin relatif de $1 par rapport à $2. Si $2 n'est pas spécifié,
on prend le répertoire courant. Si $1 ou $2 ne sont pas des chemins absolus,
il sont transformés en chemins absolus par rapport à $3. Si $1==$2, retourner
une chaine vide
}}}
!! {{{relpathx}}}
{{{
Comme relpath, mais pour un chemin vers un exécutable qu'il faut lancer:
s'assurer qu'il y a une spécification de chemin, e.g. ./script
}}}
!! {{{withinpath}}}
{{{
Tester si le chemin absolu $2 se trouve dans le chemin absolu "$1" (appelée
barrière). Soit un chemin P, on considère que P est dans P. Si ce comportement
n'est pas souhaité, $3(=N) doit valoir O, auquel cas P est dans Q implique que
P != Q.
}}}
!! {{{safe_abspath}}}
{{{
Afficher le chemin absolu de $1, par rapport à $2, si et seulement si le
chemin résultat ne se trouve pas en dehors de la barrière $3. Si $2 n'est pas
spécifié, prendre le répertoire courant. S'il est relatif, l'exprimer par
rapport au répertoire courant. Si $3 est relatif, l'exprimer par rapport à $2.
Si le chemin résultat est sité en dehors de la barrière, ne rien afficher et
retourner un code d'erreur.
Si le chemin $1 n'existe pas, il n'est PAS normalisé. Sinon, les meilleurs
efforts sont faits pour normaliser le chemin résultat.
}}}
!! {{{safe_relpath}}}
{{{
Afficher le chemin relatif de $1 par rapport à $2 si et seulement si le chemin
résultat ne se trouve pas en dehors de la barrière $3. Si $2 n'est pas
spécifié, prendre le répertoire courant. S'il est relatif, l'exprimer par
rapport au répertoire courant. Si $3 est relatif, l'exprimer par rapport à $2.
Si le chemin résultat est sité en dehors de la barrière, ne rien afficher et
retourner un code d'erreur.
}}}
!! {{{splitwcs}}}
{{{
Découper un nom de chemin $1 entre la partie sans wildcards, qui est placée dans
la variables $2(=basedir), et la partie avec wildcards, qui est placée dans la
variable $3(=filespec)
}}}
!! {{{deref}}}
{{{
Retourner un chemin absolu vers le fichier $1, dans lequel toutes les
composantes "lien symbolique" ont été supprimées.
DEPRECATED: Cette fonction est dépréciée. Utiliser à la place readlinkm()
}}}
!! {{{readlinka}}}
{{{
Afficher un chemin absolu vers la destination du fichier $1. Si $1 n'est pas
un lien, afficher simplement le chemin du fichier
}}}
!! {{{readlinkm}}}
{{{
Retourner un chemin absolu vers le fichier $1, dans lequel toutes les
composantes "lien symbolique" ont été supprimées. Il n'est pas requis que les
composantes du chemin existent.
}}}
!! {{{path_if_test}}}
{{{
afficher un chemin si le fichier $2 existe (en utilisant l'opérateur $1) dans
l'un des chemins absolus $4..n. si $3==relative, afficher le chemin relatif,
sinon le chemin absolu. note: $3 peut être de la forme relative:path, auquel
cas le chemin affiché est exprimé relativement à path
}}}
!! {{{update_link}}}
{{{
mettre à jour le lien $2 pour qu'il pointe vers le fichier $1
}}}
!! {{{update_links}}}
{{{
Mettre à jour les liens $2..@ pour qu'ils pointent vers la nouvelle
destination $1
}}}
!! {{{move_link}}}
{{{
Déplacer le lien $1 vers $2, et mettre à jour la destination du lien si
elle est exprimée de façon relative
Si $1 n'est pas un lien, le déplacer normalement avec mv
}}}
!! {{{copy_link}}}
{{{
Copier le lien $1 vers $2, et mettre à jour la destination du lien si
elle est exprimée de façon relative
Si $1 n'est pas un lien, le copier normalement avec cp
}}}
!! {{{array_find_links}}}
{{{
Chercher dans le répertoire $3 (qui est par défaut le répertoire courant)
les liens vers le fichier $2, et ajouter leurs chemins absolus dans le
tableau $1
}}}
!! {{{list_links}}}
{{{
Chercher dans le répertoire $2 les liens vers le fichier $1, et les
afficher, un par ligne.
}}}
!! {{{move_file}}}
{{{
Déplacer le fichier $1 vers $2, et mettre à jour les liens $3..@ pour
qu'ils pointent vers la nouvelle destination
}}}
!! {{{get_nblines}}}
{{{
Afficher le nombre de lignes d'un fichier
}}}
!! {{{mktempf}}}
{{{
générer un fichier temporaire et retourner son nom
}}}
!! {{{mktempd}}}
{{{
générer un répertoire temporaire et retourner son nom
}}}
!! {{{mkdirof}}}
{{{
Créer le répertoire correspondant à un fichier
}}}
!! {{{cp_a}}}
{{{
copier des fichiers en gardant le maximum de propriétés
}}}
!! {{{cp_R}}}
{{{
copier des fichiers récursivement, en suivant les liens symboliques
}}}
!! {{{quietgrep}}}
{{{
tester la présence d'un pattern dans un fichier
}}}
!! {{{quietdiff}}}
{{{
tester si deux fichiers sont identiques
}}}
!! {{{testsame}}}
{{{
tester si deux fichiers sont identiques/différents
}}}
!! {{{testdiff}}}
!! {{{testupdated}}}
{{{
test si $2 n'existe pas ou si $1 est différent de $2
}}}
!! {{{testnewer}}}
{{{
test si $2 n'existe pas ou si $1 est plus récent que $2
}}}
!! {{{ps_all}}}
{{{
afficher tous les processus avec le maximum d'informations
}}}
!! {{{progexists}}}
{{{
tester l'existence d'un programme dans le PATH
}}}
!! {{{has_python}}}
{{{
tester la présence de python
}}}
!! {{{has_gawk}}}
{{{
tester la présence de gnuawk
}}}
!! {{{is_root}}}
{{{
tester si on est root
}}}
!! {{{source_ifexists}}}
{{{
sourcer un fichier s'il existe
}}}
!! {{{is_running}}}
{{{
tester si un programme dont on donne le PID tourne
}}}
!! {{{sedi}}}
{{{
Lancer sed sur un fichier en le modifiant en place
}}}
!! {{{csort}}}
{{{
Lancer sort avec LANG=C pour éviter les problèmes avec la locale. en effet,
avec LANG!=C, sort utilise les règles de la locale pour le tri, et par
exemple, avec LANG=fr_FR.UTF-8, la locale indique que les ponctuations doivent
être ignorées.
}}}
!! {{{lsort}}}
!! {{{cgrep}}}
{{{
Lancer grep avec LANG=C pour éviter les problèmes avec la locale. cf csort
pour une explication.
}}}
!! {{{lgrep}}}
!! {{{csed}}}
{{{
Lancer sed avec LANG=C pour éviter les problèmes avec la locale. cf csort pour
une explication.
}}}
!! {{{lsed}}}
!! {{{cawk}}}
{{{
Lancer awk avec LANG=C pour éviter les problèmes avec la locale. cf csort pour
une explication.
}}}
!! {{{lawk}}}
!! {{{cdiff}}}
{{{
Lancer diff avec LANG=C pour éviter les problèmes avec la locale. cf csort
pour une explication.
}}}
!! {{{ldiff}}}
!! {{{fix_mode}}}
{{{
Si le fichier $1 n'est pas writable, le rendre writable temporairement. Si
nécessaire, le fichier est créé.
Cette fonction s'utilise de cette façon:
mode="$(fix_mode file)"
...
unfix_mode file "$mode"
}}}
!! {{{unfix_mode}}}
{{{
Restaurer le mode $2 du fichier $1 traité par fix_mode
}}}
!! {{{get_mode}}}
{{{
Obtenir le mode du fichier $1, en le créant si nécessaire. A utiliser avec
unfix_mode pour restaurer le mode d'un fichier qui a été traité avec un
fichier temporaire intermédiaire
}}}
!! {{{rm_maybe}}}
{{{
Supprimer les fichiers dont on donne la liste. Si aucun fichier n'est
spécifié, cette fonction est un NOP
}}}
!! {{{cpdir}}}
{{{
copier un fichier dans un répertoire, ou le contenu d'un répertoire dans un
autre répertoire, que le répertoire source soit un lien symbolique ou
non. Cette fonction existe parce que le comportement de "cp_a src dest" n'est
pas consistant selon les plateformes, surtout si src est un lien symbolique
sur un répertoire: parfois on copie le lien, parfois on copie le contenu du
répertoire, parfois on copie le répertoire...
La copie est faite avec rsync si possible. Les options du tableau
__CPDIR_RSYNC_ARGS sont rajoutées aux options standard de rsync.
}}}
!! {{{cpnovcs}}}
{{{
copier le fichier/répertoire $1 *dans* le *répertoire* $2 avec rsync. Les
options du tableau __CPNOVCS_RSYNC_ARGS sont rajoutées aux options standard
de rsync.
Si $1 est un répertoire, la copie est faite en ignorant les sous-répertoires
de VCS (.svn, CVS). En ce qui concerne les répertoire de VCS, git aussi est
supporté, mais uniquement s'il est à la racine du transfert.
Si $1 se termine par un '/', c'est le contenu du répertoire qui est copié, pas
le répertoire lui-même. Si rsync n'est pas trouvé sur le système, alors on
fait une copie standard qui inclue les répertoires de VCS.
}}}
!! {{{cpvcs}}}
{{{
comme cpnovcs, mais ne pas ignorer les répertoires de VCS
}}}
!! {{{cpdirnovcs}}}
{{{
Le pendant de cpdir, mais en ignorant les sous-répertoires de VCS: copier le
contenu du répertoire $1 dans le répertoire $2
}}}
!! {{{doinplace}}}
{{{
Filtrer le fichier $1 à travers la commande $2..$*, puis remplacer le fichier
s'il n'y a pas eu d'erreur. Retourner le code d'erreur de la commande. Si $1
n'est pas spécifié ou vaut -, filtrer l'entrée standard vers la sortie
standard.
La variante doinplacef remplace le fichier quelque soit le code de retour de
la commande. A utiliser avec des commandes comme grep qui peuvent retourner
FAUX s'ils ne trouvent pas le motif
}}}
!! {{{doinplacef}}}
!! {{{stripnl}}}
{{{
Supprimer les caractères de fin de ligne de la chaine en entrée
}}}
!! {{{nl2lf}}}
!! {{{nl2crlf}}}
!! {{{nl2cr}}}
!! {{{list_all}}}
{{{
Lister les fichiers ou répertoires du répertoire $1, un par ligne
Les répertoires . et .. sont enlevés de la liste
$1=un répertoire dont le contenu doit être listé
$2..@=un ensemble de patterns pour le listage
}}}
!! {{{list_files}}}
{{{
Lister les fichiers du répertoire $1, un par ligne
$1=un répertoire dont le contenu doit être listé.
$2..@=un ensemble de patterns pour le listage
}}}
!! {{{list_dirs}}}
{{{
Lister les répertoires du répertoire $1, un par ligne
Les répertoires . et .. sont enlevés de la liste
$1=un répertoire dont le contenu doit être listé.
$2..@=un ensemble de patterns pour le listage
}}}
!! {{{array_lsall}}}
{{{
Lister les fichiers avec `list_all $2 $3...`, et les mettre dans le
tableau $1. Le tableau contient les chemins complets, par seulement les
noms comme avec list_all
}}}
!! {{{array_lsdirs}}}
{{{
Lister les fichiers avec `list_dirs $2 $3...`, et les mettre dans le
tableau $1. Le tableau contient les chemins complets, par seulement les
noms comme avec list_dirs
}}}
!! {{{array_lsfiles}}}
{{{
Lister les fichiers avec `list_files $2 $3...`, et les mettre dans le
tableau $1. Le tableau contient les chemins complets, par seulement les
noms comme avec list_files
}}}
!! {{{filter_empty}}}
{{{
Filtrer l'entrée standard en enlevant les lignes vides
}}}
!! {{{filter_vcspath}}}
{{{
L'entrée standard étant une liste de chemins, filtrer les fichiers et
répertoire qui ont un rapport avec subversion ou git
}}}
!! {{{merge_contlines}}}
{{{
Avec les lignes lues sur stdin, fusionner celles qui se terminent par \ avec
les suivantes.
}}}
!! {{{filter_comment}}}
{{{
Filtrer un fichier de configuration lu sur stdin en enlevant les commentaires
et les lignes vides.
Avec $1==-m, fusionner les lignes qui se terminent par \ avec les suivantes
Comme filter_conf(), les commentaires doivent être sur une ligne à part.
Contrairement à filter_conf, il n'est pas nécessaire que le caractère '#' soit
en début de ligne: il peut apparaitre après des espaces et des tabulations. De
même, une ligne qui ne contient que des espaces et des tabulations est
considérée comme vide.
}}}
!! {{{filter_conf}}}
{{{
filtrer un fichier de configuration lu sur stdin en enlevant les commentaires
et les lignes vides. Une ligne n'est considérée commentaire que si '#' est un
première position. Utiliser filter_comment() si les commentaire peuvent
commencer par des caractères espace et tabulation.
Si $1==-m, fusionner les lignes qui se terminent par \ avec les suivantes
}}}
!! {{{is_archive}}}
{{{
tester si l'extension d'un fichier indique que c'est une archive
}}}
!! {{{extract_archive}}}
{{{
Extraire le contenu de l'archive $1 dans le répertoire ${2:-.}
}}}
!! {{{get_archive_basename}}}
{{{
Obtenir le nom de base de l'archive $1
}}}
!! {{{get_archive_appname}}}
{{{
Obtenir le nom probable de l'application ou du framework contenu dans
l'archive $1, e.g:
get_archive_versionsuffix app-0.1.tgz
--> app
}}}
!! {{{get_archive_versionsuffix}}}
{{{
Obtenir la valeur probable de la version de l'application ou du framework
contenu dans l'archive $1, avec le caractère de séparation, e.g:
get_archive_versionsuffix app-0.1.tgz
--> -0.1
}}}
!! {{{get_archive_version}}}
{{{
Obtenir la valeur probable de la version de l'application ou du framework
contenu dans l'archive $1, e.g:
get_archive_versionsuffix app-0.1.tgz
--> 0.1
}}}
!! {{{dump_usernames}}}
{{{
Placer dans le tableau $1 la liste des utilisateurs du système
Cette implémentation consulte /etc/passwd et liste tous les utilisateurs dont
le homedir se trouve dans /home, et dont l'uid est >=500
}}}
!! {{{resolv_ips}}}
{{{
Placer dans le tableau $1(=ips) la liste des adresses ip correspondant à
l'hôte $2. La résolution est effectuée avec la commande host.
}}}
!! {{{resolv_hosts}}}
{{{
Placer dans le tableau $1(=hosts) la liste des hôtes correspondant à
l'adresse ip $2. La résolution est effectuée avec la commande host.
}}}
!! {{{runscript_as}}}
{{{
Utiliser bash pour lancer le script $2 avec les arguments $3..$n afin qu'il
tourne avec les droits d'un autre user $1(=root). Si $2=exec, utiliser exec
pour lancer le script et ses arguments qui commencent à partir de $3, ce qui
fait que cette fonction ne retourne pas.
Attention! cette fonction ne teste pas avec si on est déjà le user $1. Il y a
donc un risque de boucle infinie si on ne teste pas le user courant.
}}}
!! {{{runscript_as_root}}}
{{{
Utiliser bash pour lancer le script $1 avec les arguments $2..$* avec les
droits de root. Si on est déjà en root, le script est simplement lancé. Sinon,
utiliser runscript_as pour lancer le script avec les droits de root.
}}}
!! {{{run_as}}}
{{{
Relancer le script courant afin qu'il tourne avec les droits d'un autre user
$1(=root)
Attention! cette fonction ne teste pas avec si on est déjà ce user. Il y a
donc un risque de boucle infinie si on ne teste pas le user courant.
Il faut lancer cette fonction avec les arguments du script en cours. Par
exemple::
run_as root "$@"
Si $2=--noexec, on n'utilise pas la fonction exec, ce qui fait que la fonction
retourne. Sinon, on peut considérer que cette fonction ne retourne jamais
}}}
!! {{{run_as_root}}}
{{{
relancer le script courant afin qu'il tourne en root si on est pas en déjà
root. Sinon, cette fonction est un nop.
}}}
!! {{{check_user}}}
{{{
Vérifier si le user courant est l'un des users $1..*
}}}
!! {{{ensure_user}}}
{{{
Vérifier si le user courant est l'un des users $1..N où N est la position du
premier "--". Si ce n'est pas le cas et que l'on est root, relancer le script
avec ce user grâce à la fonction run_as()
Retourner 1 si ce n'était pas le bon user. Retourner 10 si ce n'était pas le
bon user et que l'on n'est pas root (donc impossible à priori de relancer le
script avec le bon user). Retourner 11 si l'utilisateur a choisi de ne pas
lancer le script avec le bon utilisateur
A utiliser de cette manière:
if ensure_user users... -- args; then
# ... on est avec le bon user; faire les opérations
else
# ... ce code n'est exécuté que si une erreur s'est produite, ou si ce
# n'était pas le bon user et que l'option --noexec est utilisée
fi
}}}
!! {{{check_hostname}}}
{{{
Vérifier si le hostname courant est l'un des hôtes $1..*
localhost matche toujours
}}}
!! {{{check_userhostname}}}
{{{
Vérifier si le hostname et éventuellement le user courant sont l'un des
arguments $1..*
Chaque argument est de la forme [user@]host, mais le test ne tient compte que
du nom de l'hôte, sans tenir compte du domaine. Si le user n'est pas spécifié,
le test ne porte que sur hostname.
}}}
!! {{{ensure_hostname}}}
{{{
Vérifier si le hostname et le user courant sont l'un des arguments $1..*
Chaque argument est de la forme [user@]host, mais le test ne tient compte que
du nom de l'hôte, sans tenir compte du domaine.
Si user est spécifié:
- Si on est sur le bon hôte mais pas le bon user, ensure_user est lancé avec
l'argument approprié pour relancer le script
Si l'argument était de la forme userhost:path, le répertoire courant est
changé avant de lancer le script avec le bon utilisateur.
Sinon (si user n'est pas spécifié):
- Si on n'est pas sur le bon hôte, après confirmation le script est lancé avec
ssh sur l'hôte distant avec le user spécifié (qui vaut par défaut root). Ce
script DOIT exister sur l'hôte distant avec le même chemin.
Si l'argument était de la forme userhost:path, le répertoire courant distant
est changé avant de lancer le script
Si on est avec le bon user sur le bon hôte, le répertoire courant n'est jamais
changé.
Retourner 1 si ce n'était pas le bon user. Retourner 10 si ce n'était pas le
bon user et que l'on n'est pas root (donc impossible à priori de relancer le
script avec le bon user). Retourner 11 si l'utilisateur a choisi de ne pas
lancer le script sur l'hôte distant. Retourner 12 si une erreur s'est produite
avec ssh.
A utiliser de cette manière:
if ensure_hostname user@host... -- args; then
# ... on est [avec le bon user] sur le bon hôte; faire les opérations
else
# ... ce code n'est exécuté que si une erreur s'est produite, ou si ce
# n'était pas le bon user et que l'option --noexec est utilisée
fi
}}}
!! {{{sqvals}}}
!! {{{quoted_values}}}
!! {{{formatcsv}}}
!! {{{awkdef}}}
{{{
Afficher un script à insérer au début d'un script awk. Ce script définit dans
une section BEGIN{} les variables donnés en arguments, et avec l'option -f,
des fonctions utiles. Si une valeur ne ressemble pas à une définition de
variable, l'analyse des variables s'arrête et le reste des arguments est
inséré tel quel. Cette fonction peut être utilisée de cette manière:
awk "$(awkdef -f var=value... 'script awk')"
Normalement, les variables définies sont scalaires, avec une syntaxe de la
forme var[:type]=value. type peut valoir str ou int, pour forcer le type de la
variable créée dans awk.
Il est possible d'utiliser la syntaxe awk_array[@]=bash_array ou array[@] (qui
est équivalente à array[@]=array) pour initialiser le tableau awk_array, qui
contiendra toute les valeurs du tableau nommé bash_array, avec les indices de
1 à N, N étant le nombre d'éléments du tableau bash_array. La variable
awk_array_count est aussi initialisée, et contient le nombre d'éléments du
tableau
La syntaxe "awk_array[@]=<\n..." permet de spécifier les valeurs du tableau,
une par ligne, e.g:
$'values[@]=<\nvalue1\nvalue2'
pour un tableau values qui contiendra deux valeurs: value1 et value2
Avec l'option -f, des fonctions supplémentaires sont définies. Elles sont
décrites dans le module awk.
}}}
!! {{{lawkrun}}}
{{{
wrapper pour lancer awk avec un script préparé par awkdef. Les définitions et
les arguments sont séparés par --, e.g.
awkrun var0=value0 var1=value1 script -- input0 input1
}}}
!! {{{cawkrun}}}
!! {{{awkrun}}}
!! {{{lf_trylock}}}
{{{
USAGE
lf_trylock [-h max_hours] /path/to/lockfile
OPTIONS
lockfile
fichier qui doit contenir le verrou
-h max_hours
Nombre d'heures (par défaut 4) au bout duquel afficher stale
Sinon, afficher locked
Retourne 0 si le verrou a été placé correctement. Il ne faut pas oublier de
supprimer le fichier. Le mieux est de le faire supprimer automatiquement par
autoclean:
lockfile=...
case "$(lf_trylock "$lockfile")" in
locked) ...;;
stale) ...;;
esac
autoclean "$lockfile"
Sinon, retourner 1 et afficher l'une des deux valeurs suivantes:
- stale si le verrou a déjà été placé, depuis au moins max_hours heures
- locked si le verrou a déjà été placé
- retry si une erreur s'est produite pendant la pose du verrou ou sa
lecture. Cela peut se produire si les droits ne sont pas suffisants pour
écrire dans le répertoire destination, ou si le fichier a été supprimé
avant sa lecture (race-condition). Dans ce dernier cas, reessayer permettra
d'acquérir le verrou
}}}
!! {{{pidfile_set}}}
{{{
USAGE
pidfile_set [-p pid] /path/to/pidfile
OPTIONS
pidfile
fichier qui doit contenir le pid du script
-p pid
spécifier le pid. par défaut, utiliser $$
-r  si pidfile existe mais que le processus ne tourne plus, faire
comme si le fichier n'existe pas.
Retourner 0 si le pid a été correctement écrit dans le fichier. Ce fichier
sera supprimé automatiquement en fin de script
Retourner 1 si le fichier existe déjà et que le processus est en train de
tourner.
Retourner 2 si le fichier existe déjà mais que le processus ne tourne plus.
Retourner 10 si autre erreur grave s'est produite (par exemple, s'il manque le
chemin vers pidfile, ou si le fichier n'est pas accessible en écriture.)
}}}
!! {{{pidfile_check}}}
{{{
USAGE
pidfile_check /path/to/pidfile
OPTIONS
pidfile
fichier qui doit contenir le pid d'un processus
Cette fonction permet de vérifier si le processus associé à un fichier de pid
est en train de tourner.
Retourner 0 si le fichier de pid existe et que le process du pid spécifié est
en train de tourner. Retourner 1 sinon.
Retourner 10 si erreur grave s'est produite (par exemple, s'il manque le
chemin vers pidfile, ou si le fichier n'est pas accessible en lecture.)
}}}
!! {{{page_maybe}}}
{{{
Utiliser less, si possible, pour afficher le flux en entrée. Si le terminal
n'est pas interactif ou si le nombre de lignes en entrée est inférieur au
nombre de lignes du terminal, afficher simplement le flux.
Les arguments de cette fonction sont passés à less
}}}
!! {{{utools_local}}}
{{{
Afficher les commandes pour rendre locales certaines variables en fonction des
arguments:
- opts rend locale args, pour utiliser parse_opts() à l'intérieur d'une
fonction.
- verbosity et interaction rendent respectivement locales __verbosity et
__interaction. Ceci est utile pour pouvoir appeler sans risque de pollution
de l'environnement une fonction qui utilise parse_opts() avec les
définitions de PRETTYOPTS.
Si aucun arguments n'est fourni, toutes les définitions sont affichées.
}}}
!! {{{stdredir}}}
{{{
Lancer la commande $4..@ en redirigeant stdin depuis $1, stdout vers $2,
stderr vers $3. Si $1 est vide ou vaut /dev/stdin, la redirection n'est
pas faite. Si $2 est vide ou vaut /dev/stdout, la redirection n'est pas
faite. Si $3 est vide ou vaut /dev/stderr, la redirection n'est pas faite.
Cette fonction existe parce que sur certaines versions de bash, il semble
que les redirections /dev/std* ne sont pas traitées de façon particulière.
De plus, sur des technologies telles que OpenVZ, les chemins /dev/std* ne
sont pas créés (parce que /proc/self/fd/* n'est pas accessible). Donc,
dans de rares cas où le script tourne sur OpenVZ avec une version de bash
qui est buggée, la redirection n'est pas faite correctement.
}}}
!! {{{isatty}}}
{{{
tester si STDOUT n'est pas une redirection
}}}
!! {{{in_isatty}}}
{{{
tester si STDIN n'est pas une redirection
}}}
!! {{{out_isatty}}}
{{{
tester si STDOUT n'est pas une redirection
}}}
!! {{{err_isatty}}}
{{{
tester si STDERR n'est pas une redirection
}}}
!! {{{die}}}
!! {{{die_unless}}}
{{{
Afficher $-1 et quitter le script avec die() si la commande $1..-2 retourne
FAUX
}}}
!! {{{eerror_unless}}}
{{{
Afficher $-1 avec eerror() et retourner $? si la commande $1..-2 retourne FAUX
}}}
!! {{{die_if}}}
{{{
Afficher $-1 et quitter le script avec die() si la commande $1..-2 retourne
VRAI
}}}
!! {{{eerror_if}}}
{{{
Afficher $-1 avec eerror() et retourner le code d'erreur 1 si la commande
$1..-2 retourne VRAI
}}}
!! {{{noerror}}}
{{{
lancer la commande "$@" et masquer son code de retour
}}}
!! {{{noout}}}
{{{
lancer la commande "$@" en supprimant sa sortie standard
}}}
!! {{{noerr}}}
{{{
lancer la commande "$@" en supprimant sa sortie d'erreur
}}}
!! {{{tooenc}}}
{{{
Transformer la valeur $1 de l'encoding $2(=$OENC) vers l'encoding de sortie
$3=($UTOOLS_OUTPUT_ENCODING)
}}}
!! {{{uecho}}}
!! {{{tooenc_}}}
{{{
Transformer la valeur $1 de l'encoding $2(=$OENC) vers l'encoding de sortie
$3=($UTOOLS_OUTPUT_ENCODING)
}}}
!! {{{uecho_}}}
!! {{{toienc}}}
{{{
Transformer la valeur $1 de $2(=$IENC) vers l'encoding d'entrée
$3(=$UTOOLS_INPUT_ENCODING)
}}}
!! {{{uread}}}
{{{
Lire une valeur sur stdin et la placer dans la variable $1. On assume que la
valeur en entrée est encodée dans l'encoding d'entrée par défaut
}}}
!! {{{stooenc}}}
{{{
Transformer la valeur lue sur stdin de $OENC vers l'encoding de sortie par
défaut ($UTOOLS_OUTPUT_ENCODING)
}}}
!! {{{stoienc}}}
{{{
Transformer la valeur lue sur stdin de $IENC vers l'encoding d'entrée par
défaut ($UTOOLS_INPUT_ENCODING)
}}}
!! {{{elogto}}}
{{{
Activer UTOOLS_EDATE et rediriger STDOUT et STDERR vers le fichier $1
Si deux fichiers sont spécifiés, rediriger STDOUT vers $1 et STDERR vers $2
Si aucun fichier n'est spécifié, ne pas faire de redirection
Si la redirection est activée, forcer l'utilisation de l'encoding UTF8
Si UTOOLS_ELOG_OVERWRITE=1, alors le fichier en sortie est écrasé. Sinon, les
lignes en sortie lui sont ajoutées
}}}
!! {{{set_verbosity}}}
!! {{{set_interaction}}}
!! {{{show_error}}}
{{{
tester respectivement si on doit afficher les messages d'erreur,
d'avertissement, d'information, de debug
}}}
!! {{{show_warn}}}
!! {{{show_info}}}
!! {{{show_verbose}}}
!! {{{show_debug}}}
!! {{{check_verbosity}}}
!! {{{get_verbosity_option}}}
!! {{{check_interaction}}}
!! {{{is_interaction}}}
!! {{{get_interaction_option}}}
!! {{{eflush}}}
{{{
Afficher les messages en attente
}}}
!! {{{eclearp}}}
{{{
Supprimer les message en attente
}}}
!! {{{eerror}}}
{{{
Afficher un message d'erreur
}}}
!! {{{ewarn}}}
{{{
Afficher un message d'avertissement
}}}
!! {{{enote}}}
{{{
Afficher un message d'information de même niveau qu'un avertissement
}}}
!! {{{ebanner}}}
{{{
Afficher un message très important encadré, puis attendre 5 secondes
}}}
!! {{{eimportant}}}
{{{
Afficher un message très important
}}}
!! {{{eattention}}}
{{{
Afficher un message important
}}}
!! {{{einfo}}}
{{{
Afficher un message d'information
}}}
!! {{{eecho}}}
{{{
Afficher un message d'information sans préfixe
}}}
!! {{{eecho_}}}
!! {{{edebug}}}
{{{
Afficher un message de debug
}}}
!! {{{trace}}}
{{{
Afficher la commande $1..@, la lancer, puis afficher son code d'erreur si une
erreur se produit
}}}
!! {{{trace_error}}}
{{{
Lancer la commande $1..@, puis afficher son code d'erreur si une erreur se
produit. La différence avec trace() est que la commande n'est affichée que si
une erreur se produit.
}}}
!! {{{etitle}}}
{{{
Afficher le titre $1, qui est le début éventuel d'une section. Les section
imbriquées sont affichées indentées. La section n'est pas terminée, et il faut
la terminer explicitement avec eend, sauf dans certains cas précis:
- Si $2..$* est spécifié, c'est une commande. Lancer la commande dans le
contexte de la section. Puis, la section est automatiquement terminée sauf si
l'option -s est spécifiée, auquel cas la section reste ouverte. Si l'option -p
est spécifiée, eclearp() est appelé pour purger les messages en attente
- Dans le cas contraire, l'option -s est ignorée: la section doit toujours
être terminée explicitement.
La fonction etitled() est comme etitle(), mais le titre n'est pas affiché
immédiatement. L'affichage effectif est effectué dès qu'une fonction e* est
utilisée. Ceci permet, avec la fonction eclearp(), de ne pas afficher de titre
pour une section vide.
}}}
!! {{{etitled}}}
!! {{{estep}}}
{{{
Afficher la description d'une opération. Cette fonction est particulièrement
appropriée dans le contexte d'un etitle.
Les variantes e (error), w (warning), n (note), i (info) permettent d'afficher
des couleurs différentes, mais toutes sont du niveau info.
}}}
!! {{{estepe}}}
!! {{{estepw}}}
!! {{{estepn}}}
!! {{{estepi}}}
!! {{{estep_}}}
!! {{{estepe_}}}
!! {{{estepw_}}}
!! {{{estepn_}}}
!! {{{estepi_}}}
!! {{{ebegin}}}
{{{
Afficher le message $1, qui décrit le début d'une opération. Cette fonction
débute une section, qu'il faut terminer avec eend.
Si $2..$* est spécifié, c'est une commande. Lancer la commande dans le
contexte de la section. Puis, la section est terminée automatiquement, sauf si
l'option -s est spécifiée, auquel cas la section reste ouverte.
}}}
!! {{{edot}}}
{{{
Afficher une étape d'une opération, matérialisée par un point '.' ou une
croix 'x' en cas de succès ou d'erreur. Cette fonction est particulièrement
appropriée dans le contexte d'un ebegin.
}}}
!! {{{edotw}}}
{{{
Afficher un avertissement comme étape d'une opération, matérialisée par une
lettre 'w' (typiquement de couleur jaune). Cette fonction est particulièrement
appropriée dans le contexte d'un ebegin.
}}}
!! {{{ewait}}}
{{{
Afficher les étapes d'une opération qui dure, matérialisées par des '+' toutes
les secondes tant que le processus $1 tourne.
A utiliser de cette manière:
ebegin "msg"
cmd &
ewait $!
eend
}}}
!! {{{eend}}}
{{{
Terminer une section.
Avec l'option -c, remettre à zéro toutes les informations de section
Si la section en cours est un ebegin, afficher la fin de l'opération: [ok] ou
[error] en fonction du code de retour de la dernière commande (ou de $1 si
cette valeur est donnée)
Si la section en cours est un etitle, marquer la fin de la section concernée
par le titre.
}}}
!! {{{elinedots}}}
{{{
Afficher un message comme avec ebegin "$1", puis afficher un point '.' pour
chaque ligne lue sur stdin. Cela permet de suivre une opération. En mode
DEBUG, afficher la ligne affichée plutôt qu'un point.
Si $2..$* sont spécifiés, lancer la commande et suivre sa sortie. Ainsi,
'elinedots msg cmd args' est un raccourci pour 'cmd args | elinedots msg'
}}}
!! {{{ask_yesno}}}
{{{
Afficher le message $1 suivi de [oN] ou [On] suivant que $2 vaut O ou N, puis
lire la réponse. Retourner 0 si la réponse est vrai, 1 sinon.
Si $1 est une option, elle est utilisée avec check_interaction pour savoir si
on est en mode interactif ou non. A ce moment-là, les valeurs sont décalées
($2=message, $3=default)
Si $2 vaut C, la valeur par défaut est N si on est interactif, O sinon
Si $2 vaut X, la valeur par défaut est O si on est interactif, N sinon
}}}
!! {{{read_value}}}
{{{
Afficher le message $1 suivi de la valeur par défaut [$3] si elle est non
vide, puis lire la valeur donnée par l'utilisateur. Cette valeur doit être non
vide si $4(=O) est vrai. La valeur saisie est placée dans la variable
$2(=value)
Si $1 est une option, elle est utilisée avec check_interaction pour savoir si
on est en mode interactif ou non. A ce moment-là, les valeurs sont décalées
($2=message, $3=variable, $4=default, $5=required)
En mode non interactif, c'est la valeur par défaut qui est sélectionnée. Si
l'utilisateur requière que la valeur soit non vide et que la valeur par défaut
est vide, afficher un message d'erreur et retourner faux
read_password() est comme read_value(), mais la valeur saisie n'est pas
affichée, ce qui la rend appropriée pour la lecture d'un mot de passe.
}}}
!! {{{read_password}}}
!! {{{simple_menu}}}
{{{
Afficher un menu simple dont les éléments sont les valeurs du tableau
$2(=options). L'option choisie est placée dans la variable $1(=option)
-t TITLE: spécifier le titre du menu
-m YOUR_CHOICE: spécifier le message d'invite pour la sélection de l'option
-d DEFAULT: spécifier l'option par défaut. Par défaut, prendre la valeur
actuelle de la variable $1(=option)
}}}
!! {{{actions_menu}}}
{{{
Afficher un menu dont les éléments sont les valeurs du tableau $4(=options),
et une liste d'actions tirées du tableau $3(=actions). L'option choisie est
placée dans la variable $2(=option). L'action choisie est placée dans la
variable $1(=action)
Un choix est saisi sous la forme [action]num_option
-t TITLE: spécifier le titre du menu
-m OPT_YOUR_CHOICE: spécifier le message d'invite pour la sélection de
l'action et de l'option
-M ACT_YOUR_CHOICE: spécifier le message d'invite dans le cas où aucune option
n'est disponible. Dans ce cas, seules les actions vides sont possibles.
-e VOID_ACTION: spécifier qu'une action est vide, c'est à dire qu'elle ne
requière pas d'être associée à une option. Par défaut, la dernière action
est classée dans cette catégorie puisque c'est l'action "quitter"
-d DEFAULT_ACTION: choisir l'action par défaut. par défaut, c'est la première
action.
-q QUIT_ACTION: choisir l'option "quitter" qui provoque la sortie du menu sans
choix. par défaut, c'est la dernière action.
-o DEFAULT_OPTION: choisir l'option par défaut. par défaut, prendre la valeur
actuelle de la variable $2(=option)
}}}
!! {{{autoclean}}}
{{{
Ajouter $1..$n à la liste des fichiers à supprimer à la fin du programme
}}}
!! {{{ac_cleanall}}}
{{{
Supprimer *tous* les fichiers temporaires gérés par autoclean tout de suite.
}}}
!! {{{ac_clean}}}
{{{
Supprimer les fichier temporaires $1..$* si et seulement s'ils ont été générés
par ac_set_tmpfile ou ac_set_tmpdir
}}}
!! {{{ac_set_tmpfile}}}
{{{
Créer un fichier temporaire avec le motif $2, l'ajouter à la liste des
fichiers à supprimer en fin de programme, et mettre sa valeur dans la
variable $1
En mode debug, si ($5 est vide ou ${!5} est une valeur vraie), et si $3 n'est
pas vide, prendre ce fichier au lieu de générer un nouveau fichier
temporaire. Si $4==keep, ne pas écraser le fichier $3 s'il existe.
}}}
!! {{{ac_set_tmpdir}}}
{{{
Créer un répertoire temporaire avec le motif $2, l'ajouter à la liste des
fichiers à supprimer en fin de programme, et mettre sa valeur dans la
variable $1
En mode debug, si ($4 est vide ou ${!4} est une valeur vraie), et si $3 n'est
pas vide, prendre ce nom de répertoire au lieu de créer un nouveau répertoire
temporaire
}}}
!! {{{debug_tee}}}
{{{
En mode debug, passer le flux à travers la commande 'tee "$@"'. Sinon, le flux
est passé inchangé.
}}}
!! {{{get_user_defaults_file}}}
{{{
Afficher le chemin vers le fichier utilisateur à éditer pour qu'il soit chargé
par 'set_defaults $1'. Ce fichier n'existe pas forcément; il faut peut-être le
créer.
}}}
!! {{{get_defaults_files}}}
{{{
Initialiser le tableau $1(=defaults) avec la liste des fichiers qui seraient
chargés par la commande 'set_defaults $2..N'
}}}
!! {{{set_defaults}}}
{{{
Pour chaque argument, sourcer /etc/default/$arg *et* (en priorité
~/etc/default.$HOSTNAME/$arg ou à défaut ~/etc/default/$arg) si ceux-ci
existent. *Sinon*, lire $scriptdir/lib/default/$arg si ce fichier existe
}}}
!! {{{myhost}}}
{{{
Afficher le nom d'hôte pleinement qualifié, en faisant appel à la commande
hostname. Par comparaison, $MYHOST est fourni par bash.
}}}
!! {{{myhostname}}}
{{{
Afficher le nom d'hôte sans domaine, en faisant appel à la commande
hostname. Par comparaison, $MYHOSTNAME est fourni par bash.
}}}