Initiation au Lua avec Scribunto/Chaînes de caractères

Début de la boite de navigation du chapitre

Nous allons, dans ce chapitre, étudier quelques fonctions préprogrammées permettant de faire quelques opérations sur les chaînes de caractères. Comme dans le chapitre précédent, nous ne rangerons pas nécessairement les fonctions dans l’ordre alphabétique.

fin de la boite de navigation du chapitre

Tous les exemples de ce chapitre seront rangés dans le Module:Chaine.

Généralités

Une chaîne de caractères se représente par un texte entouré de guillemet " ". L'affectation à une variable se présente ainsi :

phrase = "Je pense donc je suis"

Il est possible de connaître le nombre de caractères utilisés dans la chaîne de caractères en utilisant l'opérateur #

longueur = #"Je pense donc je suis"

longueur sera alors de type number et contiendra le nombre 21.

On peut aussi utiliser cet opérateur sur une variable de type string pour connaître la longueur de la chaîne de caractères qu'elle contient :

longueur = #phrase

Le caractère # ne marche pas sur l'unicode. Pour l'unicode, on utilisera la fonction mw.ustring.len

Sans rien y mettre, on peut initialiser une variable comme étant de type string en écrivant :

local mot = ""

On rappelle l’utilisation de l'opérateur .. permettant de concaténer deux chaînes de caractères.

phrase = "Je pense donc je suis"..", mais que suis-je ?"

La variable phrase contiendra alors la chaîne de caractères : "Je pense donc je suis, mais que suis-je ?"

La librairie String

La librairie String est constituée d'un ensemble de fonctions rangées dans une table nommée string. Nous commencerons donc par visualiser le contenu de cette table grâce au programme suivant :

local p = {}

function p.visuString(frame)
	reponse = ""
	for index, objet in pairs(string) do
		reponse = reponse.."<br />À la clé '''"..index.."''', on trouve un objet de type : "..type(objet)
	end
	return reponse
end

return p

{{#invoke:Chaine|visuString}} nous donne :
À la clé sub, on trouve un objet de type : function
À la clé find, on trouve un objet de type : function
À la clé gsub, on trouve un objet de type : function
À la clé gmatch, on trouve un objet de type : function
À la clé gfind, on trouve un objet de type : function
À la clé byte, on trouve un objet de type : function
À la clé rep, on trouve un objet de type : function
À la clé match, on trouve un objet de type : function
À la clé uupper, on trouve un objet de type : function
À la clé ulower, on trouve un objet de type : function
À la clé reverse, on trouve un objet de type : function
À la clé upper, on trouve un objet de type : function
À la clé len, on trouve un objet de type : function
À la clé format, on trouve un objet de type : function
À la clé char, on trouve un objet de type : function
À la clé lower, on trouve un objet de type : function

Nous étudions ci-dessous chacune des fonctions en détail :

string.sub

Cette fonction permet d'extraire une sous-chaîne d'une chaîne donnée. Elle admet trois paramètre. Le premier est la chaîne dont on veut extraire une sous-chaîne. Le deuxième est la position du premier caractère extrait. Le troisième est la position du dernier caractère extrait. Par exemple : string.sub("abcdefghijkl",3,7) devrait nous retourner "cdefg". Il est possible de donner les positions avec des nombres négatifs, cela signifie que l’on compte la position à partir de la fin de la chaîne. Si le troisième paramètre est absent, cela signifie que l’on extrait jusqu'au dernier caractère de la chaîne.

Pour tester cette fonction, nous utiliserons une fonction p.extrait ainsi écrite :

function p.extrait(frame)
	phrase = frame.args[1]
	debut = tonumber(frame.args[2])
	fin = tonumber(frame.args[3])
	return string.sub(phrase,debut,fin)
end

{{#invoke:Chaine|extrait|abcdefghijkl|3|7}} nous donne : cdefg

{{#invoke:Chaine|extrait|abcdefghijkl|-5|-2}} nous donne : hijk

En Unicode, on utilisera la fonction : mw.ustring.sub.

string.find

Cette fonction permet de trouver un motif particulier dans une chaîne de caractères et de retourner sa position.

Elle s'utilise sous la forme string.find(chaîne, motif, position de départ de la recherche,true)

Si la fonction ne trouve pas le motif, elle retourne nil

La position de départ est optionnelle. Si on ne la met pas, la recherche démarrera au début (dans ce cas true ne devra pas être mis non plus).

Si l’on ne met pas true en quatrième paramètre, certains caractères de la chaîne motif vont être interprétés de façon particulière. Ces caractères sont "(", ")", "&", "%". On devra donc mettre true si le motif que l’on recherche contient ces caractères sans qu’ils aient un sens particulier. Si, par exemple, on veut chercher "groupe (mathématiques)" dans un texte qui contient cette expression, on devra écrire : string.find(texte, "groupe (mathématiques)", 1,true). Si l’on se contente d'écrire : string.find(texte, "groupe (mathématiques)"), on obtiendra nil.

Écrivons une fonction p.cherche qui cherche un mot dans la phrase "Rien ne sert de courir, il faut partir à point" :

function p.cherche(frame)
	local mot = frame.args[1]
	local phrase = "Rien ne sert de courir,il faut partir à point"
	local position = string.find(phrase,mot)
	if position then
		return "Le mot recherché se trouve à la position : "..position
	else
		return "Je n'ai pas trouvé !"
	end
end

{{#invoke:Chaine|cherche|courir}} nous donne : Le mot recherché se trouve à la position : 17

Le fait de pouvoir démarrer la recherche à une position particulière peut être utile si on cherche un mot dans un paragraphe d'une page. On commence alors par chercher la position du titre du paragraphe et on cherche ensuite le mot à partir de cette position.

En Unicode, on utilisera la fonction : mw.ustring.find.

string.gsub

Cette fonction permet de remplacer toutes les occurrences d'un motif donné par un autre motif. Par exemple, cette fonction permet de remplacer un mot d'une phrase par un autre mot. string.gsub("Je casse un œuf dur", "casse", "mange") nous retourne : Je mange un œuf dur,1.

Nous voyons aussi que, en plus de la phrase modifiée, cette fonction nous retourne le nombre de modifications faites.

Écrivons une fonction p.oeuf pour vérifier ce que l’on vient de dire :

function p.oeuf()
	local phrase,nombre = string.gsub("Je casse un œuf dur", "casse", "mange")
	return phrase.."(Le nombre de mots remplacés est "..nombre..")"
end

{{#invoke:Chaine|oeuf}} nous donne : Je mange un œuf dur(Le nombre de mots remplacés est 1)

En Unicode, on utilisera la fonction : mw.ustring.gsub.

string.gmatch

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

En Unicode, on utilisera la fonction : mw.ustring.gmatch

string.gfind

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

string.byte

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

En Unicode, on utilisera la fonction : mw.ustring.byte ou la fonction : mw.ustring.codepoint

string.rep

Cette fonction répète une chaîne de caractères un certain nombre de fois. Elle a donc deux arguments. Le premier argument est la chaîne de caractères à répéter et le second argument est le nombre de fois que l’on doit répéter cette chaîne. Par exemple, string.rep("cou",2) devrait nous donner "coucou". À titre d'exemple, nous écrirons une fonction p.echo qui répétera une chaîne de caractères un nombre de fois que l’on précisera :

function p.echo(frame)
	local mot = frame.args[1]
	local nombre = tonumber(frame.args[2])
	return string.rep(mot,nombre)
end

{{#invoke:Chaine|echo|glou |3}} nous donne : glou glou glou

En Unicode, on utilisera la fonction : mw.ustring.rep

string.match

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

En Unicode, on utilisera la fonction : mw.ustring.match

string.uupper

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

string.ulower

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

string.reverse

Cette fonction renverse la chaîne de caractères qui lui est soumise. La dernière lettre devient la première, l'avant dernière devient la seconde et ainsi de suite. Par exemple : "coquillage" devient "egalliuqoc". Pour tester cette fonction, la première idée qui vient à l'esprit est d'écrire une fonction p.palindrome qui teste si un mot entré en argument est un palindrome :

function p.palindrome(frame)
	local mot = frame.args[1]
	if mot == string.reverse(mot) then
		return mot.." est un palindrome."
	else
		return mot.." n’est pas un palindrome."
	end
end

{{#invoke:Chaine|palindrome|radar}} nous donne : radar est un palindrome.

{{#invoke:Chaine|palindrome|renier}} nous donne : renier n’est pas un palindrome.

string.upper

Cette fonction permet de remplacer les caractères minuscules de la chaîne de caractères par les caractères majuscules correspondants. Par exemple, "crocodile" deviendra "CROCODILE". Essayons de voir si ça marche ! Dans le Module:Chaine, écrivons une fonction p.capitale qui utilise directement la fonction string.upper sur une chaîne de caractères rentrée en argument :

function p.capitale(frame)
	local mot = frame.args[1]
	return string.upper(mot)
end

{{#invoke:Chaine|capitale|crocodile}} nous donne : CROCODILE

{{#invoke:Chaine|capitale|pIScinE eT 3 pApiLloNs}} nous donne : PISCINE ET 3 PAPILLONS

Nous constatons sur le dernier exemple que les majuscules restent majuscules. Les autres caractères comme les chiffres ne sont pas modifiés.

En Unicode, on utilisera la fonction : mw.ustring.upper

string.len

Cette fonction nous donne le nombre de caractères contenus dans une chaîne de caractères. Les lettres accentuées comptent double. Par exemple, string.len(Marionnette) devrait nous retourner 11 car il y a 11 lettres dans le mot "Marionnette". Par contre string.len(système) nous retournera 8 à cause de la lettre accentuée è qui compte double. Comme exemple, nous écrirons une fonction p.longueur qui nous renverra le nombre de caractères d'une chaîne de caractères rentrée en argument :

function p.longueur(frame)
	local phrase = frame.args[1]
	return string.len(phrase)
end

{{#invoke:Chaine|longueur|Marionnette}} nous donne : 11

{{#invoke:Chaine|longueur|La vague déferle sur la plage}} nous donne : 30

Dans le deuxième exemple, nous voyons qu’il y a 29 caractères dans la phrase et pourtant la fonction string.len en compte 30 à cause de la présence de la lettre accentuée é dans la mot déferle

En Unicode, on utilisera la fonction : mw.ustring.len

Pour la fonction mw.ustring.len, les lettres accentuées ne comptent pas double. Cette fonction sera donc préférable pour traiter les chaînes de caractères pouvant contenir des lettres accentuées.

string.format

La fonction string.format permet d'obtenir un format particulier pour un nombre ou une chaîne de caractères.

Elle s'utilise sous la forme : string.format(option,nombre ou chaîne)

L'option permet de définir le type de format que l’on désire obtenir. Il sera écrit sous la forme : '%lettre'

Nous allons passer en revue, les différentes options possible :

L'option '%c'

Permet d'obtenir le caractère correspondant à un code ASCII particulier. Par exemple :

string.format('%c',87) donnera la lettre majuscule W.

string.format('%c',36) donnera le symbole $.

L'option '%d'

Donne la partie entière d'un nombre

string.format('%d',56.235) donnera 56.

string.format('%d',-23.827) donnera -23.

L'option '%E'

Permet d'obtenir l'écriture scientifique correspondante à un nombre donnée, la puissance de 10 étant écrite avec E.

string.format('%E',0.097) donnera 9.700000E-2.

L'option '%e'

Permet d'obtenir l'écriture scientifique correspondante à un nombre donnée, la puissance de 10 étant écrite avec e.

string.format('%e',0.097) donnera 9.700000e-2.

L'option '%f'

Permet d'obtenir un nombre décimal écrit avec six chiffres après la virgule.

string.format('%f',0.097) donnera 0.097000

string.format('%f',823.43657835) donnera 823.436578

L'option '%g'

Transforme une notation scientifique en notation décimale tout en arrondissant le nombre à six chiffres significatifs.

string.format('%g',1.5789235E4) donnera 15789.2

string.format('%g',-1.5789235e-4) donnera -0.000157892

L'option '%G'

Transforme une notation scientifique en notation décimale tout en arrondissant le nombre à six chiffres significatifs.

string.format('%G',1.5789235E4) donnera 15789.2

string.format('%G',-1.5789235e-4) donnera -0.000157892

L'option '%i'

Donne la partie entière d'un nombre

string.format('%i',56.235) donnera 56.

string.format('%i',-23.827) donnera -23.

L'option '%o'

Cette option permet de traduire un nombre écrit en base 10 en nombre écrit en base 8.

string.format('%o',9) donnera 11

string.format('%o',93) donnera 135

L'option '%u'

Convertit dans un format qui n'accepte que les nombres entiers positifs compris entre 0 et 18446744073709551615. Le nombre obtenu n'est plus à virgule flottante. Pour les nombres positifs, on obtient la partie entière. Pour les nombres négatifs on obtient la somme du nombre négatif avec 18446744073709551616.

string.format('%u',-1) donnera 18446744073709551615

string.format('%u',21.2479) donnera 21

L'option '%X'

Cette option permet de traduire un nombre en hexadécimal. Autrement dit, cette option permet de traduire un nombre écrit en base 10 en nombre écrit en base 16. Les lettres utilisées pour écrire ce nombre seront en majuscule.

string.format('%X',47) donnera 2F

string.format('%X',28) donnera 1C

L'option '%x'

Cette option permet de traduire un nombre en hexadécimal. Autrement dit, cette option permet de traduire un nombre écrit en base 10 en nombre écrit en base 16. Les lettres utilisées pour écrire ce nombre seront en minuscule.

string.format('%x',169) donnera a9

string.format('%x',735) donnera 2df

L'option '%q'

Traite une chaîne de caractère. Les guillemets sont conservés.

string.format('%q',"La voiture roule") donnera : "La voiture roule"

L'option '%s'

Traite une chaîne de caractère. Les guillemets ne sont pas conservés.

string.format('%s',"La voiture roule") donnera : La voiture roule

Nous pouvons retrouver tous les exemples précédents simulés avec la fonction p.formatage dans le Module:Chaine :

function p.formatage()
	local reponse = " "
	reponse = reponse.."<br>Avec c, on obtent : "..string.format('%c',87).." et "..string.format('%c',36)
	reponse = reponse.."<br>Avec d, on obtent : "..string.format('%d',56.235).." et "..string.format('%d',-23.827)
	reponse = reponse.."<br>Avec E, on obtent : "..string.format('%E',0.097).." et "..string.format('%E',-2833.24)
	reponse = reponse.."<br>Avec e, on obtent : "..string.format('%e',0.097).." et "..string.format('%e',-2833.24)
	reponse = reponse.."<br>Avec f, on obtent : "..string.format('%f',0.097).." et "..string.format('%f',823.43657835)
	reponse = reponse.."<br>Avec g, on obtent : "..string.format('%g',1.5789235E4).." et "..string.format('%g',-1.5789235e-4)
	reponse = reponse.."<br>Avec G, on obtent : "..string.format('%G',1.5789235E4).." et "..string.format('%G',-1.5789235e-4)
	reponse = reponse.."<br>Avec i, on obtent : "..string.format('%i',56.235).." et "..string.format('%i',-23.827)
	reponse = reponse.."<br>Avec o, on obtent : "..string.format('%o',9).." et "..string.format('%o',93)
	reponse = reponse.."<br>Avec u, on obtent : "..string.format('%u',-1).." et "..string.format('%u',21.2479)
	reponse = reponse.."<br>Avec X, on obtent : "..string.format('%X',47).." et "..string.format('%X',28)
	reponse = reponse.."<br>Avec x, on obtent : "..string.format('%x',169).." et "..string.format('%x',735)
	reponse = reponse.."<br>Avec q, on obtent : "..string.format('%q',"La voiture roule")
	reponse = reponse.."<br>Avec s, on obtent : "..string.format('%s',"La voiture roule")
	return reponse
end

{{#invoke:Chaine|formatage}} nous donne :
Avec c, on obtent : W et $
Avec d, on obtent : 56 et -23
Avec E, on obtent : 9.700000E-02 et -2.833240E+03
Avec e, on obtent : 9.700000e-02 et -2.833240e+03
Avec f, on obtent : 0.097000 et 823.436578
Avec g, on obtent : 15789.2 et -0.000157892
Avec G, on obtent : 15789.2 et -0.000157892
Avec i, on obtent : 56 et -23
Avec o, on obtent : 11 et 135
Avec u, on obtent : 18446744073709551615 et 21
Avec X, on obtent : 2F et 1C
Avec x, on obtent : a9 et 2df
Avec q, on obtent : "La voiture roule"
Avec s, on obtent : La voiture roule

En Unicode, on utilisera la fonction : mw.ustring.format

string.char

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.char

string.lower

Cette fonction fait exactement l'inverse de la fonction string.upper, elle transforme les majuscules en minuscules dans une chaîne de caractères. Pour la tester, nous écrirons une fonction p.minuscule ainsi :

function p.minuscule(frame)
	local mot = frame.args[1]
	return string.lower(mot)
end

{{#invoke:Chaine|minuscule|CORNICHON}} nous donne : cornichon

{{#invoke:Chaine|minuscule|pIScinE eT 3 pApiLloNs}} nous donne : piscine et 3 papillons

Nous constatons sur le dernier exemple que les minuscules reste minuscules. Les autres caractères comme les chiffres ne sont pas modifiés.

En Unicode, on utilisera la fonction : mw.ustring.lower

Motifs (pattern)

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

En attendant une rédaction plus détaillée et moins obscure pour les non-programmeurs, cette section est issue d'une recopie d'une partie de la page : mw:Extension:Scribunto/Lua reference manual/fr

En Lua, les motifs sont similaires aux expressions régulières sans pour autant être identiques. Voici quelques différences avec les expressions régulières et les PCRE :

• Le caractère d'échappement est le symbole du pour cent %, pas l'antislash \ ;
• Le point . remplace tout caractère, y compris le retour chariot ;
• Il n'y a pas d'option pour être insensible à la casse ;
• L'alternative | n’est pas définie ;
• Les quantificateurs (*, ?, +, et -) ne peuvent s'appliquer qu’à un caractère ou une classe de caractère, pas à un groupe de capture ;
• Le seul quantificateur non possessif est -, qui est équivalent au quantificateur *? de PCRE ;
• Pas moyen de quantifier de manière précise (comme le ferait {n,m} avec PCRE ;
• Les seuls caractères de contrôle qui n'ont aucune profondeur sont ^ et $ (lua n'offre pas la possibilité d’utiliser \b ou (?=···) qui apparaisse dans les PCRE).

Voir aussi motifs ustring pour des motifs similaires utilisant cette fois les caractères Unicode.

Classes de caractères :

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

Une classe de caractères est utilisée pour représenter un ensemble de caractères. Les combinaisons suivantes sont autorisées pour représenter une classe de caractères :

• x : (où x n’est pas un caractère « magique » ^$()%.[]*+-?) représente le caractère x lui-même.
• . : (un point) représente tous les caractères.
• %a : représente toutes les lettres (A-Za-z, mais pas é, è, û...).
• %c : représente tous les caractères de contrôle.
• %d : représente tous les chiffres.
• %l : représente toutes les lettres minuscules (a-z, mais pas é, è, û...).
• %p : représente tous les signes de ponctuation.
• %s : représente tous les caractères séparateurs (espace, saut de ligne, …).
• %u : représente toutes les lettres majuscules (A-Z, mais pas É, Ê...).
• %w : représente tous les caractères alphanumériques (A-Za-z0-9, mais pas é, è, û...).
• %x : représente tous les chiffres hexadécimaux.
• %z : représente le caractère \0 (le caractère dont la valeur numérique est nulle).
• %x : (où x est n’importe quel caractère non alphanumérique) représente le caractère x. Ceci est la façon habituelle d’utiliser explicitement un caractère « magique » (ayant un sens de contrôle). Tout caractère de ponctuation (même les non magiques) peut être précédé d'un % quand il représente lui-même.
• [set] : représente la classe qui est l'union de tous les caractères présents dans set. On peut indiquer un intervalle de caractère en séparant les caractères qui bornent cet intervalle avec un -.

Toutes les classes %x décrites plus haut peuvent aussi être utilisées dans un set. Tous les autres caractères dans un set représentent eux-mêmes. Par exemple [%w_] (ou [_%w]) représente tous les caractères alphanumériques et le tiret bas (underscore), [0-7] représente les chiffres octaux, et [0-7%l%-] représente les chiffres octaux plus les lettre minuscules plus le caractère -. Utiliser à la fois les intervalles et les classes a un effet non spécifié. Ainsi, des motifs comme [%a-z] ou [a-%%] n'ont pas de sens.

• [^set] : représente le complément de set (voir l'interprétation de set ci-dessus), c'est-à-dire tous les caractères n'appartenant pas à set.

Pour toutes les classes représentées par une seule lettre (%a, %c, …), la lettre majuscule correspondante représente le complément de cette classe. Par exemple %S représente tous les caractères qui ne sont pas des séparateurs.

Élément de motif (pattern item) :

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

Un élément de motif peut être :

• un singleton d'une classe de caractère, qui correspond à un caractère unique dans la classe ;
• un singleton d'une classe de caractère suivi d'un *, qui correspond à 0 ou plus répétition(s) de tout caractère de la classe. Cette répétition correspond toujours à la plus longue répétition possible ;
• un singleton d'une classe de caractère suivi d'un +, qui correspond à 1 ou plus répétition(s) de tout caractère de la classe. Cette répétition correspond toujours à la plus longue répétition possible ;
• un singleton d'une classe de caractère suivi d'un -, qui correspond également à 0 ou plus répétition(s) de tout caractère de la classe. Contrairement à *, cette répétition correspond toujours à la plus petite répétition possible ;
• un singleton d'une classe de caractère suivi d'un ?, qui correspond à 0 ou 1 occurrence d'un caractère de la classe ;
• %n, pour n compris entre 1 et 9. Cet élément correspond à une sous-chaîne valant la n-ième chaîne capturée (voir plus bas) ;
• %bxy, ou x et y sont deux caractères distincts. Cet élément correspond à la chaîne qui commence par x, se termine par y, et où x et y sont équilibrés (balanced). Cela signifie, en lisant la chaîne de gauche à droite, compter +1 pour chaque x et -1 pour chaque y, le y terminal est le premier y pour lequel le compte atteint 0. Par exemple, l'élément %b() correspond à une expression avec des parenthèses équilibrées.

Motif (pattern) :

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

Un motif est une séquence d'éléments de motif. Un ^ au début d'un motif correspond au début de la ligne de la chaîne traitée. Un $ à la fin du motif correspond à la fin de la ligne de la chaîne traitée. Aux autres positions, ^ et $ n'ont pas de sens particulier et représentent le caractère qui les constitue.

Captures :

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

Un motif (pattern) peut contenir des sous-motifs entourés de parenthèses, qui décrivent des captures. Quand une correspondance réussit, la sous-chaîne de la chaîne qui correspond est stockée (capturée) pour usage ultérieur. Les captures sont numérotées dans l’ordre de leur parenthèse de gauche. Par exemple, dans le motif "(a*(.)%w(%s*))", la partie de la chaîne qui concorde avec "a*(.)%w(%s*)" est stockée dans la première capture (et a donc le numéro 1) ; le caractère qui concorde avec "." est stocké dans la capture numéro 2, et la partie qui concorde avec "%s*" a le numéro 3.

La capture vide () est spéciale et capture la position courante dans la chaîne (un nombre). Par exemple si on applique le motif "()aa()" sur la chaîne "flaaap", il y aura deux captures : 3 et 5.

Un motif ne peut contenir de zéros ("\0"). Utilisez %z à la place.

La librairie Ustring

En attendant une rédaction plus détaillée et moins obscure pour les non-programmeurs, des fonctions de cette librairie, cette section est issue d'une recopie d'une partie de la page : mw:Extension:Scribunto/Lua reference manual/fr

La librairie Ustring est une reprise de la librairie string étudiée précédemment, mais pouvant opérer sur des caractères UTF-8.

La plupart des fonctions génèrent une erreur si la chaîne n’est pas valide en codage UTF-8.

mw.ustring.maxPatternLength

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

Donne la taille maximum autorisée pour un motif (pattern), en octets.

mw.ustring.maxStringLength

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

Donne la taille maximum autorisée pour une chaîne, en octets.

mw.ustring.byte

mw.ustring.byte( s, i, j )

Retourne les octets d'une chaîne. Identique à string.byte().

mw.ustring.byteoffset

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.byteoffset( s, l, i )

Retourne la position en octets d'un caractère dans la chaîne. La valeur par défaut pour l et i est 1. i peut être négatif, auquel cas c’est une position à partir de la fin.

Le caractère à l == 1 est le premier caractère qui commence à ou à partir de la position i. Le caractère à l == 0 est le premier caractère qui commence à ou avant la position i. Notez que ce peut être le même caractère. Des valeurs plus grandes ou plus petites de l sont calculées en relatif. (NDT : pas clair. À préciser)

mw.ustring.char

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.char( ... )

Similaire à string.char(), mais les entiers retournés sont des points de codes Unicode et non des octets.

mw.ustring.codepoint

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.codepoint( s, i, j )

Similaire à string.byte(), mais les valeurs retournées sont des points de code Unicode et les positions sont celles des caractères et non des octets.

mw.ustring.find

mw.ustring.find( s, pattern, init, plain )

Similaire à string.find(), mais le motif (pattern) est géré comme décrit dans motifs ustring et la position init est en caractères et non en octets.

Exemple Unicode

print mw.ustring.find("Salut à vous", "à")  -- 7 7

Si la chaine recherchée contient des opérateurs regex, ils peuvent être interprétés. Pour s'en prémunir, il peut être utile de les échapper à l’aide de la fonction suivante : function p._escapePattern( pattern_str ) return mw.ustring.gsub( pattern_str, "([%(%)%.%%%+%-%*%?%[%^%$%]])", "%%%1" ); end

Exemple avec "?"

print mw.ustring.find("Comment allez-vous ?", "vous ?")                    -- "15 19"
print mw.ustring.find("Comment allez-vous ?", p._escapePattern("vous ?"))  -- "15 20"

mw.ustring.format

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.format( format, ... )

Identique à string.format(). Les tailles et précisions pour les chaînes sont en octets et non en points de code Unicode.

mw.ustring.gcodepoint

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.gcodepoint( s, i, j )

Retourne trois valeurs pour itérer sur les points de code Unicode de la chaîne. i vaut 1 par défaut et j vaut -1 par défaut. Ca sert à être utilisé par la forme itérateur de for :

for codepoint in mw.ustring.gcodepoint( s ) do
    block
end

mw.ustring.gmatch

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.gmatch( s, pattern )

Similaire à string.gmatch(), mais le motif (pattern) est géré comme décrit dans motifs ustring.

mw.ustring.gsub

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.gsub( s, pattern, repl[, n] )

Similaire à string.gsub(), mais le motif (pattern) est géré comme décrit dans motifs ustring.

mw.ustring.isutf8

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.isutf8( s )

Retourne vrai si la chaîne est en UTF-8 valide, faux sinon.

mw.ustring.len

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.len( s )

Retourne la longueur de la chaîne en point de code Unicode ou nil si la chaîne n’est pas en UTF-8 valide.

Voir string.len() pour une fonction similaire qui utilise la longueur des bits plutôt que des points de code.

mw.ustring.lower

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.lower( s )

Similaire à string.lower() à part que la fonction suit le format Unicode.

Si la librairie Language est également chargée, ceci utilisera lc() sur la langue courante à la place.

mw.ustring.match

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.match( s, pattern, init )

Similaire à string.match(), mais le motif (pattern) est géré comme décrit dans motifs ustring et la position init est en caractères et non en octets.

mw.ustring.rep

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.rep( s, n )

Identique à string.rep().

mw.ustring.sub

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.sub( s, i, j )

Similaire à string.sub(), mais les positions sont en caractères et non en octets.

mw.ustring.toNFC

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.toNFC( s )

Convertit la chaîne en forme normalisée C. Retourne nil si la chaîne n’est pas valide en UTF-8.

mw.ustring.toNFD

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.toNFD( s )

Convertit la chaîne en forme normalisée D. Retourne nil si la chaîne n’est pas valide en UTF-8.

mw.ustring.upper

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.ustring.upper( s )

Similaire à string.upper() à part que la fonction suit le format Unicode.

Si la librairie Language est également chargée, ceci utilisera uc() sur la langue courante à la place.

Motifs ustring

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

Appelé aussi pattern, les motifs dans les fonctions ustring utilisent la même syntaxe que celle des motifs de la librairie String. La différence principale est que les classes de caractères sont redéfinis en termes de propriétés de caractères Unicode :

• %a : représente tous les caractères de la catégorie "Lettre"
• %c : représente tous les caractères de la catégorie "Contrôle"
• %d : représente tous les caractères de la catégorie "Nombre décimal".
• %l : représente tous les caractères de la catégorie "Lettre minuscule".
• %p : représente tous les caractères de la catégorie "Ponctuation".
• %s : représente tous les caractères de la catégorie "Séparateur", plus tabulation, saut de ligne, retour chariot, tabulation verticale, et saut de page.
• %u : représente tous les caractères de la catégorie "Lettre majuscule"
• %w : représente tous les caractères de la catégorie "Lettre" ou "Nombre décimal"
• %x : ajoute la version complète des caractères hexadécimaux

Dans tous les cas, les caractères sont interprétés comme des caractères Unicode et non des octets, donc des séries comme [０-９], des motifs comme %b«», et des quantificateurs appliqués à des caractères multi-octets fonctionnent correctement. La capture vide capturera des positions en codes Unicode et non en octets.

La librairie Text

Les exemples de ce chapitre se trouveront dans le Module:Text

Nous commencerons par visualiser le contenu de la librairie Text grâce au programme suivant :

local p = {}

function p.visualisation(frame)
	reponse = ""
	for index, objet in pairs(mw.text) do
		reponse = reponse.."<br />À la clé "..index..", on trouve un objet de type : "..type(objet)
	end
	return reponse
end

return p

{{#invoke:Text|visualisation}} nous donne :
À la clé listToText, on trouve un objet de type : function
À la clé gsplit, on trouve un objet de type : function
À la clé nowiki, on trouve un objet de type : function
À la clé encode, on trouve un objet de type : function
À la clé JSON_PRETTY, on trouve un objet de type : number
À la clé decode, on trouve un objet de type : function
À la clé jsonEncode, on trouve un objet de type : function
À la clé truncate, on trouve un objet de type : function
À la clé trim, on trouve un objet de type : function
À la clé killMarkers, on trouve un objet de type : function
À la clé tag, on trouve un objet de type : function
À la clé unstripNoWiki, on trouve un objet de type : function
À la clé split, on trouve un objet de type : function
À la clé JSON_PRESERVE_KEYS, on trouve un objet de type : number
À la clé jsonDecode, on trouve un objet de type : function
À la clé JSON_TRY_FIXING, on trouve un objet de type : number
À la clé unstrip, on trouve un objet de type : function

Nous voyons que nous avons 12 fonctions. Étudions les dans l’ordre où elles sont sorties.

mw.text.listToText

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.listToText( list )
mw.text.listToText( list, separator, conjunction )

Joint une liste sous forme « textuelle ». Fait la même chose que table.concat() mais avec un séparateur différent pour l'élément final.

Le séparateur par défaut est récupéré dans MediaWiki:comma-separator dans la langue locale, et la conjonction par défaut est le MediaWiki:and concaténé avec le MediaWiki:word-separator.

Exemples :

-- retourne une chaîne vide
mw.text.listToText( {} )

-- retourne "1"
mw.text.listToText( { 1 } )

-- retourne "1 et 2"
mw.text.listToText( { 1, 2 } )

-- retourne "1, 2, 3, 4 et 5"
mw.text.listToText( { 1, 2, 3, 4, 5 } )

-- retourne "1; 2; 3; 4 ou 5"
mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' ou ' )

mw.text.gsplit

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.gsplit( s, pattern, plain )

Retourne une fonction itérative qui va itérer sur les sous-chaînes qui auraient été retournées par un appel équivalent à mw.text.split().

mw.text.truncate

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.truncate( text, length )
mw.text.truncate( text, length, ellipsis )
mw.text.truncate( text, length, ellipsis, adjustLength )

Tronque text à la longueur indiquée, en ajoutant ellipsis si une troncature est effectuée. Si length est positif, la fin de la chaîne est tronquée ; s'il est négatif, c’est le début de la chaîne qui est enlevé. Si adjustLength est présent et vrai, le résultat en incluant ellipsis ne sera pas plus long que la longueur précisée.

La valeur par défaut pour ellipsis est prise dans MediaWiki:ellipsis pour le wiki local.

Exemples utilisant "..." pour ellipsis :

-- retourne "foobarbaz"
mw.text.truncate( "foobarbaz", 9 )

-- retourne "fooba..."
mw.text.truncate( "foobarbaz", 5 )

-- retourne "...arbaz"
mw.text.truncate( "foobarbaz", -5 )

-- retourne "foo..."
mw.text.truncate( "foobarbaz", 6, nil, true )

-- retourne "foobarbaz", car c’est plus court que "foobarba..."
mw.text.truncate( "foobarbaz", 8 )

mw.text.encode

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.encode( s )
mw.text.encode( s, charset )

Remplace les caractères de la chaîne par des entités HTML. Les caractères '<', '>', '&', '"', et l'espace insécable sont remplacés par l'entité HTML correspondante. Tous les autres sont remplacés par l'entité HTML numérique correspondante.

Si charset est indiqué, il doit contenir une chaîne pouvant être utilisée dans une classe de caractères des motifs Ustring, par exemple "set" dans [set]. Par défaut : '<>&"\' ' (l'espace à la fin est l'espace insécable U+00A0).

mw.text.trim

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.trim( s )
mw.text.trim( s, charset )

Enlève les espaces et autres caractères au début et à la fin d'une chaîne.

Si charset est indiqué, il doit contenir une chaîne syntaxiquement compatible avec les classes de caractères des motifs Ustring, par exemple "set" dans [set]. Par défaut : l'espace ASCII, "%t%r%n%f".

mw.text.killMarkers

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.killMarkers( s )

Retire d'une chaîne toutes les balises spécifiques à MediaWiki.

mw.text.tag

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.tag{ name = string, attrs = table, content = string|bool }

Notez l’utilisation de paramètres nommés.

Génère un tag à la façon HTML pour name.

Si attrs est indiqué, il doit être une table avec des clés de type chaîne. Les valeurs de ces clés sont utilisées comme valeurs des attributs. Une valeur booléenne true insère un paramètre HTML5 sans valeur, et false ignore le paramètre. Toute autre valeur génère une erreur.

Si content n’est pas présent (ou vaut nil), seul le tag ouvrant est retourné. Si content vaut false, un tag auto-fermant est retourné. Sinon il doit être un nombre ou une chaîne auquel cas ce contenu est inséré entre l'ouverture et la fermeture du tag. Notez que le contenu n’est pas automatiquement encodé en HTML ; utiliser mw.text.encode() au besoin.

Pour retourner proprement un tag comme <ref>, utilisez plutôt frame:extensionTag().

mw.text.decode

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.decode( s )
mw.text.decode( s, decodeNamedEntities )

Remplace les entités HTML de la chaîne par les caractères correspondant.

Si decodeNamedEntities est absent ou false, les seules entités reconnues sont '&lt;', '&gt;', '&amp;', '&quot;', et '&nbsp;'. Sinon la liste des entités HTML5 à traiter est chargée depuis la fonction PHP get_html_translation_table.

mw.text.nowiki

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.nowiki( s )

Remplace divers caractères dans la chaîne par des entités HTML pour éviter leur interprétation comme wikitexte. Ceci comprend :

• Les caractères suivants : '"', '&', "'", '<', '=', '>', '[', ']', '{', '|', '}'
• Les caractères suivants au début de la chaîne ou juste après un retour à la ligne : '#', '*', ':', ';', espace, tabulation ('\t')
• Les lignes blanches auront le caractère de nouvelle ligne (LF) ou de retour chariot (CR) d'échappé
• "----" au début de la chaine ou juste après un saut de ligne verra son premier '-' échappé
• "__" aura un tiret bas d'échappé
• "://" aura le deux-point échappé
• Un espace blanc suivant "ISBN", "RFC", ou "PMID" sera échappé

mw.text.split

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.split( s, pattern, plain )

Découpe une chaîne en sous-chaînes dont les limites correspondent au motif Ustring pattern. Si plain est présent et vrai, pattern est interprété comme une chaîne littérale et non comme un motif Lua (comme le paramètre de même nom pour mw.ustring.find()). Retourne une table contenant les sous-chaînes.

Par exemple mw.text.split( 'a b\tc\nd', '%s' ) retourne une table { 'a', 'b', 'c', 'd' }.

Si pattern correspond à la chaîne vide, s sera découpé en caractères individuels.

mw.text.unstripNoWiki

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.unstripNoWiki( s )

Renvoie la chaine entre balises <nowiki>. Les autres balises restent inchangées.

mw.text.unstrip

Cette section est vide, insuffisamment détaillée ou incomplète. Votre aide est la bienvenue ! Comment faire ?

mw.text.unstrip( s )

Équivalent à mw.text.killMarkers( mw.text.unstripNoWiki( s ) ).

This no longer reveals the HTML behind special page transclusion, <ref> tags, and so on as it did in earlier versions of Scribunto.