Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
RegEx
Eredita: RefCounted < Object
Classe per la ricerca di modelli nel testo, tramite espressioni regolari.
Descrizione
Un'espressione regolare (o regex) è un linguaggio compatto che può essere utilizzato per riconoscere stringhe che seguono uno schema specifico, come URL, indirizzi email, frasi complete, ecc. Ad esempio, un'espressione regolare ab[0-9] troverebbe qualsiasi stringa che sia ab, seguita da un numero qualsiasi da 0 a 9. Per un approfondimento, è possibile facilmente trovare vari tutorial e spiegazioni dettagliate su Internet.
Per iniziare, l'oggetto RegEx deve essere compilato con il pattern di ricerca tramite compile() prima di poterlo utilizzare. Alternativamente, è possibile usare il metodo statico create_from_string() per creare e compilare un oggetto RegEx in una singola chiamata.
var regex = RegEx.new()
regex.compile("\\w-(\\d+)")
# Abbreviazione per creare e compilare una regex (usata negli esempi seguenti):
var regex2 = RegEx.create_from_string("\\w-(\\d+)")
Il pattern di ricerca deve essere prima sottoposto a escape per GDScript, prima di essere sottoposto a escape per l'espressione. Ad esempio, compile("\\d+") sarebbe interpretato da RegEx come \d+. Analogamente, compile("\"(?:\\\\.|[^\"])*\"") sarebbe interpretato come "(?:\\.|[^"])*". In GDScript, è anche possibile utilizzare stringhe letterali non elaborate (r-string). Ad esempio, compile(r'"(?:\\.|[^"])*"') sarebbe interpretato allo stesso modo.
Attraverso search(), è possibile trovare il pattern all'interno del testo specificato. Se viene trovato un pattern, viene restituito RegExMatch ed è possibile recuperare i dettagli dei risultati tramite metodi come RegExMatch.get_string() e RegExMatch.get_start().
var regex = RegEx.create_from_string("\\w-(\\d+)")
var result = regex.search("abc n-0123")
if result:
print(result.get_string()) # Stampa"n-0123"
È possibile recuperare i risultati dell'acquisizione di gruppi () passando il numero del gruppo ai vari metodi in RegExMatch. Il gruppo 0 è quello predefinito e farà sempre riferimento all'intero pattern. Nell'esempio precedente, la chiamata a result.get_string(1) restituirebbe 0123.
Questa versione di RegEx supporta anche l'acquisizione di gruppi con nome, i cui nomi possono essere utilizzati per recuperare i risultati. Se due o più gruppi hanno lo stesso nome, il nome si riferirà solo al primo corrispondente.
var regex = RegEx.create_from_string("d(?<digit>[0-9]+)|x(?<digit>[0-9a-f]+)")
var result = regex.search("the number is x2f")
if result:
print(result.get_string("digit")) # Stampa "2f"
Se è necessario elaborare più risultati, search_all() genera un elenco di tutti i risultati non sovrapposti. Per comodità, è possibile combinare questo metodo con un ciclo for.
# Stampa "01 03 0 3f 42"
for result in regex.search_all("d01, d03, d0c, x3f and x42"):
print(result.get_string("digit"))
Esempio: Dividi una stringa tramite un'espressione regolare:
var regex = RegEx.create_from_string("\\S+")) # Classe negata di caratteri di spaziatura.
var risultati = []
for result in regex.search_all("Uno Due \n\tTre"):
risultati.push_back(result.get_string())
print(results) # Stampa ["Uno", "Due", "Tre"]
Nota: L'implementazione delle espressioni regolari di Godot si basa sulla libreria PCRE2. È possibile visualizzare il riferimento completo ai pattern qui.
Suggerimento: È possibile usare Regexr per testare online le espressioni regolari.
Metodi
void |
clear() |
create_from_string(pattern: String, show_error: bool = true) static |
|
get_group_count() const |
|
get_names() const |
|
get_pattern() const |
|
is_valid() const |
|
search(subject: String, offset: int = 0, end: int = -1) const |
|
search_all(subject: String, offset: int = 0, end: int = -1) const |
|
sub(subject: String, replacement: String, all: bool = false, offset: int = 0, end: int = -1) const |
Descrizioni dei metodi
void clear() 🔗
Questo metodo reimposta lo stato dell'oggetto, come se fosse stato appena creato. Ovvero, annulla l'assegnazione dell'espressione regolare di questo oggetto.
Error compile(pattern: String, show_error: bool = true) 🔗
Compila e assegna il modello di ricerca da usare. Restituisce @GlobalScope.OK se la compilazione avviene con successo. Se si verifica un errore, restituisce @GlobalScope.FAILED e, se show_error è true, i dettagli vengono stampati sull'output standard.
RegEx create_from_string(pattern: String, show_error: bool = true) static 🔗
Crea e compila un nuovo oggetto RegEx. Vedi anche compile().
Restituisce il numero di gruppi di cattura nel modello compilato.
PackedStringArray get_names() const 🔗
Restituisce un array di nomi di gruppi di cattura denominati nel pattern compilato. Sono elencati in ordine di apparizione.
Restituisce il modello di ricerca originale compilato.
Restituisce se a questo oggetto è assegnato un modello di ricerca valido.
RegExMatch search(subject: String, offset: int = 0, end: int = -1) const 🔗
Ricerca nel testo il modello compilato. Restituisce un contenitore RegExMatch del primo risultato corrispondente se trovato, altrimenti null.
La regione in cui cercare può essere specificata con offset e end. Ciò è utile quando si cerca un'altra corrispondenza nello stesso soggetto (subject), richiamando questo metodo dopo un successo precedente. Nota che impostare questi parametri non è la stessa cosa di passare una stringa abbreviata. Ad esempio, l'ancora di inizio ^ non è influenzata da offset e il carattere prima di offset sarà controllato per il confine di parola \b.
Array[RegExMatch] search_all(subject: String, offset: int = 0, end: int = -1) const 🔗
Ricerca nel testo il modello compilato. Restituisce un array di contenitori RegExMatch per ogni risultato non sovrapposto. Se nessun risultato è stato trovato, viene restituito un array vuoto.
La regione in cui cercare può essere specificata con offset e end. Ciò è utile quando si cerca un'altra corrispondenza nello stesso soggetto (subject), richiamando questo metodo dopo un successo precedente. Nota che impostare questi parametri non è la stessa cosa di passare una stringa abbreviata. Ad esempio, l'ancora di inizio ^ non è influenzata da offset e il carattere prima di offset sarà controllato per il confine di parola \b.
String sub(subject: String, replacement: String, all: bool = false, offset: int = 0, end: int = -1) const 🔗
Ricerca nel testo il modello compilato e lo sostituisce con la stringa specificata. Escape e backreference come $1 e $name vengono espansi e risolti. Per impostazione predefinita, solo la prima istanza viene sostituita, ma può essere modificata per tutte le istanze (sostituzione globale).
La regione in cui cercare può essere specificata con offset e end. Ciò è utile quando si cerca un'altra corrispondenza nello stesso soggetto (subject), richiamando questo metodo dopo un successo precedente. Nota che impostare questi parametri non è la stessa cosa di passare una stringa abbreviata. Ad esempio, l'ancora di inizio ^ non è influenzata da offset e il carattere prima di offset sarà controllato per il confine di parola \b.