Modulo:String/man

Questa è la pagina di documentazione per Modulo:String

Modulo Lua per la manipolazione di stringhe.

La maggior parte delle funzioni di questo modulo possono essere invocate con parametri con nome, senza nome o con un misto di entrambi. Il software di MediaWiki, quando vengono usati parametri con nome, rimuoverà ogni spazio iniziale o finale dal parametro. A seconda dell'uso che si vuole fare della funzione può essere vantaggioso conservare oppure rimuovere questi spazi.

Chiamata delle funzioni

Questo modulo è pensato per essere richiamato da template, non direttamente da una voce. Il modulo è richiamabile anche da un altro modulo Lua, ma in questo caso è meglio usare direttamente le funzioni Lua di manipolazione delle stringhe:

Per richiamare il modulo da un template usare la sintassi: {{{{{|safesubst:}}}#invoke:String|nome della funzione|parametro 1|parametro 2|...|parametro n|}}. Per esempio d'uso vedi il template {{Str len}}

Opzioni globali

Alcune funzioni possono dare un messaggio di errore o impostare una categoria di errori, la generazione di questo messaggio e/o la creazione di questa categoria possono essere controllate dalle seguenti opzioni.

ignore_errors: se impostato a 1 o "true" ogni condizione di errore darà una stringa vuota piuttosto che un messaggio di errore.

error_category: nel caso si verifichi un errore è il nome di una categoria da includere insieme al messaggio di errore. La categoria di default è Categoria:Errori riportati dal modulo String.

no_category: Se settato a 1 o "true", non verranno aggiunte categorie in caso di errore.

Funzioni

len

Questa funzione restituisce la lunghezza di una stringa.

Uso

{{#invoke:String|len|stringa}}

O

{{#invoke:String|len|s= stringa }}

Parametri

s: La stringa di cui restituire la lunghezza

Se invocata usando parametri nominati, Mediawiki rimuoverà automaticamente ogni spazio iniziale o finale dalla stringa.

sub

Questa funzione restituisce la sottostringa di una stringa bersaglio, come indicato dagli indici

Uso

{{#invoke:String|sub|stringa_bersaglio|indice_iniziale|indice_finale}}

O

{{#invoke:String|sub|s= stringa_bersaglio |i= indice_iniziale |j= indice_finale }}

Parametri

s: La stringa da cui estrarre una sottostringa
i: La posizione iniziale del primo carattere della sottostringa da restituire, se non specificato è 1.
j: La posizione finale dell'ultimo carattere della sottostringa da restituire, se non specificato corrisponde alla lunghezza della stringa_bersaglio (l'ultimo carattere).

I caratteri della stringa sono numerati a partire da 1. Se i o j hanno un valore negativo allora contano la posizione contando dalla fine della stringa, -1 è l'ultimo carattere della stringa, -2 il penultimo, ecc...

Se le posizioni sono al di fuori degli estremi della stringa viene restituito un messaggio di errore.

match

Questa funzione restituisce una sottostringa della stringa bersaglio corrispondente a un pattern specificato.

Uso

{{#invoke:String|match|source_string|pattern_string|start_index|match_number|plain_flag|nomatch_output}}

O

{{#invoke:String|match|s= source_string |pattern= pattern_string |start= start_index |match= match_number |plain= plain_flag |nomatch= nomatch_output }}

Parametri

s: la stringa da cercare
pattern: il pattern da cercare nella stringa s
start: la posizione iniziale da cui iniziare la ricerca, se non specificato è 1.
match: se ci sono corrispondenze multiple, quale restituire: 1 per la prima corrispondenza, 2 per la seconda, ecc... Un valore negativo indica di contare all'indietro a partire dall'ultima corrispondenza, quindi match = -1 significa chiedere l'ultima corrispondenza. Se non specificato è 1
plain: se vero specifica che il pattern deve essere considerato come una stringa normale, piuttosto che un pattern Lua. Se non specificata è falso.
nomatch: il valore da restituire se non ci sono corrispondenze, invece di un errore.

Se richiamata usando parametri nominati Mediawiki rimuoverà automaticamente tutti gli spazi iniziali e finali. In alcune circostanze questo può essere il comportamento desiderato, in altre si potrebbe volerli conservare.

Se match o start sono al di fuori degli estremi della stringa s, allora la funzione restituisce un errore. Viene generato un errore anche se il non vengono trovate corrispondenze. Per sopprimere gli errori si può aggiungere il parametro ignore_errors=true, in questo caso in caso di errore verrà restituita una stringa vuota.

pos

Questa funzione restituisce il carattere della stringa in posizione pos.

Uso

{{#invoke:String|pos|stringa_bersaglio|indice}}

O

{{#invoke:String|pos|target= stringa_bersaglio |pos= indice }}

Parametri

target: la stringa in cui cercare
pos: la posizione del carattere da restituire

Se richiamata usando parametri nominati Mediawiki rimuoverà automaticamente tutti gli spazi iniziali e finali. In alcune circostanze questo può essere il comportamento desiderato, in altre si potrebbe volerli conservare.

I caratteri della stringa sono numerati a partire da 1. Se pos è un valore negativo allora conta la posizione partendo dalla fine della stringa, -1 è l'ultimo carattere della stringa, -2 il penultimo, ecc...

Se la posizione richiesta è 0 o al di fuori degli estremi della stringa viene restituito un errore.

str_find

Questa funzione duplica il comportamento di {{str_find}}, inclusi i casi particolari. Questa funzione è fornita per motivi di compatibilità con i vecchi template, ma SI RACCOMANDA di non utilizzarla in nuovi template. Nello sviluppo di nuovo codice si raccomanda di usare la funzione find.

Parametri

source: la stringa in cui cercare
target: la stringa da cercare

Restituisce la posizione nella stringa source del primo carattere in cui è stata trovata la stringa target. I caratteri della stringa sono numerati a partire da 1. La funzione restituisce -1 se la stringa target non è contenuta in source.

Nota importante: Per compatibilità con il vecchio template, se la stringa target è vuota o manca, la funzione restituisce il valore "1"

find

Questa funzione permette di cercare una stringa bersaglio o un pattern Lua all'interno di un'altra stringa.

Uso

{{#invoke:String|find|stringa_sorgente|stringa_bersaglio|indice_iniziale|plain_flag}}

O

{{#invoke:String|find|source= stringa_sorgente |target= stringa_bersaglio |start= indice_iniziale |plain= plain_flag }}

Parametri

source: la stringa in cui cercare
target: la stringa o pattern Lua da cercare
start: la posizione da cui iniziare la ricerca, se non specificato è 1
plain: Se è vero indica che la stringa target deve essere considerata come un testo normale e non come un pattern Lua, se non specificata è vera

Se richiamata usando parametri nominati Mediawiki rimuoverà automaticamente tutti gli spazi iniziali e finali. In alcune circostanze questo può essere il comportamento desiderato, in altre si potrebbe volerli conservare.

Questa funzione restituisce la prima posizione maggiore o uguale a start a partire dalla quale target si trova in source. I caratteri della stringa sono numerati a partire da 1. Se target non viene trovato dà 0. Se source o target sono mancanti o vuoti dà 0.

Questa funzione dovrebbe essere sicura per stringhe UTF-8.

replace

Questa funzione permette di rimpiazzare una stringa o pattern bersaglio con un'altra stringa.

Uso

{{#invoke:String|replace|stringa_sorgente|stringa_pattern|nuova_stringa|numero_di_sostituzioni|plain_flag}}

O

{{#invoke:String|replace|source= stringa_sorgente |pattern= stringa_pattern |replace= nuova_stringa | count= numero_di_sostituzioni |plain= plain_flag }}

Parametri

source: la stringa in cui cercare
pattern: la stringa o pattern Lua da trovare in source
replace: il testo di sostituzione
count: il numero di volte in cui rimpiazzare la stringa, se non specificato tutte.
plain: se vero indica che il pattern deve essere considerato come testo normale e non come pattern Lua, il valore di default è vero

arraytostring

Formatta una o più liste di valori in una singola stringa

Uso

{{#invoke:String|arraytostring|par1|formato|separatore|congiunzione}}

Parametri

par1 ... parn: il nome base delle variabili da unire, deve contenere il carattere "#" che precisa la posizione in cui inserire l'indice. Ad esempio se par1 è "Param#", la funzione unirà i valori della lista di parametri Param1, Param2, Param3, ecc...
Il parametro "Param" (senza numero) sarà considerato equivalente a "Param1" (questo comportamento può essere modificato con il parametro "baseIndex")
msg: formattazione da applicare alla compilazione dei parametri. Il simbolo $n fa da segnaposto per il parametro "parn". È possibile inserire codice mediawiki, ma sarà eseguito prima del modulo, cioè quando il simbolo $n non è ancora stato sostituito. Per ovviare al problema, gli eventuali caratteri "{" e "}" delle parti di codice che debbano essere eseguite dopo l'elaborazione di $n dovranno essere preceduti da un "\", mentre il carattere "|" dovrà essere inserito con la costante {{!}}. Un eventuale "\}" finale dovrà sempre essere staccato, con spazio o altro, dal "}}" di fine comando. Un esempio pratico: {{#if:{{{x|}}}|$2}} si può scrivere normalmente così perché la condizione si basa sul parametro "x"; al contrario \{\{#if:$2{{!}}{{{x|}}}\}\} va scritto come appena spiegato perché la condizione si basa sul simbolo $2 che sarà sostituito solo dopo l'avvio del modulo.
separatore: una stringa (opzionale) da inserire tra ogni valore
congiunzione: una stringa (opzionale) da inserire al posto del separatore tra l'ultimo e il penultimo valore. Se non dichiarata viene usato il valore di "separatore"
nmin: indice iniziale da cui partire a scandire i parametri (di default pari a 1)
nmax: indice massimo a cui è possibile arrivare con i parametri (se non precisato è illimitato)
nobbligatori = l'indice minimo che deve essere valutato anche in presenza di buchi nella sequenza (come indice massimo sarà comunque valutato "nmax")
baseIndex: valore dell'indice parametrico che coincide con il parametro senza indice (normalmente è 1, quindi i parametri "par1" e "par" sono equivalenti; se per esempio viene impostato a 0 allora è "par0" che sarà equivalente a "par")
lista: parametro a cui è possibile assegnare uno tra i seguenti valori.
puntata - formatta l'elenco di valori come una lista puntata (i valori di "separatore" e "congiunzione" sono ignorati)

ordinata - formatta l'elenco di valori come una lista numerata (i valori di "separatore" e "congiunzione" sono ignorati)

infobox - formatta l'elenco di valori come una lista puntata (i valori di "separatore" e "congiunzione" sono ignorati), eccetto che nel caso in cui ci sia un solo elemento

Esempi di chiamata

{{#invoke:string|arraytostring|par1=var#|separatore= |congiunzione= e }}

Formatta una lista di parametri "var1", "var2" ... "varn" separandoli con una virgola, tranne per gli ultimi due uniti dalla congiunzione " e "

{{#invoke:string|arraytostring|par1=disegnatore #|par2=disegnatore # nota|msg = $1 <small>$2</small>|lista=infobox}}

Formatta coppie di parametri "disegnatore 1", "disegnatore 2" ... "disegnatore n" e "disegnatore 1 nota", "disegnatore 2 nota" ... "disegnatore n nota". Ogni coppia sarà formattata come "Disegnatore disegnatore nota" e queste saranno unite in una lista puntata. È Utile per formattare le liste di disegnatori/autori/editori, ecc...

{{#invoke:String|arraytostring|par1=#|msg=''$1''|separatore=<nowiki>|</nowiki>|Nmin=2}}

Unisce i parametri ordinali "2", "3" ... "n" in una lista separate da "|". Ogni valore viene reso in corsivo. Usata in {{tl}} per formattare la lista opzionale di parametri.

collate

Questa funzione restituisce la stringa privata degli eventuali segni diacritici sulle lettere dell'alfabeto latino. Trasforma ad esempio "Çịàö" in "Ciao", preferibile ad esempio per gli ordinamenti alfabetici.

Uso

{{#invoke:String|collate|stringa}}

Parametri

stringa: La stringa da cui togliere i segni

decode

Questa funzione accetta una stringa codificata con il sistema a percentuali usato negli URL e restituisce la stringa decodificata. Fa quindi l'opposto della funzione di sistema urlencode. Trasforma ad esempio "Come%20va%3F" in "Come va?".

Uso

{{#invoke:String|decode|stringa}}

Parametri

stringa: La stringa da decodificare

titolo_alfa

Questa funzione accetta una stringa che corrisponde a un titolo di opera e restituisce la stringa adattata all'ordinamento alfabetico. Trasforma ad esempio "La pietà" in "Pieta, La". Non funziona sempre, non potendo capire il significato delle parole, ma risolve automaticamente la maggior parte dei casi.

Uso

{{#invoke:String|titolo_alfa|titolo}}

Parametri

titolo: Il titolo di opera. Di default viene preso il titolo della pagina in cui ci si trova.

Unit test

Unit test per questo modulo sono disponibili a Modulo:String/test, per la loro esecuzione visitare Discussioni_modulo:String/test.

Documentazione sui pattern Lua

Diverse funzioni fanno uso di pattern Lua, questi sono una forma di espressione regolare, per maggiori informazioni sulla loro sintassi vedi: