Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

RegEx

继承: RefCounted < Object

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

描述

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

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

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

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

使用 search,你可以在给定的文本中匹配模式。如果匹配到一个模式,将返回 RegExMatch,你可以使用 RegExMatch.get_stringRegExMatch.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 ( String pattern )

RegEx

create_from_string ( String pattern ) static

int

get_group_count ( ) const

PackedStringArray

get_names ( ) const

String

get_pattern ( ) const

bool

is_valid ( ) const

RegExMatch

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

RegExMatch[]

search_all ( String subject, int offset=0, int end=-1 ) const

String

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


方法说明

void clear ( )

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


Error compile ( String pattern )

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


RegEx create_from_string ( String pattern ) static

创建并编译新 RegEx 对象。


int get_group_count ( ) const

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


PackedStringArray get_names ( ) const

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


String get_pattern ( ) const

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


bool is_valid ( ) const

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


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

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


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

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

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


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

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

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