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
Hérite de : RefCounted < Object
Classe pour chercher du texte avec des motifs en utilisant des expressions régulières.
Description
A regular expression (or regex) is a compact language that can be used to recognize strings that follow a specific pattern, such as URLs, email addresses, complete sentences, etc. For example, a regex of ab[0-9] would find any string that is ab followed by any number from 0 to 9. For a more in-depth look, you can easily find various tutorials and detailed explanations on the Internet.
To begin, the RegEx object needs to be compiled with the search pattern using compile() before it can be used. Alternatively, the static method create_from_string() can be used to create and compile a RegEx object in a single method call.
var regex = RegEx.new()
regex.compile("\\w-(\\d+)")
# Shorthand to create and compile a regex (used in the examples below):
var regex2 = RegEx.create_from_string("\\w-(\\d+)")
The search pattern must be escaped first for GDScript before it is escaped for the expression. For example, compile("\\d+") would be read by RegEx as \d+. Similarly, compile("\"(?:\\\\.|[^\"])*\"") would be read as "(?:\\.|[^"])*". In GDScript, you can also use raw string literals (r-strings). For example, compile(r'"(?:\\.|[^"])*"') would be read the same.
Using search(), you can find the pattern within the given text. If a pattern is found, RegExMatch is returned and you can retrieve details of the results using methods such as RegExMatch.get_string() and RegExMatch.get_start().
var regex = RegEx.create_from_string("\\w-(\\d+)")
var result = regex.search("abc n-0123")
if result:
print(result.get_string()) # Prints "n-0123"
The results of capturing groups () can be retrieved by passing the group number to the various methods in RegExMatch. Group 0 is the default and will always refer to the entire pattern. In the above example, calling result.get_string(1) would give you 0123.
This version of RegEx also supports named capturing groups, and the names can be used to retrieve the results. If two or more groups have the same name, the name would only refer to the first one with a match.
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")) # Prints "2f"
If you need to process multiple results, search_all() generates a list of all non-overlapping results. This can be combined with a for loop for convenience.
# Prints "01 03 0 3f 42"
for result in regex.search_all("d01, d03, d0c, x3f and x42"):
print(result.get_string("digit"))
Example: Split a string using a RegEx:
var regex = RegEx.create_from_string("\\S+") # Negated whitespace character class.
var results = []
for result in regex.search_all("One Two \n\tThree"):
results.push_back(result.get_string())
print(results) # Prints ["One", "Two", "Three"]
Note: Godot's regex implementation is based on the PCRE2 library. You can view the full pattern reference here.
Tip: You can use Regexr to test regular expressions online.
Méthodes
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 |
Descriptions des méthodes
void clear() 🔗
Cette méthode réinitialise l'état de l'objet, comme si il était fraîchement créé. En fait, elle désaffecte l'expression régulière de cet objet.
Error compile(pattern: String, show_error: bool = true) 🔗
Compile et assigne le motif de recherche à utiliser. Renvoie @GlobalScope.OK si la compilation est réussie. Si la compilation échoue, renvoie @GlobalScope.FAILED et lorsque show_error vaut true, les détails sont affichés à la sortie standard.
RegEx create_from_string(pattern: String, show_error: bool = true) static 🔗
Crée et compile un nouvel objet RegEx. Voir aussi compile().
Renvoie le nombre de groupes de capture dans le motif compilé.
PackedStringArray get_names() const 🔗
Renvoie un tableau de noms de groupes de capture nommés dans le motif compilé. Ils sont ordonnés par ordre d'apparition.
Renvoie le motif de recherche original qui a été compilé.
Renvoie si cet objet a un motif de recherche valide assigné.
RegExMatch search(subject: String, offset: int = 0, end: int = -1) const 🔗
Cherche le texte pour le motif compilé. Renvoie un conteneur RegExMatch du premier résultat correspondant si trouvé, sinon null.
La région dans laquelle rechercher peut être spécifiée avec offset et end. Ceci est utile lors d'une recherche d'un autre correspondance dans le même objet subject en appelant cette méthode à nouveau après un succès précédent. Notez que définir ces paramètres diffère du passage d'une chaîne raccourcie. Par exemple, l'ancre de démarrage ^ n'est pas affectée par offset, et le caractère avant offset sera vérifié pour la limite de mot \b.
Array[RegExMatch] search_all(subject: String, offset: int = 0, end: int = -1) const 🔗
Cherche le texte pour le motif compilé. Renvoie un tableau de conteneurs RegExMatch pour chaque résultat ne se superposant pas. Si aucun résultat n'est trouvé, un tableau vide est renvoyé à la place.
La région dans laquelle rechercher peut être spécifiée avec offset et end. Ceci est utile lors d'une recherche d'un autre correspondance dans le même objet subject en appelant cette méthode à nouveau après un succès précédent. Notez que définir ces paramètres diffère du passage d'une chaîne raccourcie. Par exemple, l'ancre de démarrage ^ n'est pas affectée par offset, et le caractère avant offset sera vérifié pour la limite de mot \b.
String sub(subject: String, replacement: String, all: bool = false, offset: int = 0, end: int = -1) const 🔗
Cherche le texte pour le motif compilé et le remplace par la chaîne spécifiée. les séquences d'échappement et les références arrières telles que $1 et $name sont étendues et résolues. Par défaut, seule la première instance est remplacée, mais cela peut être changé pour toutes les instances (remplacement global).
La région dans laquelle rechercher peut être spécifiée avec offset et end. Ceci est utile lors d'une recherche d'un autre correspondance dans le même objet subject en appelant cette méthode à nouveau après un succès précédent. Notez que définir ces paramètres diffère du passage d'une chaîne raccourcie. Par exemple, l'ancre de démarrage ^ n'est pas affectée par offset, et le caractère avant offset sera vérifié pour la limite de mot \b.