WPL 函数参考

本文档提供所有 WPL 函数的标准化参考。

📋 WPL 所有函数速查

预处理管道函数

选择器函数

字段集操作函数（f_ 前缀）

活跃字段操作函数

转换函数

常用场景速查

预处理管道函数

decode/base64

说明： 对整行输入进行 Base64 解码

语法：

|decode/base64|

参数： 无

示例：

rule base64_log {
  |decode/base64|
  (json(chars@user, digit@code))
}

输入（Base64）：

eyJ1c2VyIjoiYWRtaW4iLCJjb2RlIjoyMDB9

解码后：

{"user":"admin","code":200}

注意：

• 作用于整行原始输入
• 必须在字段解析前执行
• 解码失败会报错

decode/hex

说明： 对整行输入进行十六进制解码

语法：

|decode/hex|

参数： 无

示例：

rule hex_log {
  |decode/hex|
  (chars:data)
}

输入：

48656c6c6f20576f726c64

输出：

data: Hello World

unquote/unescape

说明： 移除外层引号并还原反斜杠转义

语法：

|unquote/unescape|

参数： 无

示例：

rule unescape_log {
  |unquote/unescape|
  (chars:message)
}

转换效果：

plg_pipe/

说明： 自定义预处理扩展

语法：

|plg_pipe/<name>|

参数： <name> - 注册的扩展名称

示例：

rule custom_preproc {
  |plg_pipe/dayu|
  (json(_@_origin, _@payload/packet_data))
}

注意：

• 需要通过代码注册扩展
• 注册接口：wpl::register_wpl_pipe!

选择器函数

take

说明： 选择指定字段为活跃字段

语法：

|take(<field_name>)|

参数：

• field_name - 要选择的字段名

返回： 无（改变活跃字段状态）

示例：

rule take_example {
  (
    json(chars@name, digit@age)
    |take(name)              # 选择 name 为活跃字段
    |chars_has(admin)        # 验证 name 的值
  )
}

使用场景：

• 需要对特定字段进行验证
• 链式验证多个字段

last

说明： 选择最后一个字段为活跃字段

语法：

|last()|

参数： 无

返回： 无（改变活跃字段状态）

示例：

rule last_example {
  (
    json(chars@a, chars@b, chars@c)
    |last()                  # 选择 c 为活跃字段
    |chars_has(value)        # 验证 c 的值
  )
}

字段集操作函数

f_has

说明： 检查指定字段是否存在

语法：

|f_has(<field_name>)|

参数：

• field_name - 要检查的字段名

返回： 布尔值（字段存在返回 true，否则失败）

示例：

rule check_field {
  (json |f_has(status) |f_has(message))
}

f_chars_has

说明： 检查指定字段值是否等于字符串

语法：

|f_chars_has(<field_name>, <value>)|

参数：

• field_name - 字段名（或 _ 表示活跃字段）
• value - 要匹配的字符串值

返回： 布尔值

示例：

rule check_string {
  (json |f_chars_has(status, success))
}

f_chars_not_has

说明： 检查指定字段值是否不等于字符串

语法：

|f_chars_not_has(<field_name>, <value>)|

参数：

• field_name - 字段名
• value - 不应匹配的字符串值

返回： 布尔值

示例：

rule exclude_error {
  (json |f_chars_not_has(level, error))
}

f_chars_in

说明： 检查指定字段值是否在字符串列表中

语法：

|f_chars_in(<field_name>, [<value1>, <value2>, ...])|

参数：

• field_name - 字段名
• [...] - 允许的字符串值列表

返回： 布尔值

示例：

rule check_method {
  (json |f_chars_in(method, [GET, POST, PUT]))
}

f_digit_has

说明： 检查指定字段数值是否等于指定数字

语法：

|f_digit_has(<field_name>, <number>)|

参数：

• field_name - 字段名
• number - 要匹配的数字

返回： 布尔值

示例：

rule check_status {
  (json |f_digit_has(code, 200))
}

f_digit_in

说明： 检查指定字段数值是否在数字列表中

语法：

|f_digit_in(<field_name>, [<num1>, <num2>, ...])|

参数：

• field_name - 字段名
• [...] - 允许的数字值列表

返回： 布尔值

示例：

rule check_success {
  (json |f_digit_in(status, [200, 201, 204]))
}

f_ip_in

说明： 检查指定 IP 字段是否在 IP 列表中

语法：

|f_ip_in(<field_name>, [<ip1>, <ip2>, ...])|

参数：

• field_name - 字段名
• [...] - 允许的 IP 地址列表（支持 IPv4/IPv6）

返回： 布尔值

示例：

rule check_trusted {
  (json |f_ip_in(client_ip, [127.0.0.1, 192.168.1.1]))
}

活跃字段操作函数

has

说明： 检查活跃字段是否存在

语法：

|has()|

参数： 无

返回： 布尔值

示例：

rule check_active {
  (
    json(chars@name)
    |take(name)
    |has()                   # 检查 name 是否存在
  )
}

chars_has

说明： 检查活跃字段值是否等于指定字符串

语法：

|chars_has(<value>)|

参数：

• value - 要匹配的字符串值

返回： 布尔值

示例：

rule check_value {
  (
    json(chars@status)
    |take(status)
    |chars_has(success)
  )
}

chars_not_has

说明： 检查活跃字段值是否不等于指定字符串

语法：

|chars_not_has(<value>)|

参数：

• value - 不应匹配的字符串值

返回： 布尔值

示例：

rule exclude_value {
  (
    json(chars@level)
    |take(level)
    |chars_not_has(error)
  )
}

chars_in

说明： 检查活跃字段值是否在字符串列表中

语法：

|chars_in([<value1>, <value2>, ...])|

参数：

• [...] - 允许的字符串值列表

返回： 布尔值

示例：

rule check_method {
  (
    json(chars@method)
    |take(method)
    |chars_in([GET, POST, PUT])
  )
}

digit_has

说明： 检查活跃字段数值是否等于指定数字

语法：

|digit_has(<number>)|

参数：

• number - 要匹配的数字

返回： 布尔值

示例：

rule check_code {
  (
    json(digit@code)
    |take(code)
    |digit_has(200)
  )
}

digit_in

说明： 检查活跃字段数值是否在数字列表中

语法：

|digit_in([<num1>, <num2>, ...])|

参数：

• [...] - 允许的数字值列表

返回： 布尔值

示例：

rule check_success {
  (
    json(digit@status)
    |take(status)
    |digit_in([200, 201, 204])
  )
}

ip_in

说明： 检查活跃 IP 字段是否在 IP 列表中

语法：

|ip_in([<ip1>, <ip2>, ...])|

参数：

• [...] - 允许的 IP 地址列表（支持 IPv4/IPv6）

返回： 布尔值

示例：

rule check_client {
  (
    json(ip@client_ip)
    |take(client_ip)
    |ip_in([127.0.0.1, 192.168.1.1])
  )
}

转换函数

json_unescape

说明： 对活跃字段进行 JSON 反转义

语法：

|json_unescape()|

参数： 无

转换效果：

示例：

rule parse_json_log {
  (
    json(chars@message)
    |take(message)
    |json_unescape()
  )
}

base64_decode

说明： 对活跃字段进行 Base64 解码

语法：

|base64_decode()|

参数： 无

转换效果：

示例：

rule decode_payload {
  (
    json(chars@payload)
    |take(payload)
    |base64_decode()
  )
}

📊 函数对照表

字段集 vs 活跃字段

💡 使用模式

链式调用

rule chain {
  (json
    |f_has(method)
    |f_chars_in(method, [GET, POST])
    |f_digit_in(status, [200, 201])
    |f_ip_in(client_ip, [10.0.0.1])
  )
}

选择器 + 验证

rule selector {
  (json(chars@name, digit@age)
    |take(name)
    |chars_has(admin)
    |take(age)
    |digit_in([18, 19, 20])
  )
}

预处理 + 字段级管道

rule full {
  |decode/base64|                      # 预处理：整行解码
  (json |f_has(name) |f_digit_in(age, [18, 25]))  # 字段级：验证
}

相关文档

• 快速入门：01-quickstart.md
• 核心概念：02-core-concepts.md
• 实战指南：03-practical-guide.md
• 语言参考：04-language-reference.md
• 语法规范：06-grammar-reference.md