WPL 语言参考

本文档提供 WPL 的完整语言元素参考，用于快速查阅类型、语法和结构。

📑 文档导航

📋 类型系统

基础类型

时间类型

网络类型

编码类型

结构化类型

协议类型

特殊类型

🔧 语法元素

基本结构

package 包名 {
  rule 规则名 {
    |预处理管道|
    (字段列表)
  }
}

字段定义完整语法

[N*] DataType [ (symbol) ] [ (subfields) ] [:name] [ [len] ] [ format ] [ sep ] { | pipe }

格式控制

分组元信息

分隔符优先级

字段级(3) > 组级(2) > 上游(1)

🎯 子字段语法

JSON 子字段

json(type@key, type@key, ...)

示例：

# 基本提取
json(chars@name, digit@age)

# 嵌套路径
json(chars@user/name, digit@user/age)

# 可选字段
json(chars@name, opt(chars)@email)

bad_json

bad_json:name

说明：

• bad_json 输出的是原始文本，字段类型为 chars
• 适合接住“看起来像 JSON，但严格解析失败”的输入
• 推荐与 json_like 预处理一起使用，避免把普通文本误判为坏 JSON

示例：

(bad_json:raw)

🧩 JSON-like 路由

json_like 预处理

|json_like|

语义：

• 这是规则前置的行 pipe
• 只做轻量 sniff，判断当前输入是否“像 JSON”
• 它不会提取字段，也不会做完整 JSON 解析

json_like 适合放在兜底规则前面，为 bad_json 提供保护。

json 的内置 sniff

json 现在已经内置了 json_like 式的快速判断，所以：

rule good_json {
  (json(chars@host, chars@method))
}

不需要再额外写：

rule good_json {
  |json_like|
  (json(chars@host, chars@method))
}

推荐写法

当你希望把“合法 JSON”和“坏 JSON”分开处理时，推荐这样写：

rule good_json {
  (json(chars@host, chars@method))
}

rule broken_json {
  |json_like|
  (bad_json:raw)
}

这套写法的行为是：

• 合法 JSON：由 json(...) 规则命中
• 损坏但像 JSON：由 json_like + bad_json 规则兜底
• 普通文本：不会被 bad_json 吃掉

性能含义

• json_like 是轻量判断，适合做前置过滤
• json 已经内置快速 sniff，因此对普通文本的拒绝成本明显更低
• 对“像 JSON 但损坏”的输入，先做 json_like 再走 bad_json 才有意义

KV 子字段

kvarr(type@key, type@key, ...)

示例：

kvarr(chars@hostname, digit@port, opt(chars)@user)

数组

array[/subtype]

示例：

array/digit:nums          # [1,2,3]
array/chars:items         # ["a","b"]
array/array/digit         # 嵌套数组

📝 注解

tag 注解

#[tag(key1:"value1", key2:"value2")]
package demo {
  rule x { (digit, time) }
}

copy_raw 注解

#[copy_raw(name:"raw_log")]
rule nginx_log {
  (ip, time, chars)
}

原始字符串（避免转义）

#[tag(path:r#"C:\Program Files\App"#)]
package demo {
  rule x { (digit) }
}

💡 语法速查

常用模式

# 字段命名
type:name              # digit:status

# 忽略字段
_                      # 忽略 1 个
N*_                    # 忽略 N 个

# 重复模式
kvarr                  # 自动解析KV
N*ip                   # 固定 N 次

# 可选分组
opt(chars:tag)         # 单个可选分组
opt(kvarr)             # 可选 KV 分组

# 格式控制
<[,]>                  # 方括号包裹
"                      # 引号包裹
^10                    # 固定 10 字符

# 分隔符
\,                     # 逗号
\;                     # 分号
\0                     # 行尾

# 子字段
json(chars@key)        # JSON 字段
kvarr(digit@port)      # KV 字段
@path/to/field         # 嵌套路径

相关文档

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