ngxresub.md

ngx.re.sub

语法: newstr, n, err = ngx.re.sub(subject, regex, replace, options?)

环境: init_worker_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*

使用 Perl 兼容正则表达式 regex 匹配字符串 subject，将第一个结果替换为字符串或函数类型参数 replace。可选参数 options 含义与 ngx.re.match 相同。

这个方法返回结果字符串以及成功替换的数量。当发生失败时，例如正则表达式或 <replace> 字符串参数语法错，将返回 nil 以及一个描述错误的字符串。

当 replace 是一个字符串时，它们被视为一个特殊字符串替换模板。例如：

 local newstr, n, err = ngx.re.sub("hello, 1234", "([0-9])[0-9]", "[$0][$1]")
 if newstr then
     -- newstr == "hello, [12][1]34"
     -- n == 1
 else
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

其中 $0 指模板匹配的完整子字符串，$1 指第一个括号内匹配的子串。

花括号可以被用来从背景字符串中消除变量名歧义。

 local newstr, n, err = ngx.re.sub("hello, 1234", "[0-9]", "${0}00")
     -- newstr == "hello, 100234"
     -- n == 1

要在 replace 中使用美元字符($)，可以使用另外一个该符号作为转义，例如，

 local newstr, n, err = ngx.re.sub("hello, 1234", "[0-9]", "$$")
     -- newstr == "hello, $234"
     -- n == 1

不要使用反斜线转义美元字符；它不会象你想象的那样工作。

当 replace 参数是一个 "函数" 时，它将被通过参数 "匹配表" 调用，用来生成替换字符串。被送入 replace 函数的 "匹配表" 与 ngx.re.match 的返回值相同。例如：

 local func = function (m)
     return "[" .. m[0] .. "][" .. m[1] .. "]"
 end
 local newstr, n, err = ngx.re.sub("hello, 1234", "( [0-9] ) [0-9]", func, "x")
     -- newstr == "hello, [12][1]34"
     -- n == 1

在 replace 函数返回值中的美元字符没有任何特殊含义。

这个方法需要在 Nginx 中启用 PCRE 库。 (Known Issue With Special Escaping Sequences).

这个功能最早出现在 v0.2.1rc13 版本中。

English Source

syntax: newstr, n, err = ngx.re.sub(subject, regex, replace, options?)

context: init_worker_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*

Substitutes the first match of the Perl compatible regular expression regex on the subject argument string with the string or function argument replace. The optional options argument has exactly the same meaning as in ngx.re.match.

This method returns the resulting new string as well as the number of successful substitutions. In case of failures, like syntax errors in the regular expressions or the <replace> string argument, it will return nil and a string describing the error.

When the replace is a string, then it is treated as a special template for string replacement. For example,

 local newstr, n, err = ngx.re.sub("hello, 1234", "([0-9])[0-9]", "[$0][$1]")
 if newstr then
     -- newstr == "hello, [12][1]34"
     -- n == 1
 else
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

where $0 referring to the whole substring matched by the pattern and $1 referring to the first parenthesized capturing substring.

Curly braces can also be used to disambiguate variable names from the background string literals:

 local newstr, n, err = ngx.re.sub("hello, 1234", "[0-9]", "${0}00")
     -- newstr == "hello, 100234"
     -- n == 1

Literal dollar sign characters ($) in the replace string argument can be escaped by another dollar sign, for instance,

 local newstr, n, err = ngx.re.sub("hello, 1234", "[0-9]", "$$")
     -- newstr == "hello, $234"
     -- n == 1

Do not use backlashes to escape dollar signs; it will not work as expected.

When the replace argument is of type "function", then it will be invoked with the "match table" as the argument to generate the replace string literal for substitution. The "match table" fed into the replace function is exactly the same as the return value of ngx.re.match. Here is an example:

 local func = function (m)
     return "[" .. m[0] .. "][" .. m[1] .. "]"
 end
 local newstr, n, err = ngx.re.sub("hello, 1234", "( [0-9] ) [0-9]", func, "x")
     -- newstr == "hello, [12][1]34"
     -- n == 1

The dollar sign characters in the return value of the replace function argument are not special at all.

This method requires the PCRE library enabled in Nginx. (Known Issue With Special Escaping Sequences).

This feature was first introduced in the v0.2.1rc13 release.

返回目录