Lib.rs

› 操作系统 › Windows APIs | 文本处理
#regex #glibc #libgnurx #regexec #regcomp

sys gnurx-sys

将glibc中的正则表达式功能提取到独立的库中，用于Win32

由 Koutheir Attouchi 编写

14个版本

0.3.8 2024年3月27日
0.3.7 2023年11月1日
0.3.6 2023年6月7日
0.3.4 2022年11月23日
0.2.0 2020年11月6日

#29 in Windows APIs

LGPL-2.1-or-later

325KB
8K SLoC

C 8K SLoC // 0.1% comments Rust 285 SLoC M4 83 SLoC // 0.6% comments

包含 (autotools混淆代码，120KB) libgnurx/configure，(autoconf混淆代码，4KB) libgnurx/configure.ac

crates.io docs.rs license

gnurx-sys：对 libgnurx 的不安全Rust绑定

这是从 glibc 提取的正则表达式功能，作为独立的库，用于Win32。请参阅C库的 README。

regcomp()，regexec()，regerror() 和 regfree() 是POSIX正则表达式函数。它们符合 POSIX.1-2001 和 POSIX.1-2008 标准。它们定义如下

extern "C" {
    pub fn regcomp(
        preg: *mut regex_t,
        pattern: *const c_char,
        cflags: c_int,
    ) -> c_int;

    pub fn regexec(
        preg: *const regex_t,
        string: *const c_char,
        nmatch: usize,
        pmatch: *mut regmatch_t,
        eflags: c_int,
    ) -> c_int;

    pub fn regerror(
        errcode: c_int,
        preg: *const regex_t,
        errbuf: *mut c_char,
        errbuf_size: usize,
    ) -> usize;

    pub fn regfree(preg: *mut regex_t);
}

POSIX正则表达式编译

regcomp() 用于将正则表达式编译成适合后续 regexec() 搜索的形式。

regcomp() 使用 preg，一个指向模式缓冲存储区域的指针；pattern，一个指向以null结尾的字符串的指针和 cflags，用于确定编译类型的标志。

所有正则表达式搜索都必须通过编译后的模式缓冲区进行，因此必须始终为 regexec() 提供由 regcomp() 初始化的模式缓冲区的地址。

cflags 可以是以下一个或多个的按位或组合

  • REG_EXTENDED：在解释正则表达式时使用 POSIX 扩展正则表达式语法。如果没有设置，则使用 POSIX 基本正则表达式语法。

  • REG_ICASE：不区分大小写。使用此模式缓冲区进行的后续 regexec() 搜索将不区分大小写。

  • REG_NOSUB：不报告匹配位置。如果提供的模式缓冲区是在设置了此标志的情况下编译的，则忽略 regexec() 的 nmatch 和 pmatch 参数。

  • REG_NEWLINE：匹配任意字符运算符不匹配换行符。

    • 不包含换行符的非匹配列表（[^...]）不匹配换行符。
    • 行首匹配运算符（^）匹配换行符后的空字符串，无论 eflags（regexec() 的执行标志）是否包含 REG_NOTBOL。
    • 行尾匹配运算符（$）匹配换行符前的空字符串，无论 eflags 是否包含 REG_NOTEOL。

POSIX 正则表达式匹配

regexec() 用于将空终止的字符串与预编译的模式缓冲区 preg 进行匹配。使用 nmatch 和 pmatch 提供有关任何匹配位置的信息。 eflags 可以是 REG_NOTBOL 和 REG_NOTEOL 的按位或之一，这会改变以下描述的匹配行为

  • REG_NOTBOL：行首匹配运算符始终无法匹配（但请参阅上面的编译标志 REG_NEWLINE）。当将字符串的不同部分传递给 regexec() 且字符串的起始不应被视为行首时，可以使用此标志。

  • REG_NOTEOL：行尾匹配运算符始终无法匹配（但请参阅上面的编译标志 REG_NEWLINE）。

字节偏移量

除非为模式缓冲区的编译设置了 REG_NOSUB，否则可以获取匹配地址信息。

pmatch 必须至少有 nmatch 个元素。这些元素由 regexec() 用子串匹配地址填充。从第 i 个开括号开始的子表达式的偏移量存储在 pmatch[i] 中。

整个正则表达式的匹配地址存储在 pmatch[0] 中。（注意，为了返回子表达式匹配的偏移量，nmatch 必须至少为 N + 1。）

未使用的结构元素将包含值 -1。

regmatch_t 结构，它是 pmatch 的类型，定义如下：

pub struct regmatch_t {
    pub rm_so: regoff_t,
    pub rm_eo: regoff_t,
}

每个不是 -1 的 rm_so 元素指示字符串中下一个最大子字符串匹配的起始偏移量。

相对的 rm_eo 元素指示匹配的结束偏移量，即匹配文本后的第一个字符的偏移量。

POSIX 错误报告

regerror() 用于将 regcomp() 和 regexec() 可以返回的错误代码转换为错误信息字符串。

regerror() 接收错误代码，errcode，模式缓冲区，preg，一个指向字符字符串缓冲区的指针，errbuf，以及字符串缓冲区的大小，errbuf_size。

它返回包含空终止错误信息字符串所需的 errbuf 的大小。如果 errbuf 和 errbuf_size 都是非零的，则 errbuf 用错误信息的第一个 errbuf_size - 1 个字符填充，并以终止空字节 (\0) 结尾。

POSIX 模式缓冲区释放

使用预编译的模式缓冲区，preg 传递 regfree() 将释放编译过程为模式缓冲区分配的内存。

返回值和错误

regcomp() 在成功编译时返回零。在失败时，它返回以下错误之一（请参阅 reg_errcode_t）

  • REG_BADBR：不正确使用反向引用运算符。
  • REG_BADPAT：不正确使用模式运算符，例如分组或列表。
  • REG_BADRPT：不正确使用重复运算符，例如将 * 用作第一个字符。
  • REG_EBRACE：不匹配大括号区间运算符。
  • REG_EBRACK：不匹配括号列表运算符。
  • REG_ECOLLATE：无效的排序元素。
  • REG_ECTYPE：未知字符类名称。
  • REG_EEND：非特定错误。这不是由 POSIX.2 定义的。
  • REG_EESCAPE：尾随反斜杠。
  • REG_EPAREN：不匹配括号组运算符。
  • REG_ERANGE：范围运算符使用无效；例如，范围的结束点发生在起始点之前。
  • REG_ESIZE：编译正则表达式需要大于64Kb的模式缓冲区。这不是由POSIX.2定义的。
  • REG_ESPACE：正则表达式例程耗尽内存。
  • REG_ESUBREG：对子表达式的无效后向引用。

regexec()在成功匹配时返回零，或者在失败时返回REG_NOMATCH。

线程安全性

  • regcomp()和regexec()仅在调用过程中不修改进程区域设置时是线程安全的。
  • regerror()仅在调用过程中不修改进程环境时是线程安全的。
  • regfree()是线程安全的。

支持的环境变量

此包依赖于一些环境变量及其变体。对于每个环境变量（例如，CC），以下是其接受的变体

  • <var>_<target>，例如，CC_x86_64-pc-windows-gnu。
  • <var>_<target-with-underscores>，例如，CC_x86_64_pc_windows_gnu。
  • TARGET_<var>，例如，TARGET_CC。
  • <var>，例如，CC。

以下环境变量（及其变体）影响此包的构建方式

  • GNURX_LIB_DIR_PREFIX
  • CC
  • CFLAGS
  • AR
  • ARFLAGS

链接选项

默认情况下，此包从源代码构建libgnurx并将其静态链接到它。

为了更改此行为，并指导此包动态链接到外部构建的libgnurx-0.dll库，请在构建时定义环境变量GNURX_LIB_DIR_PREFIX（或其任何变体）。GNURX_LIB_DIR_PREFIX的值需要是库安装的绝对前缀路径。预期libgnurx头文件位于<GNURX_LIB_DIR_PREFIX>/include/，共享库应位于<GNURX_LIB_DIR_PREFIX>/bin/。

依赖此包

此包为其他依赖于它的包提供以下变量

  • DEP_GNURX_INCLUDE：库C头文件所在的目录路径。
  • DEP_GNURX_LIB：库二进制文件所在的目录路径。

特定平台说明

此包只支持以下目标平台

  • x86_64-pc-windows-gnu.
  • i686-pc-windows-gnu.

这是由于libgnurx库的性质。

版本控制

本项目遵循语义化版本控制。时间推移中显著的变更细节请查看CHANGELOG.md文件。

许可证

版权所有 (c) 2020-2023 Koutheir Attouchi。

请参阅此发行版顶层目录中的LICENSE.txt文件。

根据LGPL版本2.1许可证，或其任何更新版本授权。除非按照这些条款，否则不得复制、修改或分发此文件。

依赖

约0-2.8MB
约44K SLoC