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](#ngxrematch) 行为类似，不同的是本函数返回一个 Lua 迭代器，使用户程序可以自行迭代 PCRE 正则表达式 `regex` 匹配字符串参数 `<subject>` 产生的所有结果。 当出现错误时，例如发现错误的正则表达式时，返回 `nil` 和一个描述错误的字符串。 下面用一个小例子演示基本用法： ```lua 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 循环： ```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](#ngxrematch) 相同。 在当前实现中，本函数返回的迭代器仅可被用于单一请求。也就是说，此迭代器 *不能* 被赋值给属于持久命名空间的变量，例如 Lua 包(模块)。 这个方法需要在 Nginx 中启用 PCRE 库。 ([Known Issue With Special Escaping Sequences](#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](#ngxrematch), 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: ```lua 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: ```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 ``` The optional `options` argument takes exactly the same semantics as the [ngx.re.match](#ngxrematch) 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](#special-escaping-sequences)). This feature was first introduced in the `v0.2.1rc12` release. [返回目录](#nginx-api-for-lua)