ngxregmatch.md

ngx.re.gmatch

语法: iterator, err = ngx.re.gmatch(subject, regex, 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.*

与 ngx.re.match 行为类似，不同的是本函数返回一个 Lua 迭代器，使用户程序可以自行迭代 PCRE 正则表达式 regex 匹配字符串参数 <subject> 产生的所有结果。

当出现错误时，例如发现错误的正则表达式时，返回 nil 和一个描述错误的字符串。

下面用一个小例子演示基本用法：

 local iterator, err = ngx.re.gmatch("hello, world!", "([a-z]+)", "i")
 if not iterator then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

 local m
 m, err = iterator()    -- m[0] == m[1] == "hello"
 if err then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

 m, err = iterator()    -- m[0] == m[1] == "world"
 if err then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

 m, err = iterator()    -- m == nil
 if err then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

更常见的是使用 Lua 循环：

 local it, err = ngx.re.gmatch("hello, world!", "([a-z]+)", "i")
 if not it then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

 while true do
     local m, err = it()
     if err then
         ngx.log(ngx.ERR, "error: ", err)
         return
     end

     if not m then
         -- no match found (any more)
         break
     end

     -- found a match
     ngx.say(m[0])
     ngx.say(m[1])
 end

可选参数 options 含义与使用方法与 ngx.re.match 相同。

在当前实现中，本函数返回的迭代器仅可被用于单一请求。也就是说，此迭代器 不能 被赋值给属于持久命名空间的变量，例如 Lua 包(模块)。

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

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

English Source

syntax: iterator, err = ngx.re.gmatch(subject, regex, 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.*

Similar to ngx.re.match, but returns a Lua iterator instead, so as to let the user programmer iterate all the matches over the <subject> string argument with the PCRE regex.

In case of errors, like seeing an ill-formed regular expression, nil and a string describing the error will be returned.

Here is a small example to demonstrate its basic usage:

 local iterator, err = ngx.re.gmatch("hello, world!", "([a-z]+)", "i")
 if not iterator then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

 local m
 m, err = iterator()    -- m[0] == m[1] == "hello"
 if err then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

 m, err = iterator()    -- m[0] == m[1] == "world"
 if err then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

 m, err = iterator()    -- m == nil
 if err then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

More often we just put it into a Lua loop:

 local it, err = ngx.re.gmatch("hello, world!", "([a-z]+)", "i")
 if not it then
     ngx.log(ngx.ERR, "error: ", err)
     return
 end

 while true do
     local m, err = it()
     if err then
         ngx.log(ngx.ERR, "error: ", err)
         return
     end

     if not m then
         -- no match found (any more)
         break
     end

     -- found a match
     ngx.say(m[0])
     ngx.say(m[1])
 end

The optional options argument takes exactly the same semantics as the ngx.re.match method.

The current implementation requires that the iterator returned should only be used in a single request. That is, one should not assign it to a variable belonging to persistent namespace like a Lua package.

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

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

返回目录