RegEx

RegEx

使用正则表达式搜索文本的类。

描述

正则表达式（或称 regex）是一种紧凑的语言，可用于识别遵循特定模式的字符串，如 URL、电子邮件地址、完整句子等。例如正则表达式 ab[0-9] 可以找到 ab 后面跟着 0 到 9 的任何数字的字符串。要想更深入地了解，你可以很容易地在互联网上找到各种教程和详细解释。

首先，在使用 RegEx 对象之前，需要用 compile 对其进行搜索模式的编译。

var regex = RegEx.new()
regex.compile("\\w-(\\d+)")

在为表达式转义之前，必须先为 GDScript 转义搜索模式。例如，compile("\\d+") 会被 RegEx 读成 \d+。同样，compile("\"(?:\\\\.|[^\"])*\") 会被读作 "(?:\.|[^"])*"。在 GDScript 中，你还可以使用原始字符串文字（r-字符串）。例如，compile(r'"(?:\\.|[^"])*"') 将被读取为相同的。

使用 search，你可以在给定的文本中匹配模式。如果匹配到一个模式，将返回 RegExMatch，你可以使用 RegExMatch.get_string 和 RegExMatch.get_start 等方法检索结果的细节。

var regex = RegEx.new()
regex.compile("\\w-(\\d+)")
var result = regex.search("abc n-0123")
if result:
    print(result.get_string()) # 会输出 n-0123

捕获组的结果 () 可以通过向 RegExMatch 中的各种方法传递组号来检索。默认是组 0，并且将总是指整个模式。在上面的例子中，调用 result.get_string(1) 会得到 0123。

这个版本的 RegEx 也支持命名的捕获组，名称可以用来检索结果。如果两个或更多的组有相同的名称，那么这个名称将只指第一个有匹配的组。

var regex = RegEx.new()
regex.compile("d(?<digit>[0-9]+)|x(?<digit>[0-9a-f]+)")
var result = regex.search("数字是 x2f")
if result:
    print(result.get_string("digit")) # 会输出 2f

如果你需要处理多个结果，search_all 会生成一个所有不重叠的结果列表。为了方便起见，这可以和一个 for 循环结合起来。

for result in regex.search_all("d01, d03, d0c, x3f and x42"):
    print(result.get_string("digit"))
# 会输出 01 03 0 3f 42

使用 RegEx 分割字符串的例子：

var regex = RegEx.new()
regex.compile("\\S+") # 非空白字符类。
var results = []
for result in regex.search_all("One  Two \n\tThree"):
    results.push_back(result.get_string())
# `results` 数组包含 "One"、"Two"、"Three"。

注意：Godot 的 regex 实现基于的是 PCRE2。你可以查看完整的模式参考这里。

提示：你可以使用 Regexr 来在线测试正则表达式。

方法

void	clear()
Error	compile(pattern: String)
RegEx	create_from_string(pattern: String) static
int	get_group_count() const
PackedStringArray	get_names() const
String	get_pattern() const
bool	is_valid() const
RegExMatch	search(subject: String, offset: int = 0, end: int = -1) const
Array[RegExMatch]	search_all(subject: String, offset: int = 0, end: int = -1) const
String	sub(subject: String, replacement: String, all: bool = false, offset: int = 0, end: int = -1) const

方法说明

void clear() 🔗

这个方法重置了对象的状态，就像它是新创建的一样。也就是说，它取消了这个对象的正则表达式的赋值。

Error compile(pattern: String) 🔗

编译并指定要使用的搜索模式。如果编译成功，返回 @GlobalScope.OK。如果遇到错误，细节将被打印到标准输出，并返回一个错误。

RegEx create_from_string(pattern: String) static 🔗

创建并编译新 RegEx 对象。

int get_group_count() const 🔗

返回编译模式中捕获组的数量。

PackedStringArray get_names() const 🔗

返回一个数组，该数组是编译模式中命名的捕获组的名称。它们是按外观排序的。

String get_pattern() const 🔗

返回被编译的原始搜索模式。

bool is_valid() const 🔗

返回此对象是否分配了有效的搜索模式。

RegExMatch search(subject: String, offset: int = 0, end: int = -1) const 🔗

在文本中搜索编译后的模式。如果找到，则将首个匹配结果放在 RegExMatch 容器中返回，否则返回 null。

可以使用 offset 和 end 指定要搜索的区域。这对在上一次成功后再次调用该方法，以相同的 subject 搜索另一个匹配项时很有用。请注意，设置这些参数不同于传递缩短后的字符串。例如，起始锚点 ^ 不受 offset 的影响，会为单词边界 \b 检查 offset 之前的字符。

Array[RegExMatch] search_all(subject: String, offset: int = 0, end: int = -1) const 🔗

在文本中搜索编译后的模式。返回 RegExMatch 容器的数组，其中每个容器包含的是互不重叠的匹配结果。如果没有找到结果，则返回一个空数组。

String sub(subject: String, replacement: String, all: bool = false, offset: int = 0, end: int = -1) const 🔗

在文本中搜索编译后的模式，并将其替换为指定的字符串。诸如 $1 和 $name 等转义和反向引用会被扩展和解析。默认情况下，只有第一个实例被替换，但可以修改为针对所有实例（全局替换）。