使用指南

WarpParse 核心概念速查

本文档帮助零基础用户快速理解 WarpParse 的核心概念和术语。

什么是 ETL？

ETL 是 Extract（提取）、Transform（转换）、Load（加载）的缩写。简单来说：

• Extract（提取）：从日志文件、数据库、消息队列等地方读取原始数据
• Transform（转换）：把非结构化的文本转换成结构化的数据（如 JSON）
• Load（加载）：把处理好的数据存储到目标位置（文件、数据库、ES 等）

类比理解

就像一个智能快递分拣系统：

• Extract = 收件（从各个地方收集包裹）
• Transform = 分类（按地址、类型分类打标签）
• Load = 派送（送到对应的目的地）

WarpParse 核心术语

数据流转过程

原始日志 → [Source 读取] → [WPL 解析] → [OML 转换] → [Sink 输出] → 目标存储
   ↓              ↓              ↓              ↓              ↓
文件/TCP      connectors     提取字段       组装对象      文件/DB/ES

详细说明

1. Source 读取：从配置的数据源读取原始数据

   • 文件：读取日志文件
   • TCP：监听网络端口接收数据
   • Kafka：从消息队列消费数据

2. WPL 解析：使用 WPL 规则从原始文本中提取字段

   • 识别 IP 地址、时间、数字等类型
   • 解析 JSON、KV 等结构化数据
   • 验证和过滤字段

3. OML 转换：使用 OML 规则组装输出格式

   • 字段重命名和映射
   • 类型转换（字符串→数字→时间）
   • 条件判断和计算

4. Sink 输出：将处理后的数据写入目标

   • 文件：保存为 JSON/CSV 等格式
   • 数据库：写入 MySQL/PostgreSQL
   • 搜索引擎：写入 Elasticsearch

快速入门路径

阶段一：
1、跑通 Getting Started，看到数据流转起来
2、学习 WPL 基础类型（ip、digit、time、chars）
3、学习 OML 数据组装
4、在 editor 学习了解 demo 样例

阶段二：
1、在 editor 上开始完成 T1 题目
2、在自己空间下创建 wpl和oml
3、配置 Source 和 Sink
4、使用 wpgen 生成样例数据，wparse 进行执行查看输出

项目目录结构

工作目录/
├── conf/              # 配置文件
│   ├── wparse.toml   # 解析引擎配置
│   └── wpgen.toml    # 数据生成器配置
│
├── connectors/        # 连接器定义
│   ├── sink.d/       # 输出连接器（数据去哪里）
│   └── source.d/     # 输入连接器（数据从哪来）
│
├── data/              # 数据目录
│   ├── in_dat/       # 输入数据（原始日志）
│   │   └── gen.dat  # 生成的测试数据
│   ├── out_dat/      # 输出数据（解析结果）
│   │   ├── demo.json       # 所有成功解析的记录
│   │   ├── default.dat     # 命中wpl未命中oml异常数据
│   │   ├── error.dat       # 异常数据
│   │   ├── miss.dat        # 未命中wpl异常数据
│   │   ├── monitor.dat     # 监控数据
│   │   └── residue.dat     # 残留数据（部分解析成功）
│   ├── logs/         # 运行日志
│   └── rescue/       # 失败数据（用于排查问题）
│
├── models/            # 模型定义
│   ├── wpl/          # WPL 解析规则
│   │   └── wp-space/
│   │       ├── parse.wpl    # 解析规则文件
│   │       └── sample.dat   # 规则测试样本
│   ├── oml/          # OML 转换规则
│   │   └── wp-space/
│   │       └── adm.oml      # 对象映射规则
│   └── knowledge/    # 知识库（SQL 查询等）
│
└── topology/          # 拓扑配置
    ├── sources/      # 数据源配置
    └── sinks/        # 数据目标配置

目录说明

• conf/：全局配置，如日志级别、性能参数
• connectors/：定义如何连接数据源和目标
• data/：所有数据文件的存放位置
  • in_dat/：存放原始输入数据
    • gen.dat：wpgen 生成的测试数据
  • out_dat/：存放解析后的输出数据
    • all.json：所有成功解析的记录（JSON 格式）
    • default.dat：默认输出文件
    • error.dat：解析过程中出错的记录
    • ignore.dat：根据规则被忽略的记录
    • miss.dat：缺失必需字段的记录
    • monitor.dat：监控和统计数据
    • residue.dat：部分字段解析成功的残留数据
  • logs/：运行时日志，用于调试和排查问题
  • rescue/：解析失败的原始数据，用于重新处理
• models/：核心业务逻辑（WPL 规则和 OML 规则）
  • wpl/：WPL 解析规则，按命名空间组织
    • wp-space/parse.wpl：具体的解析规则文件
    • wp-space/sample.dat：规则对应的测试样本
  • oml/：OML 转换规则，按命名空间组织
    • wp-space/adm.oml：对象映射和转换规则
  • knowledge/：知识库，如 SQL 查询、IP 库等
• topology/：数据流拓扑配置

常用命令速查

下一步

阅读完本文档后，建议按以下顺序学习：

1. 快速入门：10 分钟跑通第一个示例
2. WPL 语言基础：学习数据提取规则
3. OML 语言基础：学习数据组装规则

相关文档

• 快速入门
• CLI 工具集
• WPL 语言
• OML 语言

CLI 工具集

本文档集合介绍 WarpParse提供的完整命令行工具集，包括数据解析、生成、项目管理等功能。

工具总览

核心工具

快速参考

wparse - 数据解析引擎

# 守护进程模式（持续运行）
wparse daemon --work-root ./myproject --stat-print

# 批处理模式
wparse batch --work-root ./myproject --max-line 10000 --stat 5

wpgen - 数据生成器

# 基于规则生成数据
wpgen rule --work-root ./myproject --print-stat --line-cnt 10000

# 基于样本生成数据
wpgen sample --work-root ./myproject --line-cnt 5000

# 配置管理
wpgen conf init
wpgen conf check
wpgen conf clean

# 数据管理
wpgen data clean
wpgen data check

wproj - 项目管理工具

# 项目初始化
wproj init --mode full

# 项目检查
wproj check

# 数据清理
wproj data clean

# 统计功能
wproj stat file
wproj stat file --output json

# 模型管理
wproj model list
wproj model validate

# 规则工具
wproj rule parse --rule-id myrule
wproj rule test --input sample.log

# 配置管理
wproj sinks list
wproj sinks validate
wproj sinks route

wprescue - 数据恢复工具

# 批处理模式恢复数据
wprescue batch --work-root ./myproject

工具关系图

graph TD
    A[wproj] --> B[初始化项目]
    A --> C[检查配置]
    A --> D[统计数据]

    B --> E[生成配置文件]
    B --> F[创建目录结构]

    C --> G[验证配置有效性]

    D --> H[源数据统计]
    D --> I[输出数据统计]

    J[wpgen] --> K[生成测试数据]
    J --> L[管理生成器配置]
    J --> M[管理输出数据]

    N[wparse] --> O[实时流处理]
    N --> P[批处理分析]
    N --> Q[性能调优]

    R[wprescue] --> S[数据恢复]
    R --> T[故障恢复]

学习路径

1. 初学者：从 快速入门指南 开始，了解完整的配置和使用流程
2. 进阶用户：深入学习 wparse 运行模式，理解两种运行模式的区别和适用场景
3. 数据工程师：掌握 wpgen 使用指南，能够生成各种测试数据
4. 运维人员：使用 wproj 项目管理 进行日常的项目管理和监控
5. 故障处理：参考 wprescue 数据恢复 处理异常情况

常见使用场景

实时流处理

# 启动守护进程，持续处理数据流
wparse daemon \
  --work-root ./myproject \
  --stat-print \
  --robust online

批量数据分析

# 批处理分析历史数据
wparse batch \
  --work-root ./myproject \
  --max-line 100000 \
  --check-continue 1000 \
  --stat 10

开发测试

# 开发模式，详细日志
wparse batch \
  --work-root ./myproject \
  --log-profile dev \
  --max-line 100 \
  --stat 1

数据生成测试

# 生成特定场景的测试数据
wpgen rule \
  --work-root ./myproject \
  --conf-name test.toml \
  --line-cnt 10000 \
  --gen-speed 1000

故障排除

常见问题

1. 配置文件找不到

   • 确保在正确的工作目录下运行命令
   • 使用 --work-root 参数指定工作目录

2. 权限错误

   • 检查工作目录和日志目录的写权限
   • 确保有足够的磁盘空间

3. 内存不足

   • 减少 --max-line 或 --parse-workers 参数值
   • 使用 --robust 参数设置合适的鲁棒模式

4. 数据源连接失败

   • 检查 connectors/source.d/ 目录下的连接器配置
   • 验证网络连接和认证信息

日志分析

# 查看实时日志
tail -f logs/wparse.log

# 搜索错误日志
grep -i error logs/*.log

# 使用 wproj 进行项目检查
wproj check --work-root ./myproject

版本信息

查看工具版本：

wparse --version
wpgen --version
wproj --version
wprescue --version

环境变量

退出码

技术架构

CLI 工具采用 Rust 编写，使用 clap 框架处理命令行参数，tokio 异步运行时。核心功能通过 wp-engine 库的 facade 模式对外暴露，确保 API 稳定性和向后兼容性。

项目结构

warp-parse/
├── src/
│   ├── wparse/          # 数据解析引擎
│   │   └── main.rs
│   ├── wpgen/            # 数据生成器
│   │   ├── main.rs
│   │   ├── cli.rs       # CLI 定义
│   │   ├── rule.rs      # 规则生成逻辑
│   │   ├── sample.rs    # 样本生成逻辑
│   │   ├── conf.rs      # 配置管理
│   │   └── data.rs      # 数据管理
│   ├── wproj/            # 项目管理
│   │   └── main.rs
│   └── wprescue/         # 数据恢复
│       └── main.rs
└── wp-engine/            # 核心引擎库
    └── facade/args.rs    # 参数定义

这种设计确保了：

1. 模块化：每个工具职责单一，易于维护
2. 复用性：核心功能通过库共享
3. 可扩展性：便于添加新的 CLI 工具

相关链接

• 项目主页
• 下载页面
• 配置参考
• 用户文档

GettingStarted

前置准备

• 下载 wparse
• copy到可执行路径下。如 /usr/local/bin 或 /${HOME}/bin

一、初始化工作目录

• 清理并初始化配置与模板

  wproj init --mode full
  wproj check 
  

执行完成后，工作目录将包含：

├── conf
│   ├── wparse.toml
│   └── wpgen.toml
├── connectors
│   ├── sink.d
│   └── source.d
├── data
│   ├── in_dat
│   ├── logs
│   ├── out_dat
│   └── rescue
├── models
│   ├── knowledge
│   ├── oml
│   └── wpl
└── topology
    ├── sinks
    └── sources

二、生成数据与清理

wproj data clean 
wpgen data clean 

# 生成样本（示例 3000 行，3 秒统计间隔）
wpgen sample -n 3000 --stat 3

三、运行解析

# 批处理（-n 指定条数，-p 打印统计；失败时查看 ./logs/ 下日志）
wparse batch --stat 3 -p  

四、统计与校验

# 同时统计源与文件型 sink
wproj  data stat

Wproj

wproj 是 Warp Parse 项目管理工具，提供完整的项目生命周期管理功能，包括项目初始化和配置管理、数据源的检查和统计、模型管理和知识库创建维护。

命令概览

wproj <COMMAND>

Commands:
  rule   规则工具：解析规则的管理和调试 | Rule tools: management and debugging of parsing rules
  init   一键初始化完整工程骨架 | Initialize complete project skeleton
  check  批量检查项目配置和文件完整性 | Batch check project configuration and file integrity
  data   数据管理工具：清理、统计、验证 | Data management tools: cleanup, statistics, validation
  model  模型管理工具：规则、源、汇、知识库 | Model management tools: rules, sources, sinks, knowledge base

init - 项目初始化

一键创建项目目录结构和默认配置。

wproj init [OPTIONS]

初始化模式：

示例：

# 初始化配置（默认）
wproj init -w /project

# 初始化完整项目
wproj init -w /project --mode full

check - 项目检查

批量检查项目配置和文件完整性。

wproj check [OPTIONS]

检查项（–what）：

示例：

# 全面检查
wproj check -w /project --what all

# 仅检查配置和规则，首次失败即退出
wproj check -w /project --what conf,wpl --fail-fast

# JSON 输出，仅显示失败项
wproj check -w /project --json --only-fail

data - 数据管理

wproj data <SUBCOMMAND>

Subcommands:
  clean     清理本地输出文件
  check     检查数据源连通性
  stat      统计数据量和性能
  validate  验证数据分布和比例

data clean

清理项目输出数据。

wproj data clean

data stat

统计数据量。

wproj data stat 

data validate

验证数据分布和比例。

wproj data validate [OPTIONS]

示例：

# 清理输出数据
wproj data clean 

# 统计源+SINK文件行数
wproj data stat 

# 验证数据分布
wproj data validate 

model - 模型管理

TODO!

rule - 规则工具

离线解析测试，验证 WPL 规则。

wproj rule parse [OPTIONS]

示例：

# 使用规则执行离线解析测试
wproj rule parse 

Wparse

运行模式

• 两种运行模式：wparse daemon（常驻服务）和 wparse batch（批处理）
• 批处理模式读完文件后自动退出，daemon 模式需信号触发退出

命令行参数

wparse <COMMAND>

Commands:
  daemon  守护进程模式（常驻服务）
  batch   批处理模式（读完即退）

通用参数

使用示例

# 批处理模式：处理 3000 条后退出，每 2 秒输出统计
wparse batch -n 3000 --stat 2 -p

# 批处理模式：指定工作目录和多线程
wparse batch  -w 4 --parse-workers 4

# 守护进程模式：常驻服务，每 5 秒输出统计
wparse daemon --stat 5 -p

# 自定义日志和规则目录
wparse daemon --log-profile custom.toml --wpl /custom/rules

退出策略

批处理模式（batch）

单源（picker）结束条件（任一满足）：

• 上游 EOF（文件读取完毕）
• 收到 Stop 指令
• 致命错误（触发全局停机）

进程退出流程：

1. 所有数据源的 picker 结束
2. 主组完成
3. sink/infra 组依序下线
4. 进程退出

关键日志：

• 每个源结束：数据源 '...' picker 正常结束
• 全局收尾：all routine group await end!

守护进程模式（daemon）

• 启动 acceptor（网络监听等）
• 进程保持常驻运行
• 退出触发方式：
  • SIGTERM/SIGINT/SIGQUIT 信号
  • 控制总线 Stop 指令（企业版）

错误与重试策略

常见问题

Q：为什么 batch 下不启动 acceptor？

A：acceptor 是常驻组件（监听网络），会阻塞主组完成。batch 目标是“源结束 → 主组完成 → 进程退出“。

Wpgen

wpgen 是 WarpParse 数据生成器，用于基于WPL规则或样本文件生成测试数据。

命令概览

wpgen <COMMAND>

Commands:
  rule    Generate data by rule/基于规则生成数据
  sample  Generate data from sample files/基于样本文件生成数据
  conf    Configuration commands/配置相关命令
  data    Data management commands/数据管理相关命令

子命令详解

rule - 基于规则生成

基于 WPL 规则生成测试数据，支持规则验证和性能分析。

wpgen rule [OPTIONS]

sample - 基于样本生成

基于样本文件（sample.dat）生成测试数据。

wpgen sample [OPTIONS]

conf - 配置管理

wpgen conf <SUBCOMMAND>

Subcommands:
  init   初始化生成器配置（conf/wpgen.toml）
  clean  清理生成器配置
  check  检查配置有效性

data - 数据管理

wpgen data <SUBCOMMAND>

Subcommands:
  clean  Clean generated output data according to wpgen config/根据 wpgen 配置清理已生成输出数据
  check  Not supported; reserved for future/暂不支持；保留供未来使用

运行语义

count（总产出条数）

启动时按 parallel 精确均分到每个 worker，余数前置分配。各 worker 跑完本地任务量即退出，总量严格等于 count。

speed（全局速率）

• speed = 0：无限制（不等待）
• speed > 0：每 worker 速率为 floor(speed / parallel)

parallel（并行数）

生成 worker 的并行数。对 blackhole_sink 消费端也会并行，其它 sink 默认单消费者。

使用示例

# 配置初始化
wpgen conf init -w .
wpgen conf check -w .

# 基于规则生成 10000 条数据
wpgen sample -n 10000 -p

# 自定义规则目录和生成速度
wpgen rule 
    --wpl nginx \
    -c custom.toml \
    -s 1000 \
    --stat 2 \
    -p

# 基于样本文件生成
wpgen sample  -n 50000 -s 5000 --stat 5 -p

# 清理生成的数据
wpgen data clean -c wpgen.toml --local

常见问题

Q：产出不足预期？

A：count 被精确分配给每个 worker。检查日志中 limit : … 是否符合预期。

配置文件

默认配置文件路径：conf/wpgen.toml

主要配置项：

[generator]
count = 10000      # 总生成条数
speed = 1000       # 生成速度（行/秒），0 表示无限制
parallel = 4       # 并行 worker 数

[output]
# 输出配置...

生成文件通常位于 ./data/in_dat/，可在配置中调整目标路径。

wprescue

wprescue 是数据恢复工具，用于从救援目录中恢复数据并按照项目配置的 Sink 路由输出到目标。

命令概览

wprescue 

重要： wprescue 仅支持 batch 模式。

命令行参数

wprescue [OPTIONS]

工作原理

1. 读取救援目录（./data/rescue）中的数据
2. 按照项目配置的 Sink 路由进行处理
3. 输出到目标位置
4. 处理完成后自动退出

配置指南

本文聚焦 wparse 运行所依赖的配置。建议从“运行主配置（wparse.toml）”开始，随后按需阅读源/汇与连接器章节。

推荐阅读顺序

• Wparse 运行配置（主配置）：wparse.toml（本目录）
  • Wparse 运行配置规范（wparse.toml）
• 源（Sources）与连接器
  • 源配置总览（sources）
  • 连接器（source.d）见“源配置总览”内的查找规则与示例
• 汇（Sinks）与连接器
  • Sinks 设计与配置（目录式 V2）
  • Sinks 最小可运行骨架
  • 连接器（sink.d）与 route 细节见“设计与配置”

相关参考

• 参考参数与规格：docs/80-reference 下各 Source/Sink/Spec 文档
• CLI：docs/cli/wparse.md（快速查看常用选项）

提示

• 使用 wproj conf init --work-root . 可初始化标准目录与模板（conf/、connectors/ 与部分 models 目录）。若需要知识库（KnowDB）模板，请另行执行 wproj knowdb init。
• 修改场景流程后，建议运行 usecase/core/getting_started/case_verify.sh 验证端到端产出。

Wparse配置

完整示例（推荐默认）

version = "1.0"
robust  = "normal"           # debug|normal|strict

[models]
wpl     = "./models/wpl"
oml     = "./models/oml"

[topology]
sources = "./topology/sources"
sinks   = "./topology/sinks"

[performance]
rate_limit_rps = 10000        # 限速（records/second）
parse_workers  = 2            # 解析并发 worker 数

[rescue]
path = "./data/rescue"        

[log_conf]
output = "File"               # Console|File|Both
level  = "warn,ctrl=info"

[log_conf.file]
path = "./data/logs"          # 文件输出目录；文件名自动取可执行名（wparse.log）

[stat]

[[stat.pick]]                 # 采集阶段统计
key    = "pick_stat"
target = "*"

[[stat.parse]]                # 解析阶段统计
key    = "parse_stat"
target = "*"

[[stat.sink]]                 # 下游阶段统计
key    = "sink_stat"
target = "*"

Sources配置

概览

Source（源）是 warp-parse 系统中负责数据输入的组件，支持多种数据源和协议。采用统一的连接器架构，提供灵活的数据接入能力。

定位与目录

• 配置文件：$WORK_ROOT/topology/sources/wpsrc.toml
• 连接器定义：从 $WORK_ROOT/models/sources 起向上查找最近的 connectors/source.d/*.toml

核心概念

• 连接器：可复用的输入连接定义，包含 id/type/params/allow_override
• 参数覆写：通过白名单机制安全覆写连接器参数
• 标签系统：支持为数据源添加标签，便于路由和过滤

支持的 Source 类型

内置 Source

• file：文件输入，支持监控和轮询
• syslog：Syslog 协议输入（UDP/TCP）
• tcp：协议输入

扩展 Source

• kafka：Apache Kafka 消息队列输入

配置规则

基本规则

• 仅支持 [[sources]] + connect/params 格式
• 覆写键必须 ∈ connector allow_override 白名单；超出即报错
• enable 字段控制是否启用（默认 true）
• tags 字段支持添加数据源标签

配置结构

[[sources]]
key = "source_identifier"           # 源的唯一标识
connect = "connector_id"            # 引用的连接器 ID
enable = true                       # 是否启用（可选，默认 true）
tags = ["source:tag1", "type:log"]  # 标签（可选）
params = {                 # 参数覆写（可选）
    # 覆写连接器参数
}

配置示例

最小示例

[[sources]]
key = "file_1"
connect = "file_src"
params = { base = "data/in_dat", file = "gen.dat" }

文件输入示例

# models/sources/wpsrc.toml
[[sources]]
key = "access_log"
connect = "file_src"
params = {
    base = "./logs",
    file = "access.log",
    encode = "text"
}
tags = ["type:access", "env:prod"]

Syslog 输入示例

# models/sources/wpsrc.toml
[[sources]]
key = "syslog_udp"
connect = "syslog_udp_src"
params = {
    port = 1514,
    header_mode = "parse",
    prefer_newline = true
}
tags = ["protocol:syslog", "transport:udp"]

TCP 输入示例（通用 TCP 行/长度分帧）

# models/sources/wpsrc.toml
[[sources]]
key = "tcp_in"
connect = "tcp_src"
enable = true
params= {
  port = 19000,
  framing = "auto",
  prefer_newline = true
}

Sink 配置

目录与文件组织

• sink_root：用例内通常为 <case>/sink

  • business.d/**/*.toml：业务组路由（场景输出，支持子目录）
  • infra.d/**/*.toml：基础组路由（default/miss/residue/intercept/error/monitor，支持子目录）
  • defaults.toml：默认组级期望 [defaults.expect]

• connectors/sink.d/*.toml：连接器定义（loader 自 sink_root 向上查找最近的该目录）

路由文件格式

• 顶层
  • version（可选）
  • sink_group
    • name：组名（字符串）
    • oml / rule：推荐扁平写法；均可为字符串或字符串数组；用于匹配模型或规则。
    • expect：可选，组级期望（覆盖 defaults）
    • sinks：数组，每项为单个 sink 定义
• 单个 sink 字段
  • name：该 sink 的名称（组内唯一）；未提供则按 [index] 回退
  • connect：引用连接器 id（兼容读取 use/connector）
  • params：对连接器默认参数的白名单覆盖（keys 必须在连接器 allow_override 列表中）
  • expect：可选，单 sink 期望（仅 ratio/tol/min/max，互斥关系：ratio/tol 与 min/max 不可混用）
  • filter：可选，拦截条件文件路径；命中 true 时丢弃该 sink 并发送至 intercept

配置示例：

基础组

version = "2.0"
[sink_group]
name = "intercept"

[[sink_group.sinks]]
name = "intercept"
connect = "file_kv_sink"
params = { base = "./out", file = "intercept.dat" }

业务组（filter）

version = "2.0"

[sink_group]
name = "/sink/filter"
oml  = ["/oml/sh*"]

[[sink_group.sinks]]
name = "all"
connect = "file_kv_sink"
params = { base = "./out/sink", file = "all.dat" }

[[sink_group.sinks]]
name = "safe"
connect = "file_kv_sink"
filter = "./sink/business.d/filter.conf"   # 命中 -> 拦截，不写 safe
params = { base = "./out/sink", file = "safe.dat" }

说明

• 标识规则
  • 组名：sink_group.name（例如 /sink/example/simple）
  • sink 名：name（组内唯一；未显式提供时按索引回退为 [0]/[1]/…）
• 过滤语义（filter）
  • filter 是“拦截条件”：表达式求值为 true 时，该条数据不写入该 sink，而是转发到基础组 intercept（framework/intercept）
  • 每个 sink 可独立设置 filter；与 expect 相互独立

校验提示

• 分母决定：
  • basis = total_input：总输入
  • basis = group_input：该组各 sink 行数之和（或 stats 中该组输入）
  • basis = model：按模型粒度统计（目前以组内 sinks 行数之和替代）
• min_samples：当分母为 0 或小于该值时，组校验被忽略（打印提示，不 fail）
• 当 route 为非文件类写入 fmt 时，validate 会提示“fmt 由后端决定，已忽略”。

常见排错

• 连接器未找到：检查 connectors/sink.d 是否存在对应 id；wproj sinks list 可查看引用关系
• 覆盖参数不生效：检查 allow_override 白名单
• filter 未生效：
  • 路径解析相对当前工作目录（建议写相对 sink_root 的相对路径）
  • 日志中会打印“found path/not found filter …”
  • 表达式语法需通过 TCondParser；可先用简单表达式试验

Wpgen配置

wpgen 是数据生成工具，用于按照规则或样本生成测试数据。

基础配置

配置文件路径：conf/wpgen.toml

version = "1.0"

[generator]
mode = "sample"          # 生成模式：rule | sample
count = 1000             # 生成总条数（可选）
duration_secs = 60       # 生成持续时间（秒，可选，与 count 二选一）
speed = 1000             # 恒定速率（行/秒），0 为无限速
parallel = 1             # 并行度
rule_root = "./rules"    # 规则目录（mode=rule 时使用）
sample_pattern = "*.txt" # 样本文件匹配模式（mode=sample 时使用）

[output]
# 引用 connectors/sink.d 中的连接器 id
connect = "file_kv_sink"
name = "gen_out"
# 覆写连接器参数（仅 allow_override 白名单内的键）
params = { base = "./src_dat", file = "gen.dat" }

[logging]
level = "warn"
output = "file"
file_path = "./data/logs/"

动态速度模型

除了使用 speed 字段指定恒定速率外，还可以使用 speed_profile 配置动态速度变化模型。 当 speed_profile 存在时，speed 字段将被忽略。

恒定速率 (constant)

固定速率生成数据。

[generator.speed_profile]
type = "constant"
rate = 5000              # 每秒生成行数

正弦波动 (sinusoidal)

速率按正弦曲线周期性波动，模拟周期性负载变化。

[generator.speed_profile]
type = "sinusoidal"
base = 5000              # 基准速率（行/秒）
amplitude = 2000         # 波动幅度（行/秒）
period_secs = 60.0       # 周期长度（秒）

速率范围：[base - amplitude, base + amplitude]，即上例中为 3000-7000 行/秒。

阶梯变化 (stepped)

速率按预定义的阶梯序列变化，适合模拟分阶段负载测试。

[generator.speed_profile]
type = "stepped"
# 格式：[[持续时间(秒), 速率], ...]
steps = [
    [30.0, 1000],        # 前 30 秒：1000 行/秒
    [30.0, 5000],        # 接下来 30 秒：5000 行/秒
    [30.0, 2000]         # 最后 30 秒：2000 行/秒
]
loop_forever = true      # 是否循环执行（默认 false）

突发模式 (burst)

在基准速率上随机触发高速突发，模拟突发流量场景。

[generator.speed_profile]
type = "burst"
base = 1000              # 基准速率（行/秒）
burst_rate = 10000       # 突发时速率（行/秒）
burst_duration_ms = 500  # 突发持续时间（毫秒）
burst_probability = 0.05 # 每秒触发突发的概率（0.0-1.0）

渐进模式 (ramp)

速率从起始值线性变化到目标值，适合压力递增测试。

[generator.speed_profile]
type = "ramp"
start = 100              # 起始速率（行/秒）
end = 10000              # 目标速率（行/秒）
duration_secs = 300.0    # 变化持续时间（秒）

达到目标速率后将保持该速率。支持正向（递增）和反向（递减）。

随机波动 (random_walk)

速率在基准值附近随机波动，模拟不规则负载。

[generator.speed_profile]
type = "random_walk"
base = 5000              # 基准速率（行/秒）
variance = 0.3           # 波动范围（0.0-1.0），0.3 表示 ±30%

速率范围：[base * (1 - variance), base * (1 + variance)]

复合模式 (composite)

组合多个速度模型，支持多种组合方式。

[generator.speed_profile]
type = "composite"
combine_mode = "average" # 组合方式：average | max | min | sum

# 子模型列表
[[generator.speed_profile.profiles]]
type = "sinusoidal"
base = 5000
amplitude = 2000
period_secs = 60.0

[[generator.speed_profile.profiles]]
type = "random_walk"
base = 5000
variance = 0.1

组合方式说明：

• average：取所有子模型速率的平均值（默认）
• max：取所有子模型速率的最大值
• min：取所有子模型速率的最小值
• sum：累加所有子模型速率

配置示例

示例 1：简单恒定速率

version = "1.0"

[generator]
mode = "sample"
count = 10000
speed = 5000
parallel = 2

[output]
connect = "file_json_sink"
params = { base = "./data", file = "output.dat" }

[logging]
level = "info"
output = "file"
file_path = "./logs"

示例 2：渐进压力测试

version = "1.0"

[generator]
mode = "rule"
duration_secs = 600      # 运行 10 分钟
parallel = 4
rule_root = "./rules"

[generator.speed_profile]
type = "ramp"
start = 100
end = 20000
duration_secs = 300.0    # 5 分钟内从 100 提升到 20000

[output]
connect = "kafka_sink"
params = { topic = "test-topic" }

[logging]
level = "warn"
output = "file"
file_path = "./logs"

示例 3：模拟真实业务负载

version = "1.0"

[generator]
mode = "sample"
duration_secs = 3600     # 运行 1 小时
parallel = 8

[generator.speed_profile]
type = "composite"
combine_mode = "average"

# 基础周期性波动（模拟日间/夜间流量差异）
[[generator.speed_profile.profiles]]
type = "sinusoidal"
base = 10000
amplitude = 5000
period_secs = 300.0

# 叠加随机噪声
[[generator.speed_profile.profiles]]
type = "random_walk"
base = 10000
variance = 0.15

[output]
connect = "tcp_sink"
params = { host = "127.0.0.1", port = 9000 }

[logging]
level = "info"
output = "both"
file_path = "./logs"

运行规则

• wpgen 会在加载 conf/wpgen.toml 时，若检测到 [output].connect：

  • 从 ENGINE_CONF.sink_root 向上查找最近的 connectors/sink.d/ 目录
  • 读取目标连接器并与 params 合并（仅允许 allow_override 中的键）

• 当配置了 parallel > 1 时，速度模型会自动按并行度分配，确保总速率符合预期

• count 和 duration_secs 二选一：

  • 设置 count 时，生成指定条数后停止
  • 设置 duration_secs 时，运行指定秒数后停止
  • 两者都未设置时，将持续运行直到手动停止

KnowDB 配置

本指南描述知识库（KnowDB）的目录式配置与装载规范。

适用范围

• 初始化权威库（CSV → SQLite），用于 wparse/wproj 等工具在启动时装载

核心原则

• SQL 外置：每张表的 DDL/DML 均放在对应目录下的 .sql 文件中
• 安全：运行期只允许访问配置里声明过的表名；SQL 仅支持 {table} 占位符
• 默认可用：多数字段可省略，内置默认值与自动探测能满足常见场景

目录布局（推荐）

models/knowledge/
  knowdb.toml                     # 本配置
  example/
    create.sql
    insert.sql
    data.csv                     # 单一数据文件（表目录根）
  address/
    create.sql
    insert.sql
    data.csv

顶层配置（models/knowledge/knowdb.toml）

version = 2

[[tables]]
name = "example"
# dir 省略时等于 name；此示例即使用目录 models/knowledge/example
# data_file 省略时使用表目录下的 data.csv
columns.by_header = ["name", "pinying"]

# 如需更多表，追加 [[tables]] 段落

SQL 文件规范

• create.sql：建表语句，必须存在；可使用占位符 {table}；允许包含多条语句（如 CREATE INDEX）
• insert.sql：插入语句，必须存在；参数位置用 ?1..?N；允许 {table}
• clean.sql：可选；若不存在，装载前默认执行 DELETE FROM {table}

列映射（columns）

• 推荐 by_header=[..]，按 CSV 表头名映射到 insert.sql 中的列
• 若 has_header=false，必须提供 by_index=[..]
• 可选增强（实现层）：若未配置 columns，且 insert.sql 显式了列清单，可解析 insert 的列名作为 by_header

装载策略（默认可省略）

• 默认：transaction=true、batch_size=2000、on_error="fail"
• on_error:
  • fail：遇到坏行（缺列/解析失败）即失败回滚
  • skip：跳过坏行并计数告警

自动探测（当 data_file 未配置）

• 使用 {base_dir}/{tables.dir}/data.csv
• 不存在则报错

安全约束

• 运行时（facade/query_cipher/SQL 评估）仅允许使用 [[tables]].name 中声明的表名
• SQL 模板仅允许 {table} 占位符；禁止其它动态拼接

最小可运行示例

1. 目录

models/knowledge/knowdb.toml
models/knowledge/example/{create.sql, insert.sql, data.csv}

2. create.sql

CREATE TABLE IF NOT EXISTS {table} (
  id      INTEGER PRIMARY KEY,
  name    TEXT NOT NULL,
  pinying TEXT NOT NULL
);

3. insert.sql

INSERT INTO {table} (name, pinying) VALUES (?1, ?2);

4. data.csv

name,pinying
令狐冲,linghuchong
任盈盈,renyingying

5. knowdb.toml（最小化）

version = 2
base_dir = "./models/knowledge"
[[tables]]
name = "example"
dir  = "example"
columns.by_header = ["name", "pinying"]
[tables.expected_rows]
min = 1
max = 100

常见错误与排障

• 缺少 create.sql / insert.sql：启动时失败并指向缺失文件
• has_header=false 但未提供 by_index：装载报错
• expected_rows.min 未满足：数据不足，装载失败
• 数据源未找到：既未配置 data_file，也不存在默认路径 data.csv
• 运行期 SQL 访问未声明的表：安全校验失败

与应用的关系

• wparse/wproj 等会在启动处加载 knowdb：创建权威库并设置 Query Provider
• 曾用于隐私模块的 query_cipher(table)（加载单列表词表）在当前版本默认不启用；如需脱敏请在业务侧实现

内置 SQL 函数（UDF）

• 运行时注册：
  • 导入阶段（权威库写连接）与查询阶段（线程克隆的只读连接）均自动注册。
  • 可在 INSERT/SELECT/WHERE 中直接使用（DDL 不涉及）。
• 签名与语义：
  • ip4_int(text) -> integer：点分 IPv4 转 32 位整数；容忍空白/引号；非法返回 0。
  • ip4_between(ip_text, start_text, end_text) -> integer：是否在闭区间 [start,end] 内（1/0）。
  • cidr4_min(text) -> integer：CIDR 起始地址（含），如 10.0.0.0/8。
  • cidr4_max(text) -> integer：CIDR 结束地址（含）。
  • cidr4_contains(ip_text, cidr_text) -> integer：IP 是否落在 CIDR 段内（1/0）。
  • ip4_text(integer|string) -> text：32 位整数转点分 IPv4（便于调试/展示）。
  • trim_quotes(text) -> text：去除两端成对引号（’ 或 “），容忍前后空白；未成对则原样返回（去掉空白）。
• 导入示例（insert.sql）：

  INSERT INTO {table} (ip_start_int, ip_end_int, zone)
  VALUES (ip4_int(?1), ip4_int(?2), trim_quotes(?3));
  

• 查询示例（普通 SQL）：

  -- 区间命中（推荐整数比较写法，避免在 WHERE 中直接比较函数返回）
  SELECT zone FROM zone
  WHERE ip_start_int <= ip4_int(:ip)
    AND ip_end_int   >= ip4_int(:ip)
  LIMIT 1;
  
  -- CIDR 命中
  SELECT zone FROM zone
  WHERE cidr4_contains(:ip, :cidr) = 1;
  
  -- 调试回显
  SELECT ip4_text(ip_start_int) AS ip_start, ip4_text(ip_end_int) AS ip_end, zone
  FROM zone
  LIMIT 5;
  

• OML 中的 SQL 精确求值：
  • OML 的 select … from … where …; 语法对列段做了标识符白名单限制，不建议在列段直接写函数。
  • 推荐在上游产出数值型 IP（如 src_ip_int），在 OML 的 where 中用整数比较：

    from_zone: chars = sql(
      select zone from zone
      where ip_start_int <= read(src_ip_int)
        and ip_end_int   >= read(src_ip_int);
    )
    

• 注意事项：
  • 目前非法 IPv4/CIDR 输入返回 0（或匹配失败），为提高导入韧性；如需严格行为可定制。
  • SQLite 原生已提供 lower/upper/trim 等字符串函数，可与上述 UDF 组合使用。

日志配置

本文面向使用者与一线开发，给出在 Warp Parse 中开启/调整日志与进行常见问题定位的实操指南。

• 目标域（targets）见《开发者文档：Logging Targets And Levels》。
• 文件日志默认滚动：10MB/10 份，gzip 压缩。

快速上手

wparse / wprescue （conf/wparse.toml）

生产推荐（文件输出 + 低噪声）：

[log_conf]
output = "File"   # Console|File|Both
level  = "warn,ctrl=info，dfx=info"
[log_conf.file]
path = "./data/logs"   # 目录会自动创建；文件名按可执行名自动命名，如 wparse.log

本地联调（同时输出到控制台）：

[log_conf]
output = "Both"
level  = "debug"
[log_conf.file]
path = "./data/logs"

WPL 规则语言

WPL (Warp Processing Language) 是 Warp Parse 解析子系统（warp-parse）使用的规则语言，用于描述字段抽取、协议解析与简单判定逻辑。

📚 文档导航

按学习路径

🆕 新手入门
   ↓
01-quickstart.md ────→ 5分钟上手，复制即用
   ↓
07-complete-types-examplemd ──→ 🌟 完整功能演示（强烈推荐）
   ↓
02-core-concepts.md ──→ 理解设计理念和核心概念
   ↓
03-practical-guide.md → 按任务查找解决方案
   ↓
04-language-reference.md → 查阅类型和语法
   ↓
05-functions-reference.md → 查阅函数

按用户角色

按任务查找

📖 文档列表

⚡ 快速示例

Nginx 访问日志

package nginx {
  rule access_log {
    (
      ip:client_ip,
      2*_,
      time/clf<[,]>:time,
      http/request":request,
      digit:status,
      digit:bytes
    )
  }
}

JSON API 响应

package api {
  rule response {
    (json(
      chars@user,
      digit@code,
      chars@message
    ))
  }
}

华为防火墙日志（Base64）

package firewall {
  rule huawei_log {
    |decode/base64|
    (
      digit:id,
      time:timestamp,
      sn:serial,
      chars:type\:,
      opt(kvarr),
      kvarr
    )
  }
}

更多示例请查看：01-quickstart.md 和 03-practical-guide.md

🎯 完整类型系统示例

想快速了解 WPL 支持的所有数据类型？

👉 查看完整类型示例 - 一个示例展示 23 种主要数据类型

该文档包含：

• ✅ 完整可运行的输入数据 + WPL 规则 + 输出结果
• ✅ 23 种类型：基础、时间、网络、结构化、协议、编码
• ✅ 每种类型详解：语法、示例、使用场景
• ✅ 常见组合模式：复制即用的类型组合

适合：

• 🆕 新手快速了解 WPL 能力
• 📚 开发者作为类型速查手册
• 🔍 遇到陌生数据格式时快速查找对应类型

🎯 核心特性

• 声明式：描述“是什么“，而非“怎么做“
• 类型安全：自动验证和转换（IP、时间、JSON 等）
• 组合性：小规则组合成复杂规则
• 强大的管道：预处理（Base64/Hex 解码）+ 字段级验证
• 灵活的匹配：顺序、择一、可选、重复
• 子字段提取：JSON/KV 嵌套字段

💬 快速帮助

常见问题

Q: 从哪里开始学习？ A: 从 01-quickstart.md 开始，5 分钟即可上手。

Q: 如何解析我的日志格式？ A: 查看 03-practical-guide.md，找到相似的场景并调整。

Q: 某个类型/函数怎么用？ A: 查看 04-language-reference.md 或 05-functions-reference.md。

Q: 解析失败怎么调试？ A: 参考 01-quickstart.md § 调试技巧 或 03-practical-guide.md § 常见问题。

开始学习： 01-quickstart.md - 5分钟快速入门

WPL 完整类型系统示例

一个示例展示 WPL 支持的所有主要数据类型

本文档提供一个完整的、可运行的 WPL 规则示例，展示 23 种主要数据类型的使用方法。这是学习 WPL 类型系统的最佳参考。

📑 文档导航

📋 类型覆盖清单

本示例包含以下类型：

🚀 完整示例

输入数据

peek_symbol symbol true "hello world" 123 3.14 2026-01-19T12:34:56Z 2022-03-21T12:34:56+00:00 Mon, 07 Jul 2025 09:20:32 +0000 [06/Aug/2019:12:12:19 +0800] 1647849600 192.168.1.100 192.168.0.0/24 name=test {"strict":true} "GET /api/users HTTP/1.1" 200 "Mozilla/5.0" "POST" 8080 ABC123XYZ 0x1A2B YmFzZTY0ZGF0YQ==

WPL 规则

package wpl_example {
  rule full_types {
    (
      // 1. peek_symbol - 预读符号（不消费）
      peek_symbol(peek_symbol):peek_sym,

      // 2. symbol - 精确匹配符号
      symbol(symbol):sym,

      // 3. bool - 布尔值
      bool:bool_val,

      // 4. chars - 字符串（带引号）
      chars":quoted_str,

      // 5. digit - 整数
      digit:integer,

      // 6. float - 浮点数
      float:float_val,

      // 7. time_3339 - ISO 8601 / RFC3339
      time_3339:time_iso,

      // 8. time_3339 - RFC3339（带时区）
      time_3339:time_rfc3339,

      // 9. time_2822 - RFC2822（邮件时间格式）
      time_2822:time_rfc2822,

      // 10. time/clf - Common Log Format（Apache/Nginx）
      time/clf<[,]>:time_clf,

      // 11. time_timestamp - Unix 时间戳
      time_timestamp:timestamp,

      // 12. ip - IP 地址
      ip:ip_addr,

      // 13. ip_net - IP 网段（CIDR）
      ip_net:ip_network,

      // 14. kvarr - 键值对
      kvarr(chars@name):kv_data,

      // 15. json - JSON 对象
      json(bool@strict):json_data,

      // 16. http/request - HTTP 请求行
      http/request":http_req,

      // 17. http/status - HTTP 状态码
      http/status:http_status,

      // 18. http/agent - User-Agent
      http/agent":user_agent,

      // 19. http/method - HTTP 方法
      http/method":http_method,

      // 20. port - 端口号
      port:port_num,

      // 21. sn - 序列号
      sn:serial,

      // 22. hex - 十六进制
      hex:hex_data,

      // 23. base64 - Base64 编码
      base64:base64_data
    )
  }
}

输出结果

{
  "peek_sym": "peek_symbol",
  "sym": "symbol",
  "bool_val": true,
  "quoted_str": "hello world",
  "integer": 123,
  "float_val": 3.14,
  "time_iso": "2026-01-19 12:34:56",
  "time_rfc3339": "2022-03-21 12:34:56",
  "time_rfc2822": "2025-07-07 09:20:32",
  "time_clf": "2019-08-06 12:12:19",
  "timestamp": 1647849600,
  "ip_addr": "192.168.1.100",
  "ip_network": "192.168.0.0/24",
  "kv_data": {"name": "test"},
  "json_data": {"strict": true},
  "http_req": "GET /api/users HTTP/1.1",
  "http_status": 200,
  "user_agent": "Mozilla/5.0",
  "http_method": "POST",
  "port_num": 8080,
  "serial": "ABC123XYZ",
  "hex_data": "0x1A2B",
  "base64_data": "YmFzZTY0ZGF0YQ=="
}

📖 类型详解

基础类型

1. peek_symbol - 预读符号

peek_symbol(peek_symbol):peek_sym

• 作用：预读匹配但不消费输入
• 用途：用于向前查看而不影响后续解析

2. symbol - 精确匹配符号

symbol(symbol):sym

• 作用：精确匹配指定字符串
• 用途：匹配固定关键字、分隔符等

3. bool - 布尔值

bool:bool_val

• 匹配：true 或 false
• 输出：布尔类型

4. chars - 字符串

chars":quoted_str

• 格式：支持引号包裹 "hello" 或裸字符串 hello
• 用途：提取任意字符串

5. digit - 整数

digit:integer

• 匹配：整数，如 123、-456
• 输出：整数类型

6. float - 浮点数

float:float_val

• 匹配：浮点数，如 3.14、-0.5
• 输出：浮点数类型

时间类型

7-8. time_3339 - RFC3339/ISO 8601

time_3339:time_iso           // 2026-01-19T12:34:56Z
time_3339:time_rfc3339       // 2022-03-21T12:34:56+00:00

• 格式：ISO 8601 / RFC3339 标准
• 支持：带时区或不带时区

9. time_2822 - RFC2822（邮件时间）

time_2822:time_rfc2822

• 格式：Mon, 07 Jul 2025 09:20:32 +0000
• 用途：邮件头、RSS 等

10. time/clf - Common Log Format

time/clf<[,]>:time_clf

• 格式：[06/Aug/2019:12:12:19 +0800]
• 用途：Apache/Nginx 日志

11. time_timestamp - Unix 时间戳

time_timestamp:timestamp

• 格式：秒级时间戳，如 1647849600
• 输出：时间类型

网络类型

12. ip - IP 地址

ip:ip_addr

• 支持：IPv4（192.168.1.100）和 IPv6（::1）

13. ip_net - IP 网段

ip_net:ip_network

• 格式：CIDR 表示法，如 192.168.0.0/24

14. port - 端口号

port:port_num

• 范围：1-65535

结构化类型

15. kvarr - 键值对

kvarr(chars@name):kv_data

• 格式：key=value
• 支持：自动解析或指定键提取
• 示例：name=test → {name: "test"}

16. json - JSON 对象

json(bool@strict):json_data

• 支持：完整 JSON 解析
• 子字段：可提取嵌套字段
• 示例：{"strict":true} → {strict: true}

协议类型

17. http/request - HTTP 请求行

http/request":http_req

• 格式："GET /api/users HTTP/1.1"
• 提取：方法 + 路径 + 协议版本

18. http/status - HTTP 状态码

http/status:http_status

• 格式：200、404、500 等

19. http/agent - User-Agent

http/agent":user_agent

• 格式："Mozilla/5.0..."
• 用途：浏览器标识

20. http/method - HTTP 方法

http/method":http_method

• 支持：GET、POST、PUT、DELETE 等

编码类型

21. hex - 十六进制

hex:hex_data

• 格式：0x1A2B 或 1A2B
• 输出：十六进制字符串

22. base64 - Base64 编码

base64:base64_data

• 格式：YmFzZTY0ZGF0YQ==
• 输出：Base64 编码字符串

特殊类型

23. sn - 序列号

sn:serial

• 格式：字母数字组合，如 ABC123XYZ
• 用途：设备序列号、订单号等

💡 使用建议

学习路径

1. 第一步：先理解基础类型（digit、chars、ip）
2. 第二步：掌握时间类型（根据日志格式选择）
3. 第三步：学习结构化类型（json、kvarr）
4. 第四步：了解协议类型（http/*）

实战建议

• 快速查阅：遇到不认识的数据格式，先在本页面搜索
• 复制即用：直接复制对应类型的语法到你的规则中
• 类型组合：多种类型可以自由组合使用

常见组合

// Web 日志
(ip, time/clf<[,]>, http/request", http/status, digit)

// API 日志
(time_3339, chars, json(chars@user, digit@code))

// 防火墙日志
(ip, port, time, kvarr)

🔗 相关文档

• 快速入门：01-quickstart.md - 5 分钟上手
• 核心概念：02-core-concepts.md - 深入理解类型系统
• 实战指南：03-practical-guide.md - 按任务查找解决方案
• 语言参考：04-language-reference.md - 完整类型列表
• 函数参考：05-functions-reference.md - 所有函数详解

📌 快速导航

提示：将本页面加入书签，作为 WPL 类型系统的速查手册！

WPL 快速入门

5 分钟上手 WPL，立即解析你的日志数据。

📚 快速导航

什么是 WPL

WPL (Warp Processing Language) 是一种声明式规则语言，用于描述如何从日志、消息等文本数据中提取字段和解析结构。

核心特点

• 声明式：描述“数据是什么“，而非“如何提取“
• 类型安全：自动验证和转换（IP、时间、JSON 等 37 种类型）
• 强大灵活：支持 JSON/KV 嵌套提取、Base64 解码、字段验证等
• 易于学习：5 分钟即可上手基础用法

适用场景

• 解析 Web 服务器日志（Nginx、Apache）
• 提取 JSON/KV 结构化数据
• 处理编码数据（Base64、Hex）
• 防火墙、安全设备日志解析
• 自定义日志格式解析

📚 完整类型系统

WPL 支持 23 种主要数据类型，涵盖基础类型、时间、网络、结构化数据、协议和编码等。

👉 查看完整示例： 07-complete-types-example.md

该文档包含：

• ✅ 所有 23 种类型的完整示例代码
• ✅ 可运行的输入数据和 WPL 规则
• ✅ 每种类型的详细说明和使用建议
• ✅ 常见类型组合模式

快速预览主要类型：

• 基础：digit、float、chars、bool
• 时间：time/clf、time_3339、time_2822、time_timestamp
• 网络：ip、ip_net、port、domain、url
• 结构化：json、kvarr、array
• 协议：http/request、http/status、http/method、http/agent
• 编码：hex、base64

最简示例：Nginx 日志

输入数据：

192.168.1.2 - - [06/Aug/2019:12:12:19 +0800] "GET /index.html HTTP/1.1" 200 1024

WPL 规则：

package nginx {
  rule access_log {
    (
      ip:client_ip,
      2*_,
      time/clf<[,]>:time,
      http/request":request,
      digit:status,
      digit:bytes
    )
  }
}

输出结果：

client_ip: 192.168.1.2
time: 2019-08-06 12:12:19
request: GET /index.html HTTP/1.1
status: 200
bytes: 1024

说明：

• ip:client_ip - 提取 IP 地址，命名为 client_ip
• 2*_ - 忽略 2 个字段（两个 -）
• time/clf<[,]> - 提取方括号包裹的 CLF 时间
• http/request" - 提取引号包裹的 HTTP 请求
• digit - 提取数字

3 个最常用场景

场景 1：空格分隔的日志

输入：

200 192.168.1.1 2023-01-01T12:00:00 login_success

WPL：

package demo {
  rule simple_log {
    (digit:code, ip:client, time:ts, chars:action)
  }
}

输出：

code: 200
client: 192.168.1.1
ts: 2023-01-01 12:00:00
action: login_success

场景 2：JSON 数据

输入：

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

WPL：

package api {
  rule json_response {
    (json(
      chars@user,
      digit@code,
      chars@message
    ))
  }
}

输出：

user: admin
code: 200
message: success

场景 3：KV 键值对

输入：

host=server1;port=8080;user=admin;status=online

WPL：

package config {
  rule kv_log {
    (kvarr)
  }
}

输出：

host: server1
port: 8080
user: admin
status: online

基本语法速览

结构

package 包名 {
  rule 规则名 {
    (字段列表)
  }
}

常用字段类型

字段命名

type:name              # 命名字段
digit:status           # status = 数字
ip:client_ip           # client_ip = IP地址

忽略字段

_                      # 忽略 1 个字段
2*_                    # 忽略 2 个字段
5*_                    # 忽略 5 个字段

格式控制

<[,]>                  # 方括号包裹：[content]
<{,}>                  # 花括号包裹：{content}
"                      # 引号包裹："content"
^N                     # 固定 N 个字符

重复模式

kvarr                  # 自动解析所有KV
3*ip                   # 重复 3 次
12*digit               # 重复 12 次

子字段提取

# JSON 子字段
json(chars@name, digit@age)

# KV 子字段
kvarr(chars@host, digit@port)

# 嵌套字段
json(chars@user/name, digit@user/age)

常见模式速查

解析带引号的字段

chars":url             # "http://example.com"
http/agent":ua         # "Mozilla/5.0..."

解析带特殊分隔符的数据

# 逗号分隔
(digit, ip, chars)\,

# 分号分隔
(digit, ip, chars)\;

# 字段级分隔符（优先级更高）
digit\,, ip\;, chars\s

可选字段

opt(chars)             # 可选字段
(digit, opt(chars), time)

Base64 解码

|decode/base64|
(json(chars@data))

快速调试技巧

1. 从简单开始

# 第 1 步：最简单
(digit)

# 第 2 步：添加字段
(digit, ip)

# 第 3 步：添加命名
(digit:status, ip:client)

# 第 4 步：添加复杂类型
(digit:status, ip:client, json(chars@name))

2. 使用 opt() 定位问题

# 如果某个字段导致失败，用 opt 包裹
(digit, opt(ip), time, chars)
# 如果 ip 解析失败，其他字段仍然可以解析

3. 检查分隔符

打印原始数据，确认字段间的分隔符：

数据：200,192.168.1.1,admin
分隔符：逗号
规则：(digit, ip, chars)\,

下一步

理解概念

→ 02-core-concepts.md - 理解 WPL 的设计理念

你将学到：

• 为什么 WPL 这样设计？
• 类型系统的作用
• 匹配语义（seq/alt/opt/some_of）
• 管道系统原理
• 分隔符优先级

解决实际问题

→ 03-practical-guide.md - 按任务查找解决方案

你将学到：

• 解析 Web 服务器日志（Nginx/Apache）
• 解析 JSON 数据（嵌套、反转义）
• 解析 KV 键值对（多种分隔符）
• 处理编码数据（Base64/Hex）
• 字段验证与过滤
• 复杂场景（重复模式、可选字段）

查阅参考

→ 04-language-reference.md - 完整类型和语法参考 → 05-functions-reference.md - 所有函数参考

实战练习

练习 1：解析自定义日志

数据：

[2023-01-01 12:00:00] INFO 192.168.1.1 user=admin action=login

提示：

• 时间在方括号中
• INFO 可以忽略
• 后面是 IP 和 KV

package practice {
  rule custom_log {
    (
      time<[,]>:timestamp,
      _,
      ip:client,
      kvarr
    )
  }
}

练习 2：解析嵌套 JSON

数据：

{"user":{"name":"Alice","age":25},"status":"active"}

提示：

• 使用 @path/to/field 提取嵌套字段

package practice {
  rule nested_json {
    (json(
      chars@user/name,
      digit@user/age,
      chars@status
    ))
  }
}

练习 3：解析 Base64 编码日志

数据（Base64）：

eyJ1c2VyIjoiYWRtaW4iLCJjb2RlIjoyMDB9

解码后：

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

提示：

• 使用 |decode/base64| 预处理

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

相关资源

• 核心概念：02-core-concepts.md
• 实战指南：03-practical-guide.md
• 语言参考：04-language-reference.md
• 函数参考：05-functions-reference.md
• 语法规范：06-grammar-reference.md

WPL 核心概念

本文档帮助你理解 WPL 的设计理念和核心概念，建立正确的思维模型。

📚 文档导航

快速导航

WPL 设计理念

为什么需要 WPL？

问题： 如何从非结构化文本中提取结构化数据？

输入（文本）：192.168.1.1 - - [06/Aug/2019:12:12:19 +0800] "GET /index.html" 200
输出（结构）：
  client_ip: 192.168.1.1
  time: 2019-08-06 12:12:19
  request: GET /index.html
  status: 200

传统方法的问题：

• 正则表达式：难写、难读、难维护
• 手写解析器：代码冗长、容易出错
• 固定格式解析：不够灵活

WPL 的解决方案：

• 声明式：描述“是什么“，而非“怎么做“
• 类型安全：自动验证和转换
• 组合性：小的规则组合成复杂规则

核心思想：规则 = 模式匹配 + 字段提取

package demo {
  rule example {
    (ip:client, digit:status, time:ts)
  }
}

这个规则表达：

1. 模式：数据格式是“IP 数字 时间“
2. 提取：提取 3 个字段，分别命名为 client、status、ts
3. 验证：自动验证 IP 格式、数字格式、时间格式
4. 转换：自动转换为对应类型

类型系统

类型的作用

类型在 WPL 中有三个作用：

1. 验证：确保数据符合预期格式
2. 转换：自动转换为标准格式
3. 语义：表达数据的含义

示例：

# 输入：06/Aug/2019:12:12:19 +0800
time/clf:access_time

# 类型 time/clf 做了 3 件事：
# 1. 验证：是否符合 CLF 时间格式
# 2. 转换：转换为标准时间格式 2019-08-06 12:12:19
# 3. 语义：表达"这是访问时间"

类型的层次

基础类型 ────→ 结构化类型 ────→ 协议类型
   ↓              ↓               ↓
 digit          json          http/request
 chars           kvarr        http/status
  ip           array          time/clf
 time           obj

基础类型：原子数据

• digit - 整数
• chars - 字符串
• ip - IP 地址
• time - 时间

结构化类型：复合数据

• json - JSON 对象（包含多个字段）
• kvarr - 键值对
• array - 数组

协议类型：领域特定格式

• http/request - HTTP 请求行
• http/status - HTTP 状态码
• time/clf - CLF 时间格式

类型组合示例

# 简单组合
(digit, ip, time)

# 嵌套组合
(digit, json(chars@name, digit@age), time)

# 数组组合
array/digit              # 数字数组
array/array/chars        # 二维字符串数组

匹配语义

WPL 提供 4 种匹配语义，满足不同场景需求。

seq（顺序匹配）- 默认

语义：按顺序依次匹配每个字段

# 显式写法
seq(ip, digit, time)

# 隐式写法（默认）
(ip, digit, time)

匹配过程：

输入：192.168.1.1 200 2023-01-01
      ↓           ↓   ↓
     ip         digit time

何时使用： 字段顺序固定（90% 的场景）

alt（择一匹配）

语义：尝试多种类型，匹配其中一个

alt(ip, digit)

匹配过程：

输入：192.168.1.1
尝试：ip ✓ → 成功，返回 ip
      digit ✗ → 不尝试

输入：12345
尝试：ip ✗ → 失败
      digit ✓ → 成功，返回 digit

何时使用： 同一位置可能是不同类型

示例场景：

# 日志中 user_id 可能是数字或字符串
(time, alt(digit, chars):user_id, chars:action)

opt（可选匹配）

语义：字段可选，失败不报错

opt(chars)

匹配过程：

输入：有内容 → 尝试匹配，成功则提取
输入：无内容 → 跳过，继续下一个字段

何时使用： 某些字段可能不存在

示例场景：

# HTTP 日志中 referer 可能为空
(ip, time, http/request, digit, opt(chars):referer)

some_of（尽可能多）

语义：循环匹配，尽可能多地消费字段

some_of(kvarr, ip, digit)

匹配过程：

输入：k1=v1 192.168.1.1 200 k2=v2 300

循环 1：尝试 kvarr ✓ → 提取 k1=v1
循环 2：尝试 kvarr ✗, 尝试 ip ✓ → 提取 192.168.1.1
循环 3：尝试 kvarr ✗, 尝试 ip ✗, 尝试 digit ✓ → 提取 200
循环 4：尝试 kvarr ✓ → 提取 k2=v2
循环 5：尝试 kvarr ✗, 尝试 ip ✗, 尝试 digit ✓ → 提取 300
循环 6：全部失败 → 停止

何时使用： 不确定数量和顺序的混合字段

匹配语义对比

管道系统

WPL 的管道系统分为两层：预处理管道（整行级）和字段级管道（字段级）。

预处理管道（整行级）

语法：

|step1|step2|
(字段列表)

作用域： 整行原始输入

执行时机： 在字段解析之前

常用场景：

# Base64 解码
|decode/base64|
(json)

# 多步处理
|decode/base64|unquote/unescape|
(json(chars@path))

为什么需要预处理管道？

• 某些日志整行都是 Base64 编码（如华为防火墙）
• 需要先解码，才能进行字段解析
• 预处理一次，所有字段都受益

字段级管道（字段级）

语法：

(fields) |function1| |function2|

作用域： 解析后的字段集合

执行时机： 在字段解析之后

常用场景：

# 验证字段
(json |f_has(status) |f_digit_in(status, [200, 201]))

# 转换字段
(json(chars@message) |take(message) |json_unescape())

为什么需要字段级管道？

• 需要验证某个字段是否存在
• 需要验证字段值是否符合条件
• 需要对特定字段进行转换

两种管道的区别

示例对比：

# 预处理管道：整行 Base64 解码
|decode/base64|
(json(chars@user))

# 字段级管道：单字段 Base64 解码
(json(chars@payload) |take(payload) |base64_decode())

子字段与嵌套

为什么需要子字段？

问题： JSON/KV 等结构化数据包含多个字段，如何提取？

{"user":"admin","code":200,"data":{"result":"ok"}}

解决方案： 使用子字段语法

json(
  chars@user,              # 提取 user 字段
  digit@code,              # 提取 code 字段
  chars@data/result        # 提取 data.result 字段
)

JSON 子字段

基本语法：

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

示例：

# 提取指定字段
json(chars@name, digit@age)

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

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

输入：

{"user":{"name":"Alice","age":25},"status":"active"}

输出：

user/name: Alice
user/age: 25
status: active

KV 子字段

基本语法：

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

示例：

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

输入：

hostname=server1 port=3306 user=root

输出：

hostname: server1
port: 3306
user: root

数组

基本语法：

array[/subtype]

示例：

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

分隔符优先级

为什么需要优先级？

问题： 不同来源的分隔符可能冲突

# 字段级分隔符
digit\,

# 组级分隔符
(digit, ip)\;

# 上游分隔符（来自 json/kvarr 等）

解决方案： 定义优先级规则

优先级规则

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

示例：

# 字段级覆盖组级
(digit\;, ip, chars)\,
# digit 用分号，ip 和 chars 用逗号

# 组级覆盖上游
json(...) (digit, ip)\;
# 即使 json 内部默认空格，组级分号生效

分隔符类型

实际应用

场景 1：不同字段不同分隔符

(digit\;, ip\,, chars\s)
# digit 用分号，ip 用逗号，chars 用空格

场景 2：组级统一分隔符

(digit, ip, time)\,
# 所有字段都用逗号

场景 3：最后一个字段读到行尾

(digit, ip, chars\0)
# chars 读取所有剩余内容

设计原则总结

1. 声明式优于命令式

# WPL（声明式）
(ip, digit, time)

# 命令式伪代码
ip = parse_ip(input)
digit = parse_digit(input)
time = parse_time(input)

2. 类型安全优于字符串匹配

# 带类型验证
ip:client_ip              # 自动验证 IP 格式

# 纯字符串
chars:client_ip           # 不验证格式

3. 组合优于重复

# 可组合
rule base_fields { (ip, time) }
rule extended { (ip, time, json) }   # 复用基础部分

# 不可组合
rule log1 { (ip, time, chars) }
rule log2 { (ip, time, json) }       # 重复 ip, time

4. 明确优于隐含

# 明确指定
time/clf<[,]>:access_time

# 隐含（可能失败）
time:access_time

常见误解

误解 1：WPL 是正则表达式

错误认知： WPL 和正则表达式类似

正确理解： WPL 是类型化的模式匹配语言

• 正则：字符级匹配
• WPL：类型级匹配 + 验证 + 转换

误解 2：所有字段必须连续

错误认知： 字段之间不能有空隙

正确理解： 使用 _ 跳过不需要的字段

(ip, 3*_, time)           # 跳过 3 个字段

误解 3：只能解析固定格式

错误认知： WPL 只能解析固定格式的数据

正确理解： 支持可选、重复、择一等灵活模式

opt(chars)                # 可选
kvarr                     # 自动解析KV
alt(ip, digit)            # 择一

下一步

实战应用

→ 03-practical-guide.md - 按任务查找解决方案

你将学到：

• 解析各种 Web 服务器日志
• 处理 JSON 和 KV 数据
• 使用预处理管道
• 字段验证与过滤
• 复杂场景处理

深入参考

→ 04-language-reference.md - 完整类型和语法 → 05-functions-reference.md - 所有函数详解

相关资源

• 快速入门：01-quickstart.md
• 实战指南：03-practical-guide.md
• 语言参考：04-language-reference.md

WPL 实战指南

本文档采用任务导向的方式，帮助你快速找到解决方案。

📚 任务导航

📋 快速参考

常用模式速查

常用类型速查

📖 如何使用本指南

根据你的任务，找到对应章节，复制规则并根据实际情况调整。

1. 解析 Web 服务器日志

任务 1.1：解析 Nginx/Apache 访问日志

场景： 标准 Nginx/Apache 访问日志

输入：

192.168.1.2 - - [06/Aug/2019:12:12:19 +0800] "GET /index.html HTTP/1.1" 200 1024 "http://example.com/" "Mozilla/5.0"

WPL 规则：

package nginx {
  rule access_log {
    (
      ip:client_ip,
      2*_,
      time/clf<[,]>:time,
      http/request":request,
      http/status:status,
      digit:bytes,
      chars":referer,
      http/agent":user_agent
    )
  }
}

输出：

client_ip: 192.168.1.2
time: 2019-08-06 12:12:19
request: GET /index.html HTTP/1.1
status: 200
bytes: 1024
referer: http://example.com/
user_agent: Mozilla/5.0

要点：

• 2*_ 忽略两个 - 字段
• time/clf<[,]> 解析方括号包裹的 CLF 时间
• http/request" 自动解析引号包裹的 HTTP 请求并提取方法、路径、协议
• chars" 提取引号包裹的字符串

任务 1.2：解析带变量的 Nginx 日志

场景： 自定义 Nginx log_format

输入：

2023-01-01T12:00:00+08:00|INFO|192.168.1.1|GET|/api/users|200|0.123

WPL 规则：

package nginx {
  rule custom_log {
    (
      time_3339:timestamp,
      chars:level,
      ip:client_ip,
      http/method:method,
      chars:path,
      http/status:status,
      float:response_time
    )\|
  }
}

输出：

timestamp: 2023-01-01 12:00:00
level: INFO
client_ip: 192.168.1.1
method: GET
path: /api/users
status: 200
response_time: 0.123

要点：

• )\| 指定组级分隔符为管道符 |
• time_3339 解析 RFC 3339 时间格式
• http/method 专门解析 HTTP 方法
• float 解析浮点数（响应时间）

任务 1.3：解析带 referer 为空的日志

场景： referer 可能为 - 或空

输入：

192.168.1.1 [06/Aug/2019:12:12:19 +0800] "GET /index.html" 200 1024 "-"

WPL 规则：

package nginx {
  rule access_log_optional {
    (
      ip:client_ip,
      time/clf<[,]>:time,
      http/request":request,
      http/status:status,
      digit:bytes,
      opt(chars"):referer
    )
  }
}

输出：

client_ip: 192.168.1.1
time: 2019-08-06 12:12:19
request: GET /index.html
status: 200
bytes: 1024
referer: -

要点：

• opt(chars") 将 referer 标记为可选字段
• 即使 referer 解析失败，其他字段仍能正常提取

2. 解析 JSON 数据

任务 2.1：提取 JSON 字段

场景： API 响应日志

输入：

{"user":"admin","code":200,"message":"success","timestamp":"2023-01-01T12:00:00"}

WPL 规则：

package api {
  rule response {
    (json(
      chars@user,
      digit@code,
      chars@message,
      time_3339@timestamp
    ))
  }
}

输出：

user: admin
code: 200
message: success
timestamp: 2023-01-01 12:00:00

要点：

• json(type@key) 语法提取指定键的值
• 类型自动验证和转换（time_3339 转换时间格式）

任务 2.2：处理嵌套 JSON

场景： 嵌套的 JSON 结构

输入：

{"user":{"name":"Alice","age":25,"profile":{"city":"Beijing"}},"status":"active"}

WPL 规则：

package api {
  rule nested_json {
    (json(
      chars@user/name,
      digit@user/age,
      chars@user/profile/city,
      chars@status
    ))
  }
}

输出：

user/name: Alice
user/age: 25
user/profile/city: Beijing
status: active

要点：

• 使用 / 分隔嵌套路径：@user/name, @user/profile/city
• 路径层级无限制

任务 2.3：JSON 反转义

场景： JSON 字符串包含转义字符

输入：

{"path":"c:\\users\\admin\\file.txt","message":"line1\nline2"}

WPL 规则：

package api {
  rule json_unescape {
    (json(chars@path, chars@message) |json_unescape())
  }
}

输出：

path: c:\users\admin\file.txt
message: line1
line2

要点：

• |json_unescape() 将 \\n 转换为实际换行符
• \\\\ 转换为 \
• \\\" 转换为 "

任务 2.4：可选 JSON 字段

场景： 某些字段可能不存在

输入：

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

WPL 规则：

package api {
  rule optional_fields {
    (json(
      chars@user,
      digit@code,
      opt(chars)@message,
      opt(chars)@data
    ))
  }
}

输出：

user: admin
code: 200

要点：

• opt(type)@key 标记字段为可选
• 不存在的字段不会导致解析失败

3. 解析 KV 键值对

任务 3.1：基础 KV 解析（分号分隔）

场景： 简单的 KV 格式日志

输入：

host=server1;port=8080;user=admin;status=online

WPL 规则：

package config {
  rule kv_semicolon {
    (kvarr)
  }
}

输出：

host: server1
port: 8080
user: admin
status: online

要点：

• kvarr 自动解析所有KV对
• 自动识别分隔符

任务 3.2：固定数量 KV（逗号分隔）

场景： 华为防火墙日志（12 个固定 KV）

输入：

k1=v1,k2=v2,k3=v3,k4=v4,k5=v5,k6=v6,k7=v7,k8=v8,k9=v9,k10=v10,k11=v11,k12=v12

WPL 规则：

package firewall {
  rule fixed_kv {
    (kvarr)
  }
}

输出：

k1: v1
k2: v2
...
k12: v12

要点：

• kvarr 自动解析所有KV对
• 不需要指定数量

任务 3.3：提取指定 KV 字段

场景： 只提取需要的字段

输入：

hostname=server1 port=3306 user=root db=test timeout=30

WPL 规则：

package database {
  rule extract_kv {
    (kvarr(
      chars@hostname,
      digit@port,
      chars@user,
      opt(chars)@db
    ))
  }
}

输出：

hostname: server1
port: 3306
user: root
db: test

要点：

• kvarr(type@key) 提取指定键的值
• 未列出的键（如 timeout）被忽略
• opt(type)@key 标记可选字段

任务 3.4：混合 KV 格式

场景： 可选 KV + 多个 KV

输入：

1234,2023-01-01T12:00:00,ABC123,LOGIN:host=server;user=admin,port=8080,action=success

WPL 规则：

package firewall {
  rule mixed_kv {
    (
      digit:id,
      time:timestamp,
      sn:serial,
      chars:type\:,
      opt(kvarr),
      kvarr
    )
  }
}

输出：

id: 1234
timestamp: 2023-01-01 12:00:00
serial: ABC123
type: LOGIN
host: server
user: admin
port: 8080
action: success

要点：

• chars:type\: 冒号作为分隔符
• opt(kvarr) 可选的KV
• kvarr 自动解析KV

4. 处理编码数据

任务 4.1：Base64 解码

场景： 华为防火墙日志（整行 Base64 编码）

输入（Base64）：

MTIzNCwyMDIzLTAxLTAxVDEyOjAwOjAwLEFCQzEyMyxMT0dJTjpob3N0PXNlcnZlcjt1c2VyPWFkbWluLHBvcnQ9ODA4MCxhY3Rpb249c3VjY2Vzcw==

解码后：

1234,2023-01-01T12:00:00,ABC123,LOGIN:host=server;user=admin,port=8080,action=success

WPL 规则：

package firewall {
  rule huawei_log {
    |decode/base64|
    (
      digit:id,
      time:timestamp,
      sn:serial,
      chars:type\:,
      opt(kvarr),
      kvarr
    )
  }
}

输出：

id: 1234
timestamp: 2023-01-01 12:00:00
serial: ABC123
type: LOGIN
host: server
user: admin
port: 8080
action: success

要点：

• |decode/base64| 预处理管道，对整行进行 Base64 解码
• 解码后再进行字段解析

任务 4.2：十六进制解码

场景： 二进制数据的十六进制表示

输入：

48656c6c6f20576f726c64

WPL 规则：

package binary {
  rule hex_decode {
    |decode/hex|
    (chars:data)
  }
}

输出：

data: Hello World

要点：

• |decode/hex| 将十六进制字符串解码为原始文本

任务 4.3：组合多步预处理

场景： Base64 + JSON 反转义

输入（Base64）：

eyJwYXRoIjoiY1xcXFx1c2Vyc1xcXFxmaWxlIiwidGV4dCI6ImxpbmUxXG5saW5lMiJ9

解码后：

{"path":"c:\\users\\file","text":"line1\nline2"}

WPL 规则：

package security {
  rule multi_step {
    |decode/base64|unquote/unescape|
    (json(chars@path, chars@text))
  }
}

输出：

path: c:\users\file
text: line1
line2

要点：

• 可以链接多个预处理步骤
• 执行顺序：从左到右

5. 字段验证与过滤

任务 5.1：检查字段存在

场景： 确保必需字段存在

输入：

{"status":"ok","message":"success","data":null}

WPL 规则：

package api {
  rule check_required {
    (json |f_has(status) |f_has(message))
  }
}

输出：

status: ok
message: success
data: null

要点：

• |f_has(field) 检查字段是否存在
• 字段不存在时解析失败

任务 5.2：验证状态码

场景： 只处理成功的响应（200/201/204）

输入：

{"code":200,"status":"success","data":"result"}

WPL 规则：

package api {
  rule validate_success {
    (json |f_digit_in(code, [200, 201, 204]))
  }
}

输出：

code: 200
status: success
data: result

要点：

• |f_digit_in(field, [list]) 验证数字字段值在列表中
• 不在列表中时解析失败

任务 5.3：过滤特定方法

场景： 只处理 GET/POST 请求

输入：

{"method":"GET","path":"/api/users","status":200}

WPL 规则：

package api {
  rule filter_methods {
    (json |f_chars_in(method, [GET, POST]))
  }
}

输出：

method: GET
path: /api/users
status: 200

要点：

• |f_chars_in(field, [list]) 验证字符串字段值在列表中

任务 5.4：链式验证

场景： 多个条件组合

输入：

{"user":"admin","age":25,"status":"active"}

WPL 规则：

package api {
  rule chain_validation {
    (json(chars@user, digit@age, chars@status)
      |take(user)
      |chars_has(admin)
      |take(age)
      |digit_in([18, 25, 30])
      |take(status)
      |chars_has(active)
    )
  }
}

输出：

user: admin
age: 25
status: active

要点：

• take(field) 选择字段为活跃字段
• 然后对活跃字段进行验证
• 可以链式调用多个验证

6. 复杂场景

任务 6.1：可变数量字段（some_of）

场景： 字段数量和顺序不固定

输入：

192.168.1.1 k1=v1 200 k2=v2 300 k3=v3

WPL 规则：

package mixed {
  rule variable_fields {
    some_of(ip, kv, digit)
  }
}

输出：

ip: 192.168.1.1
k1: v1
digit: 200
k2: v2
digit: 300
k3: v3

要点：

• some_of(...) 循环匹配所有可能的类型
• 尽可能多地消费字段

任务 6.2：择一匹配（alt）

场景： 某个位置可能是不同类型

输入：

user_id:12345 action:login
user_id:admin action:logout

WPL 规则：

package auth {
  rule flexible_user_id {
    (
      chars:key1,
      alt(digit, chars):user_id,
      chars:key2,
      chars:action
    )
  }
}

输出（输入 1）：

key1: user_id
user_id: 12345
key2: action
action: login

输出（输入 2）：

key1: user_id
user_id: admin
key2: action
action: logout

要点：

• alt(type1, type2) 尝试多种类型
• 匹配第一个成功的类型

任务 6.3：读到行尾

场景： 最后一个字段包含所有剩余内容

输入：

2023-01-01 ERROR This is a very long error message with many details

WPL 规则：

package log {
  rule read_to_end {
    (
      time:timestamp,
      chars:level,
      chars\0:message
    )
  }
}

输出：

timestamp: 2023-01-01
level: ERROR
message: This is a very long error message with many details

要点：

• \0 表示读到行尾
• 常用于日志的 message 字段

7. 常见问题

Q1: 如何处理可变数量的字段？

答案： 使用 N*type 或 some_of

# KV 自动解析
kvarr

# 混合类型
some_of(ip, digit, kvarr)

Q2: 如何忽略某些字段？

答案： 使用 _ 或 N*_

# 忽略 1 个字段
(ip, _, time)

# 忽略 3 个字段
(ip, 3*_, time)

Q3: 分隔符不一致怎么办？

答案： 使用字段级分隔符优先级

# 不同字段不同分隔符
(digit\;, ip\,, chars\s)

# 或使用组级分隔符
(digit, ip, chars)\,

Q4: JSON 字段可能不存在怎么办？

答案： 使用 opt(type)@key

json(
  chars@user,
  opt(chars)@email,
  opt(digit)@age
)

Q5: 如何提取嵌套 JSON 字段？

答案： 使用路径语法 @path/to/field

json(
  chars@user/name,
  digit@user/age,
  chars@data/result
)

Q6: 预处理管道失败怎么办？

答案： 检查以下几点

1. 管道名称是否正确
2. 是否以 | 结尾
3. 输入数据格式是否正确

# 正确
|decode/base64|

# 错误：缺少结尾 |
|decode/base64

Q7: 如何调试解析失败的规则？

步骤：

1. 简化规则，从最简单的字段开始
2. 使用 opt() 标记可疑字段
3. 检查分隔符是否正确
4. 检查格式控制符（引号、括号等）

# 原规则（失败）
(digit, time, chars, json)

# 调试规则
(digit, opt(time), opt(chars), opt(json))
# 逐步确定哪个字段导致失败

下一步

查阅参考

→ 04-language-reference.md - 完整类型和语法 → 05-functions-reference.md - 所有函数详解

深入理解

→ 02-core-concepts.md - 理解 WPL 设计理念

相关资源

• 快速入门：01-quickstart.md
• 核心概念：02-core-concepts.md
• 语言参考：04-language-reference.md
• 函数参考：05-functions-reference.md

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)

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)             # 单个可选
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

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

WPL 语法参考（EBNF）

本文档提供 WPL 的形式化语法定义，适合：

• 编译器/解析器开发者
• 精确理解语法规则
• 工具集成开发

普通用户请参考：

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

📑 文档导航

完整 EBNF 定义

权威实现以 crates/wp-lang 解析器为准；此处与源代码保持同步。

; WPL 语法（EBNF）
; 基于 crates/wp-lang 下解析实现（winnow）整理
; 说明：本文件给出语法产生式与必要的词法约定。除显式标注外，token 之间允许可选空白 `ws`。

wpl_document     = { package_decl } ;

package_decl     = [ annotation ] "package" ws? ident ws? "{" ws? rule_decl+ ws? "}" ;

rule_decl        = [ annotation ] "rule" ws? rule_name ws? "{" ws? statement ws? "}" ;

statement        = plg_pipe_block | express ;

plg_pipe_block   = ["@"]? "plg_pipe" ws? "(" ws? "id" ws? ":" ws? key ws? ")" ws? "{" ws? express ws? "}" ;

express          = [ preproc ] group { ws? "," ws? group } ;

preproc          = "|" ws? preproc_step { ws? "|" ws? preproc_step } ws? "|" ;   ; 至少一个步骤，且以 '|' 结尾
preproc_step     = builtin_preproc | plg_pipe_step ;
builtin_preproc  = ns "/" name ;
plg_pipe_step    = "plg_pipe" ws? "/" ws? key ;                   ; 通过注册表查找自定义扩展
ns               = "decode" | "unquote" ;                        ; 命名空间白名单
name             = ("base64" | "hex") | "unescape" ;             ; 步骤名白名单

group            = [ group_meta ] ws? "(" ws? field_list_opt ws? ")" [ ws? group_len ] [ ws? group_sep ] ;
group_meta       = "alt" | "opt" | "some_of" | "seq" ;
group_len        = "[" number "]" ;
group_sep        = sep ;

; 列表：允许空、允许尾随逗号
field_list_opt   = [ field { ws? "," ws? field } [ ws? "," ] ] ;

field            = [ repeat ] data_type [ symbol_content ]
                   [ subfields ]
                   [ ":" ws? var_name ]
                   [ length ]
                   [ format ]
                   [ sep ]
                   { pipe } ;                              ; 允许多个管道

repeat           = [ number ] "*" ;                        ; "*ip" 或 "3*ip"
length           = "[" number "]" ;                       ; 仅顶层字段支持（子字段不支持）

; 复合字段（如 kvarr/json 等）的子字段列表
subfields        = "(" ws? subfields_opt ws? ")" ;
subfields_opt    = [ subfield { ws? "," ws? subfield } [ ws? "," ] ] ;
subfield         = [ opt_datatype | data_type ]
                   [ symbol_content ]
                   [ "@" ref_path ]
                   [ ":" ws? var_name ]
                   [ format ]
                   [ sep ]
                   { pipe } ;

opt_datatype     = "opt" "(" ws? data_type ws? ")" ;     ; 声明该子字段为可选

; 字段数据类型（与外部 crate wp-model-core::DataType 对应）
data_type        = builtin_type | ns_type | array_type ;

builtin_type     = "auto" | "bool" | "chars" | "symbol" | "peek_symbol"
                   | "digit" | "float" | "_" | "sn"
                   | "time" | "time/clf" | "time_iso" | "time_3339" | "time_2822" | "time_timestamp"
                   | "ip" | "ip_net" | "domain" | "email" | "port"
                   | "hex" | "base64"
                   | "kv" | "kvarr" | "json" | "exact_json"
                   | "url"
                   | "proto_text" | "obj"
                   | "id_card" | "mobile_phone" ;

ns_type          = path_ident ;                               ; 例如 http/request、http/status 等
; 注：实现层面建议对白名单前缀（如 "http/"）做校验，以避免任意路径膨胀语言面。

array_type       = "array" [ "/" key ] ;                 ; 如："array" 或 "array/ip"

; 仅当 data_type 为 symbol/peek_symbol 时允许携带内容
symbol_content   = "(" symbol_chars ")" ;

; 字段显示/抽取格式
format           = scope_fmt | quote_fmt | field_cnt ;
scope_fmt        = "<" any_chars "," any_chars ">" ;   ; 作用域首尾定界，如 <[,]>
quote_fmt        = '"' ;                                ; 等价首尾均为 '"'
field_cnt        = "^" number ;                          ; 仅 chars/_ 合法（实现约束）

; 分隔符（高/中优先级，原样拼接）。语法为反斜杠转义的字符序列，长度>=1
sep              = sep_char , { sep_char } ;             ; 例："\\," => ","；"\\!\\|" => "!|"
sep_char         = '\\' , any_char ;

; 字段级管道：函数调用或嵌套分组
pipe             = "|" ws? ( fun_call | group ) ;

; 预置函数（wpl_fun.rs）：
; - 选择器函数：take, last
; - f_ 前缀表示字段集合操作（需指定字段名）
; - 无前缀表示活跃字段操作
; - 转换函数：json_unescape, base64_decode
fun_call         = selector_fun | target_fun | active_fun | transform_fun ;

; 选择器函数
selector_fun     = take_fun | last_fun ;
take_fun         = "take" "(" ws? key ws? ")" ;
last_fun         = "last" "(" ws? ")" ;

; 字段集合操作函数（f_ 前缀）
target_fun       = f_has | f_chars_has | f_chars_not_has | f_chars_in
                 | f_digit_has | f_digit_in | f_ip_in ;
f_has            = "f_has" "(" ws? key ws? ")" ;
f_chars_has      = "f_chars_has" "(" ws? key ws? "," ws? path ws? ")" ;
f_chars_not_has  = "f_chars_not_has" "(" ws? key ws? "," ws? path ws? ")" ;
f_chars_in       = "f_chars_in" "(" ws? key ws? "," ws? path_array ws? ")" ;
f_digit_has      = "f_digit_has" "(" ws? key ws? "," ws? number ws? ")" ;
f_digit_in       = "f_digit_in" "(" ws? key ws? "," ws? number_array ws? ")" ;
f_ip_in          = "f_ip_in" "(" ws? key ws? "," ws? ip_array ws? ")" ;

; 活跃字段操作函数（无前缀）
active_fun       = has_fun | chars_has | chars_not_has | chars_in
                 | digit_has | digit_in | ip_in ;
has_fun          = "has" "(" ws? ")" ;
chars_has        = "chars_has" "(" ws? path ws? ")" ;
chars_not_has    = "chars_not_has" "(" ws? path ws? ")" ;
chars_in         = "chars_in" "(" ws? path_array ws? ")" ;
digit_has        = "digit_has" "(" ws? number ws? ")" ;
digit_in         = "digit_in" "(" ws? number_array ws? ")" ;
ip_in            = "ip_in" "(" ws? ip_array ws? ")" ;

; 转换函数
transform_fun    = json_unescape | base64_decode ;
json_unescape    = "json_unescape" "(" ws? ")" ;
base64_decode    = "base64_decode" "(" ws? ")" ;

path_array       = "[" ws? path { ws? "," ws? path } ws? "]" ;
number_array     = "[" ws? number { ws? "," ws? number } ws? "]" ;
ip_array         = "[" ws? ip_addr { ws? "," ws? ip_addr } ws? "]" ;

annotation       = "#[" ws? ann_item { ws? "," ws? ann_item } ws? "]" ;
ann_item         = tag_anno | copy_raw_anno ;
tag_anno         = "tag" "(" ws? tag_kv { ws? "," ws? tag_kv } ws? ")" ;
tag_kv           = ident ":" ( quoted_string | raw_string ) ;      ; 键为标识符；值为字符串
copy_raw_anno    = "copy_raw" "(" ws? "name" ws? ":" ws? ( quoted_string | raw_string ) ws? ")" ;

; 词法与辅助记号 --------------------------------------------------------
field_name       = var_name ;
rule_name        = exact_path ;
key              = key_char { key_char } ;              ; [A-Za-z0-9_./-]+
var_name         = var_char { var_char } ;              ; [A-Za-z0-9_.-]+
ref_path         = ref_char { ref_char } ;              ; [A-Za-z0-9_./\-.[\]*]+
; 标识符与路径标识符（推荐写法）
ident            = ( letter | '_' ) { letter | digit | '_' | '.' | '-' } ;
path_ident       = ident { "/" ident } ;

exact_path       = exact_path_char { exact_path_char } ; ; 不含 '[' ']' '*'
exact_path_char  = letter | digit | '_' | '.' | '/' | '-' ;
path             = key | ref_path ;

number           = digit { digit } ;
digit            = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ;

key_char         = letter | digit | '_' | '.' | '/' | '-' ;
var_char         = letter | digit | '_' | '.' | '-' ;
ref_char         = key_char | '[' | ']' | '*' ;

letter           = 'A'..'Z' | 'a'..'z' ;

quoted_string    = '"' { escaped | char_no_quote_backslash } '"' ;
raw_string       = 'r' '#' '"' { any_char } '"' '#' ;          ; r#"..."#，内部不处理转义（内容可包含 '"'）
char_no_quote    = ? any char except '"' ? ;
escaped          = '\\' ( '"' | '\\' | 'n' | 't' | 'r' | 'x' hex hex ) ;
char_no_quote_backslash = ? any char except '"' and '\\' ? ;
hex              = '0'..'9' | 'a'..'f' | 'A'..'F' ;

free_string      = { fchar } ;                          ; 直至 ',' 或 ')'（不含）
fchar            = ? any char except ',' and ')' ? ;

symbol_chars     = { schar } ;                          ; 允许除 ')' 与 '\\' 外字符，或使用 '\)' 转义
schar            = char_no_close_paren_backslash | '\\' ')' ;
char_no_close_paren_backslash = ? any char except ')' and '\\' ? ;
any_chars        = { any_char } ;
any_char         = ? any character ? ;

ip_addr          = quoted_string | ipv4 | ipv6 ;        ; 支持 IPv4/IPv6 裸字面量或带引号
ipv4             = digit1 "." digit1 "." digit1 "." digit1 ;
digit1           = digit { digit } ;
ipv6             = ? valid IPv6 literal (RFC 4291), including compressed forms like "::1" ? ;

ws               = { ' ' | '\t' | '\n' | '\r' } ;

;保留关键字（不可作为标识符使用；由实现侧进行冲突校验）
ReservedKeyword  = "package" | "rule" | "alt" | "opt" | "some_of" | "seq" | "order"
                 | "tag" | "copy_raw" | "include" | "macro" ;

语义说明

预处理管道

• preproc 管道（例如 |decode/base64|unquote/unescape|）出现在 express 起始处，独立于字段级 pipe
• 作用于整行输入，在字段解析前执行
• 执行顺序：从左到右
• 必须以 | 结尾

分组长度和分隔符

• group 后可跟 [n] 与分隔符 sep
• 长度会应用到组内所有字段
• sep 仅存储在组上，具体组合策略见实现

格式控制

• format 中的 field_cnt（^n）仅适用于 chars/_ 类型
• 其它类型将被拒绝（实现约束）

符号类型

• symbol/peek_symbol 可携带 symbol_content，如 symbol(boy)
• peek_symbol 等价于 symbol，且仅改变“窥探“语义（预读但不消费）

子字段

• subfields 中未显式 "@ref" 时，键默认为 "*"（通配键）
• 子字段支持 opt(type) 标记为可选

分隔符

• sep 写法需以反斜杠转义每个字符
• 例如 \\!\\| 代表字符串 "!|"
• 优先级：字段级 > 组级 > 上游

注解

• annotation 可用于 package 与 rule
• 若同时存在，会在 rule 侧合并（rule 优先）

相关文档

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

实现参考

• 语法实现：crates/wp-lang/src/parser/
• 管道函数：crates/wp-lang/src/parser/wpl_fun.rs
• 数据类型：外部 crate wp-model-core

WPL Field Functions 函数索引

本文档列出了 WP-Motor WPL 语言中所有可用的 field function（字段函数）。

字段选择函数 (Field Selectors)

字符串匹配函数 (String Matching)

数值匹配函数 (Numeric Matching)

IP 地址匹配函数 (IP Matching)

字段存在性检查 (Field Existence)

包装函数 (Wrapper Functions)

字符串转换函数 (String Transformation)

函数分类总览

按功能分类

1. 条件检查函数

用于检查字段是否满足特定条件，不修改字段值。

• 字符串检查：chars_has, chars_not_has, chars_in, starts_with, regex_match
• 数值检查：digit_has, digit_in, digit_range
• IP 检查：ip_in
• 存在性检查：has

2. 转换函数

修改字段值的函数。

• 解码：json_unescape, base64_decode
• 替换：chars_replace

3. 字段选择函数

用于选择特定字段作为活动字段。

• take: 按名称选择
• last: 选择最后一个字段

4. 包装函数

包装其他函数以改变其行为。

• not: 反转内部函数的成功/失败结果

按目标字段支持分类

操作当前活动字段

• chars_has, chars_not_has, chars_in, starts_with
• digit_has, digit_in, digit_range
• ip_in
• has
• json_unescape, base64_decode, chars_replace
• regex_match

可指定目标字段 (带 f_ 前缀)

• f_chars_has, f_chars_not_has, f_chars_in
• f_digit_has, f_digit_in
• f_ip_in
• f_has

使用示例

基本流水线

rule example_pipeline {
    # 1. 选择字段
    | take(message)

    # 2. 检查条件
    | chars_has(error)

    # 3. 转换处理
    | chars_replace(error, ERROR)
}

复杂条件组合

rule complex_filter {
    # 检查状态码范围
    | take(status)
    | digit_range(200, 299)  # 2xx 成功状态码

    # 检查消息内容
    | take(message)
    | regex_match('(?i)(success|ok|complete)')
}

分支逻辑

rule branching_logic {
    # 分支 1：错误日志
    (
        | take(level)
        | chars_in([ERROR, FATAL])
    )
    |
    # 分支 2：警告日志
    (
        | take(level)
        | chars_in([WARN, WARNING])
    )
}

性能参考

最佳实践

1. 合理使用函数类型

# ✅ 推荐：简单匹配使用 chars_has
| chars_has(error)

# ⚠️ 过度使用：简单匹配不需要正则
| regex_match('^error$')  # 性能较差

2. 优先使用专用函数

# ✅ 推荐：数值范围使用 digit_range
| digit_range(200, 299)

# ⚠️ 不推荐：用正则匹配数字
| regex_match('^2\d{2}$')  # 性能较差

3. 先选择字段再处理

# ✅ 正确
| take(message)
| chars_replace(old, new)

# ❌ 错误：没有活动字段
| chars_replace(old, new)  # 会失败

4. 组合使用条件函数

# ✅ 推荐：先用简单条件过滤，再用复杂条件
| chars_has(error)          # 快速过滤
| regex_match('error:\d+')  # 精确匹配

函数对比

chars_has vs regex_match

# 简单匹配：使用 chars_has
| chars_has(ERROR)

# 复杂匹配：使用 regex_match
| regex_match('(?i)error:\s*\d+')

digit_in vs digit_range

# 离散值：使用 digit_in
| digit_in([200, 404, 500])

# 连续范围：使用 digit_range
| digit_range(200, 299)

目标字段函数 vs 活动字段函数

# 活动字段函数
| take(status)
| digit_has(200)

# 目标字段函数（更简洁）
| f_digit_has(status, 200)

相关文档

• 开发指南: WPL Field Function 开发指南
• 字段引用: Field Reference
• 分隔符: Separator Guide

版本历史

• 1.15.1 (2026-02-07)

  • 新增 not() 包装函数
  • 修复 f_chars_not_has 和 chars_not_has 类型检查bug

• 1.13.4 (2026-02-03)

  • 新增 starts_with 函数
  • 完善文档体系

• 1.13.1 (2026-02-02)

  • 新增 digit_range 函数
  • 新增 regex_match 函数
  • 完善文档体系

• 1.11.0 (2026-01-29)

  • 新增 chars_replace 函数
  • 完善 Base64 和 JSON 转义支持

提示: 选择合适的函数类型可以显著提升性能。优先使用简单的专用函数，仅在需要复杂模式匹配时使用正则表达式。

WPL 字段引用使用指南

概述

在 WPL 中，使用 @ 符号来引用集合中的字段。支持两种字段名格式：

• 普通标识符：@field_name
• 单引号字符串：@'@special-field'（用于包含特殊字符的字段名）

快速开始

基本语法

# 引用普通字段
@field_name

# 引用带特殊字符的字段
@'special-field-name'

# 指定字段类型和别名
datatype@field_name: alias_name

简单示例

# JSON 解析 - 提取字段
rule parse_json {
    json(
        @src_ip: source_ip,
        @dst_ip: dest_ip,
        @message: msg
    )
}

# 使用单引号处理特殊字段名
rule parse_json_special {
    json(
        @'@client-ip': client,
        @'event.type': event,
        @'log/level': level
    )
}

普通字段引用

支持的字符

普通字段名（不带引号）支持以下字符：

• 字母和数字（a-z, A-Z, 0-9）
• 下划线（_）
• 斜杠（/）
• 连字符（-）
• 点号（.）
• 方括号（[, ]）- 用于数组索引
• 星号（*）- 用于通配符

示例

# 简单字段名
@user_id
@username
@ip_address

# 路径式字段名
@process/name
@parent/process/pid
@network/protocol

# 数组索引
@items[0]
@data[5]/value
@process[0]/path

# 通配符
@items[*]
@logs/*/message

单引号字段引用

何时使用

当字段名包含以下特殊字符时，必须使用单引号：

• @ 符号
• 空格
• 逗号（,）
• 等号（=）
• 括号（(, )）
• 尖括号（<, >）
• 井号（#）
• 其他非标准字符

基本语法

@'field name with spaces'
@'@field-with-at-sign'
@'field,with,commas'

转义字符

双引号字符串支持以下转义序列：

单引号字符串是原始字符串（raw string）：

• 只支持 \' 转义单引号本身
• 其他所有反斜杠 \ 都按字面意思处理
• \n、\t、\\ 等不会被转义

示例

# 双引号 - 支持完整转义
@"field\"name"      # 结果: field"name
@"path\\file"       # 结果: path\file
@"line\nbreak"      # 结果: line换行break

# 单引号 - 原始字符串，只转义 \'
@'field\'s name'    # 结果: field's name
@'path\to\file'     # 结果: path\to\file (字面反斜杠)
@'raw\nstring'      # 结果: raw\nstring (字面 \n)
@'C:\Users\test'    # 结果: C:\Users\test (Windows 路径)

推荐使用场景：

• 单引号：Windows 路径、Unix 路径、正则表达式、包含反斜杠的字符串
• 双引号：需要换行符、制表符等转义字符的场景

实际应用场景

场景 1：解析 Elasticsearch 日志

# Elasticsearch 字段通常使用 @ 前缀
rule elasticsearch_log {
    json(
        @'@timestamp': timestamp,
        @'@version': version,
        @message: msg,
        @'log.level': level,
        @'event.action': action
    )
}

场景 2：解析带空格的字段名

# CSV 或其他格式可能包含带空格的列名
rule csv_with_spaces {
    (
        @'First Name': first_name,
        @'Last Name': last_name,
        @'Email Address': email,
        @'Phone Number': phone
    )
}

场景 3：解析嵌套 JSON 字段

# JSON 字段路径包含特殊字符
rule nested_json {
    json(
        @'user.id': uid,
        @'user.profile.name': username,
        @'event#metadata': metadata,
        @'geo.location.lat': latitude,
        @'geo.location.lon': longitude
    )
}

场景 4：处理 Prometheus 指标

# Prometheus 指标名称包含多种特殊字符
rule prometheus_metrics {
    (
        @'http_requests_total{method="GET"}': get_requests,
        @'http_requests_total{method="POST"}': post_requests,
        @'process_cpu_seconds_total': cpu_usage
    )
}

场景 5：Windows 事件日志

# Windows 路径包含反斜杠
rule windows_events {
    json(
        @'Event.System.Provider': provider,
        @'Event.EventData.CommandLine': cmdline,
        @'Process\\Path': process_path
    )
}

场景 6：混合使用普通和特殊字段名

rule mixed_fields {
    json(
        # 普通字段名
        @username: user,
        @ip_address: ip,
        @timestamp: time,

        # 特殊字段名
        @'@client-ip': client,
        @'user.email': email,
        @'event#type': event_type,
        @'log level': level
    )
}

场景 7：KV 解析带特殊字段

# 键值对中包含特殊字符的键
rule kv_special_keys {
    kv(
        @'@timestamp': time,
        @'event-type': type,
        @'user/name': username,
        @'session#id': session
    )
}

take() 函数引号支持

take() 函数用于选择当前字段，同样支持单引号和双引号来处理包含特殊字符的字段名。

基本语法

# 普通字段名
| take(field_name)

# 双引号字段名
| take("@special-field")

# 单引号字段名
| take('@special-field')

使用场景

1. 选择带特殊字符的字段

rule select_special_fields {
    # 双引号
    | take("@timestamp")
    | take("field with spaces")
    | take("field,with,commas")

    # 单引号
    | take('@client-ip')
    | take('event.type')
    | take('log/level')
}

2. 转义字符支持

rule escaped_fields {
    # 双引号内转义
    | take("field\"name")
    | take("path\\with\\backslash")

    # 单引号内转义
    | take('field\'s name')
    | take('path\\to\\file')
}

3. 实际应用

# Elasticsearch 日志处理
rule elasticsearch {
    | take("@timestamp")
    | take("@version")
    | take("log.level")
}

# CSV 数据处理
rule csv_processing {
    | take('First Name')
    | take('Last Name')
    | take('Email Address')
}

# 混合使用
rule mixed_usage {
    | take(user_id)          # 普通字段
    | take("@timestamp")     # 双引号
    | take('event.type')     # 单引号
}

支持的转义字符

说明：

• 双引号：支持完整转义，类似 C/Java/JavaScript 字符串
• 单引号：原始字符串（raw string），只支持 \' 转义单引号本身，其他反斜杠都是字面字符

最佳实践

# ✅ 推荐 - 优先使用不带引号
| take(field_name)

# ✅ 推荐 - 特殊字符使用引号
| take("@timestamp")
| take('@client-ip')

# ✅ 推荐 - 根据内容选择引号类型
| take("field with spaces")         # 双引号，适合简单字符串
| take('it\'s a field')              # 单引号，只需转义 \'
| take('C:\Windows\System32')       # 单引号，Windows 路径
| take("line\nbreak")                # 双引号，需要换行符转义

字段类型指定

可以为字段指定数据类型：

# 不带引号的字段
ip@source_ip: src
digit@port: port_num
time@timestamp: time

# 带引号的字段
ip@'@client-ip': client
digit@'user.age': age
chars@'event message': msg

支持的类型包括：

• ip - IP 地址
• digit - 整数
• float - 浮点数
• time - 时间戳
• chars - 字符串
• json - JSON 对象
• kv - 键值对
• 等等

字段别名

使用 : 为字段指定别名：

# 普通字段别名
@source_ip: src
@destination_ip: dst
@user_id: uid

# 特殊字段别名
@'@timestamp': time
@'event.type': event
@'log/level': level

# 带类型和别名
ip@'@client-ip': client_ip
digit@'user.age': age
chars@'user name': username

使用限制

1. 不支持双引号

只支持单引号，不支持双引号：

# ✅ 正确
@'@field-name'

# ❌ 错误
@"@field-name"

2. 转义字符限制

转义字符只在单引号字符串内有效：

# ✅ 正确 - 单引号内转义
@'user\'s name'

# ❌ 错误 - 普通字段名不支持转义
@user\'s_name

3. 空字段名

字段名不能为空：

# ❌ 错误
@''

# ✅ 正确
@'_'  # 使用下划线作为字段名

4. 嵌套引用

单引号不支持嵌套：

# ❌ 错误
@'field\'nested\''

# ✅ 正确 - 使用转义
@'field\'nested'

性能说明

解析性能

• 普通字段名：零拷贝，性能最优

  @field_name  # 直接引用，无需分配
  

• 单引号字段名：需要解码转义字符

  @'@field'    # 无转义字符，性能接近普通字段
  @'field\'s'  # 有转义字符，需要额外处理
  

性能对比

优化建议

1. 优先使用普通字段名

   # ✅ 推荐
   @user_id
   @timestamp
   
   # ⚠️ 仅在必要时使用
   @'@timestamp'
   

2. 避免不必要的转义

   # ✅ 推荐
   @'simple-field'
   
   # ⚠️ 避免
   @'field\twith\tescape'  # 仅在确实需要制表符时使用
   

3. 批量操作时考虑性能

   # 大量字段解析时，优先使用普通字段名
   json(
       @user_id,      # 快
       @username,     # 快
       @'@metadata'   # 稍慢
   )
   

错误处理

常见错误

1. 字段名包含特殊字符但未使用引号

错误: 解析失败，意外的字符 '@'
原因: 字段名包含 @ 但未使用单引号
解决: @'@field-name'

2. 单引号未闭合

错误: 字符串未闭合
原因: 缺少结束的单引号
解决: 确保引号成对出现 @'field-name'

3. 转义字符错误

错误: 无效的转义序列
原因: 使用了不支持的转义字符
解决: 只使用支持的转义序列 \', \\, \n, \t, \r, \xHH

4. 空字段名

错误: 字段名不能为空
原因: @'' 或 @ 后无内容
解决: 提供有效的字段名

最佳实践

1. 命名规范

# ✅ 推荐 - 使用下划线分隔
@user_id
@client_ip
@event_timestamp

# ⚠️ 避免 - 除非必要
@'user id'
@'client-ip'

2. 保持一致性

# ✅ 推荐 - 统一风格
rule consistent_naming {
    json(
        @user_id,
        @user_name,
        @user_email
    )
}

# ⚠️ 避免 - 混合风格
rule inconsistent_naming {
    json(
        @user_id,
        @'user name',
        @userEmail
    )
}

3. 文档化特殊字段

# ✅ 推荐 - 添加注释说明
rule documented {
    json(
        # Elasticsearch 的 @timestamp 字段
        @'@timestamp': time,

        # 日志级别（包含空格）
        @'log level': level
    )
}

4. 使用类型前缀

# ✅ 推荐 - 明确指定类型
time@'@timestamp': time
ip@'@client-ip': client
chars@'event message': msg

5. 别名使用规范

# ✅ 推荐 - 使用简短的别名
@'very.long.nested.field.name': short_name
@'@timestamp': time
@'event.action': action

# ⚠️ 避免 - 别名过长
@'@timestamp': timestamp_value_from_elasticsearch

调试技巧

1. 逐步验证字段引用

# 第一步：验证单个字段
rule test_single {
    json(@'@timestamp')
}

# 第二步：添加更多字段
rule test_multiple {
    json(
        @'@timestamp',
        @'event.type'
    )
}

# 第三步：添加类型和别名
rule test_complete {
    time@'@timestamp': time,
    chars@'event.type': event
}

2. 检查字段名拼写

# 使用 JSON 工具查看原始字段名
echo '{"@timestamp": "2024-01-01"}' | jq 'keys'

# 输出: ["@timestamp"]
# WPL 中使用: @'@timestamp'

3. 测试转义字符

# 逐个测试转义字符
@'test\'quote'      # 单引号
@'test\\backslash'  # 反斜杠
@'test\nnewline'    # 换行符

4. 使用调试模式

# 使用 WP-Motor 调试模式查看解析结果
wp-motor --debug rule.wpl < test.log

常见问题 (FAQ)

Q1: 何时必须使用单引号？

当字段名包含以下字符时必须使用单引号：

• @、空格、逗号、等号、括号、尖括号、井号等特殊字符

Q2: 单引号和双引号有什么区别？

WPL 只支持单引号 ' 用于字段名引用。双引号 " 用于其他语法元素（如作用域标记）。

Q3: 如何在字段名中包含单引号？

使用反斜杠转义：@'user\'s name'

Q4: 性能影响有多大？

对于大多数应用场景，性能影响可忽略不计（纳秒级差异）。只在极高性能要求时才需要考虑。

Q5: 可以使用变量作为字段名吗？

不可以，字段名必须是静态的字面量。

Q6: 如何处理动态字段名？

使用通配符或字段组合：

@items[*]/name     # 匹配所有数组元素的 name 字段
@'prefix*'         # 匹配以 prefix 开头的字段（如果支持）

Q7: 支持 Unicode 字符吗？

支持，字段名可以包含任意 Unicode 字符：

@'用户名称'
@'événement'
@'フィールド'

更多资源

• 分隔符使用指南: docs/usage/wpl/separator.md
• chars_replace 使用指南: docs/usage/wpl/chars_replace.md
• WPL Field Function 开发指南: docs/guide/wpl_field_func_development_guide.md
• 源代码:
  • crates/wp-lang/src/parser/utils.rs (take_ref_path_or_quoted)
  • crates/wp-lang/src/parser/wpl_field.rs (wpl_id_field)

版本历史

• 1.11.0 (2026-01-29)
  • 新增单引号字段名支持（@'@special-field'）
  • 新增 take() 函数单引号和双引号支持
  • 支持 take("@field") 和 take('@field') 语法
  • 添加转义字符支持（\", \', \\, \n, \t）
  • 添加完整的测试覆盖

提示: 优先使用普通字段名以获得最佳性能，仅在字段名包含特殊字符时使用引号。

WPL 分隔符使用指南

概述

分隔符（Separator）是 WPL 中用于分割日志字段的关键语法元素。通过灵活使用分隔符，可以解析各种格式的结构化日志数据。

快速开始

基本语法

| take(field_name) separator

分隔符写在字段定义之后，用于指示该字段在何处结束。

简单示例

# 使用空格分隔
| take(ip) \s
| take(method) \s
| take(path)

# 使用逗号分隔
| take(name) ,
| take(age) ,
| take(city)

内置分隔符

1. 空格分隔符 \s

匹配单个空格字符。

# 输入: "192.168.1.1 GET /api/users"
rule parse_log {
    | take(ip) \s
    | take(method) \s
    | take(path)
}

适用场景：

• Apache/Nginx 访问日志
• 空格分隔的简单日志
• 标准格式日志文件

2. 制表符分隔符 \t

匹配单个制表符（Tab）字符。

# 输入: "user001\t25\tBeijing"
rule parse_tsv {
    | take(user_id) \t
    | take(age) \t
    | take(city)
}

适用场景：

• TSV（Tab-Separated Values）文件
• 数据库导出文件
• 制表符对齐的日志

3. 通用空白分隔符 \S

匹配空格或制表符（二选一）。

# 输入: "field1 field2\tfield3"（混合空格和制表符）
rule parse_flexible {
    | take(col1) \S
    | take(col2) \S
    | take(col3)
}

适用场景：

• 格式不统一的日志（混合空格和 Tab）
• 手工编辑过的配置文件
• 宽松的数据解析

行为说明：

• 遇到空格或制表符都会停止
• 灵活处理格式不一致的数据源

4. 行尾分隔符 \0

读取到行尾（换行符或字符串结束）。

# 输入: "prefix_value some remaining text until end"
rule parse_to_end {
    | take(prefix) _
    | take(remaining) \0
}

适用场景：

• 解析最后一个字段
• 读取消息正文
• 获取剩余所有内容

别名：

• \0 和 0 等价

5. 自定义字符分隔符

使用任意单个字符作为分隔符。

# 逗号分隔
| take(name) ,
| take(age) ,

# 竖线分隔
| take(id) |
| take(status) |

# 分号分隔
| take(key) ;
| take(value) ;

支持的字符：

• 逗号 ,
• 竖线 |
• 分号 ;
• 冒号 :
• 等号 =
• 斜杠 /
• 等任意单字符

6. 自定义字符串分隔符

使用多字符字符串作为分隔符。

# 使用 " | " 分隔
| take(field1) " | "
| take(field2) " | "

# 使用 " :: " 分隔
| take(module) " :: "
| take(function) " :: "

适用场景：

• 格式化输出的日志
• 特定格式协议
• 需要明确边界的数据

实际应用场景

场景 1：解析 Nginx 访问日志

# 日志格式: 192.168.1.1 - - [29/Jan/2024:10:30:45 +0800] "GET /api/users HTTP/1.1" 200 1234
rule nginx_access_log {
    | take(client_ip) \s
    | take(identity) \s
    | take(user) \s
    | take(timestamp) \s
    | take(request) \s
    | take(status_code) \s
    | take(bytes_sent) \0
}

场景 2：解析 TSV 数据

# 输入: "2024-01-29\t10:30:45\tERROR\tDatabase connection failed"
rule tsv_log {
    | take(date) \t
    | take(time) \t
    | take(level) \t
    | take(message) \0
}

场景 3：解析 CSV 数据

# 输入: "John Smith,30,New York,Engineer"
rule csv_parser {
    | take(name) ,
    | take(age) ,
    | take(city) ,
    | take(job) \0
}

场景 4：解析结构化日志

# 输入: "level=error | module=database | msg=Connection timeout"
rule structured_log {
    | take(level_prefix) =
    | take(level_value) " | "
    | take(module_prefix) =
    | take(module_value) " | "
    | take(msg_prefix) =
    | take(message) \0
}

场景 5：处理混合空白的日志

# 输入: "192.168.1.1 \tGET\t /api/data"（混合空格和制表符）
rule flexible_whitespace {
    | take(ip) \S
    | take(method) \S
    | take(path) \0
}

场景 6：解析 Syslog 格式

# 输入: "Jan 29 10:30:45 hostname app[1234]: Error message here"
rule syslog {
    | take(month) \s
    | take(day) \s
    | take(time) \s
    | take(hostname) \s
    | take(app_tag) ": "
    | take(message) \0
}

场景 7：解析键值对日志

# 输入: "user=admin;action=login;ip=192.168.1.1;status=success"
rule kv_log {
    | take(user_key) =
    | take(user_value) ;
    | take(action_key) =
    | take(action_value) ;
    | take(ip_key) =
    | take(ip_value) ;
    | take(status_key) =
    | take(status_value) \0
}

分隔符优先级

WPL 支持三个级别的分隔符设置：

1. 字段级分隔符（优先级 3，最高）

| take(field1) ,  # 该字段使用逗号
| take(field2) \s # 该字段使用空格

2. 组级分隔符（优先级 2）

group {
    sep = \t  # 组内所有字段默认使用制表符
    | take(field1)
    | take(field2)
}

3. 继承分隔符（优先级 1，最低）

从上游规则继承的默认分隔符。

优先级规则

字段级 > 组级 > 继承级

group {
    sep = \t         # 组级：制表符
    | take(f1)       # 使用 \t
    | take(f2) ,     # 使用 ,（字段级覆盖组级）
    | take(f3)       # 使用 \t
}

分隔符行为

全局替换 vs 单次匹配

分隔符只在当前字段结束位置匹配一次：

# 输入: "hello,world,test"
| take(first) ,   # 读取 "hello"，消费第一个逗号
| take(second) ,  # 读取 "world"，消费第二个逗号
| take(third) \0  # 读取 "test"

分隔符消费行为

默认情况下，分隔符会被消费（从输入中移除）：

# 输入: "a,b,c"
| take(x) ,  # 读取 "a"，消费 ","，剩余 "b,c"
| take(y) ,  # 读取 "b"，消费 ","，剩余 "c"

分隔符不存在的情况

如果到达字符串末尾仍未找到分隔符，读取到末尾：

# 输入: "field1 field2"
| take(f1) ,  # 未找到逗号，读取全部 "field1 field2"

高级用法

组合使用多种分隔符

# 输入: "192.168.1.1:8080/api/users?id=123"
rule url_parse {
    | take(ip) :
    | take(port) /
    | take(api_path) /
    | take(resource) ?
    | take(query_string) \0
}

处理可选字段

# 输入可能是: "user,30,city" 或 "user,,city"（age 为空）
rule optional_fields {
    | take(name) ,
    | take(age) ,      # 可能为空字符串
    | take(city) \0
}

跳过不需要的字段

# 只提取第 1 和第 3 个字段
rule skip_fields {
    | take(field1) ,
    | take(_skip) ,    # 临时变量，不保存
    | take(field3) \0
}

使用限制

1. 分隔符不支持正则表达式

# ❌ 不支持正则
| take(field) [0-9]+

# ✅ 使用固定字符串
| take(field) \s

2. 分隔符区分大小写

# "ABC" 和 "abc" 是不同的分隔符
| take(field1) ABC
| take(field2) abc

3. 空字符串不能作为分隔符

# ❌ 不支持
| take(field) ""

# ✅ 使用 \0 读取到末尾
| take(field) \0

4. 转义字符限制

当前支持的转义字符：

• \s - 空格
• \t - 制表符
• \S - 空格或制表符
• \0 - 行尾

其他转义字符（如 \n、\r）需要使用实际字符。

性能说明

单字符分隔符

性能最优，推荐优先使用：

| take(f1) ,
| take(f2) \s
| take(f3) \t

• 时间复杂度：O(n)
• 扫描速度：约 500 MB/s

多字符分隔符

性能略低，但仍然高效：

| take(f1) " | "
| take(f2) " :: "

• 时间复杂度：O(n × m)，m 为分隔符长度
• 扫描速度：约 300-400 MB/s

通用空白分隔符 \S

需要逐字符检查，性能介于两者之间：

| take(f1) \S

• 时间复杂度：O(n)
• 扫描速度：约 400 MB/s

错误处理

常见错误

1. 分隔符未找到

错误: 未找到分隔符 ','
原因: 输入字符串中不包含指定的分隔符
解决: 检查输入格式或使用 \0 读取到末尾

2. 分隔符语法错误

错误: invalid separator
原因: 使用了不支持的分隔符语法
解决: 参考本文档使用正确的分隔符格式

3. 字段顺序错误

错误: 字段解析失败
原因: 字段定义顺序与实际数据不匹配
解决: 调整字段顺序以匹配输入格式

最佳实践

1. 优先使用内置分隔符

# ✅ 推荐
| take(f1) \s
| take(f2) \t

# ⚠️ 避免（除非必要）
| take(f1) " "
| take(f2) "\t"

2. 明确指定最后字段的分隔符

# ✅ 推荐（明确到行尾）
| take(message) \0

# ⚠️ 不清晰
| take(message)  # 依赖默认行为

3. 使用 \S 处理不规范数据

# ✅ 推荐（兼容性好）
| take(field1) \S
| take(field2) \S

# ⚠️ 可能失败（如果混合了空格和制表符）
| take(field1) \s
| take(field2) \s

4. 复杂格式使用多字符分隔符

# ✅ 清晰准确
| take(level) " | "
| take(message) " | "

# ⚠️ 可能误匹配
| take(level) |
| take(message) |

5. 组合使用字段级和组级分隔符

# ✅ 推荐（减少重复）
group {
    sep = ,
    | take(f1)
    | take(f2)
    | take(f3) \0  # 最后字段使用不同分隔符
}

调试技巧

1. 逐字段验证

# 先解析第一个字段
| take(field1) ,

# 确认成功后添加第二个
| take(field1) ,
| take(field2) ,

# 依次添加...

2. 使用临时字段查看中间结果

| take(field1) ,
| take(_debug) ,    # 临时字段，查看剩余内容
| take(field2) \0

3. 打印分隔符位置

在测试环境中，使用调试模式查看分隔符匹配情况：

wp-motor --debug rule.wpl < test.log

4. 验证分隔符字符

对于不可见字符（如制表符），使用十六进制查看器确认：

# 查看文件中的制表符
cat -A test.log
# 或
hexdump -C test.log | head

常见问题 (FAQ)

Q1: \s 和 \S 有什么区别？

• \s：只匹配空格 (space)
• \S：匹配空格或制表符 (space OR tab)

# 输入: "a b"
| take(x) \s  # ✅ 匹配成功

# 输入: "a\tb"
| take(x) \s  # ❌ 匹配失败（这是制表符，不是空格）
| take(x) \S  # ✅ 匹配成功

Q2: 如何处理连续的分隔符？

WPL 会将连续分隔符视为多个空字段：

# 输入: "a,,c"
| take(f1) ,  # 读取 "a"
| take(f2) ,  # 读取 ""（空字符串）
| take(f3) \0 # 读取 "c"

Q3: 分隔符会影响性能吗？

单字符分隔符性能最优，多字符分隔符略慢，但对于大多数场景影响可忽略。

Q4: 如何解析嵌套结构？

使用多级分隔符：

# 输入: "k1=v1;k2=v2|k3=v3;k4=v4"
rule nested {
    | take(group1) |
    | take(group2) \0
}
# 然后在每个 group 内再用 ; 和 = 解析

Q5: 分隔符可以是中文吗？

可以，支持 Unicode 字符：

# 使用中文逗号分隔
| take(field1) ，
| take(field2) ，

Q6: \0 和省略分隔符有区别吗？

建议显式使用 \0，语义更清晰：

# ✅ 推荐（明确）
| take(message) \0

# ⚠️ 可以但不明确
| take(message)

Q7: 如何处理引号内的分隔符？

对于包含引号的复杂格式，建议使用专门的解析器（如 JSON、KV 解析器）：

# 复杂 CSV（带引号）
# 输入: "field1","field with , comma","field3"
# 建议使用 CSV 解析器而非手动分隔符

更多资源

• WPL 语法参考: docs/guide/wpl_syntax.md
• 解析器开发指南: docs/guide/wpl_field_func_development_guide.md
• chars_replace 使用指南: docs/usage/wpl/chars_replace.md
• 源代码: crates/wp-lang/src/ast/syntax/wpl_sep.rs

版本历史

• 1.11.0 (2026-01-29)

  • 新增 \t 制表符分隔符支持
  • 新增 \S 通用空白分隔符（空格或制表符）
  • 优化 Whitespace 分隔符性能
  • 添加完整的测试覆盖

• 1.10.x 及更早版本

  • 支持 \s（空格）和 \0（行尾）
  • 支持自定义字符和字符串分隔符

提示: 分隔符是 WPL 解析的核心，选择合适的分隔符可以大大简化日志解析规则。

chars_replace 函数使用指南

概述

chars_replace 是 WPL (WP Language) 中的字符串替换函数，用于在日志字段中查找并替换指定的子字符串。

快速开始

基本语法

chars_replace(target, replacement)

• target: 要查找并替换的字符串
• replacement: 替换后的新字符串

简单示例

# 将 "error" 替换为 "warning"
chars_replace(error, warning)

# 将 "ERROR" 替换为 "WARN"
chars_replace(ERROR, WARN)

参数格式

1. 不带引号（简单标识符）

适用于简单的字段名或关键词：

chars_replace(old_value, new_value)
chars_replace(test-old, test-new)
chars_replace(错误, 警告)

支持的字符：

• 字母（a-z, A-Z）
• 数字（0-9）
• 下划线（_）
• 点（.）
• 斜杠（/）
• 连字符（-）
• Unicode 字符（中文、日文等）

2. 带引号（特殊字符）

适用于包含特殊字符的字符串：

chars_replace("test,old", "test,new")         # 包含逗号
chars_replace("hello world", "goodbye world") # 包含空格
chars_replace("status=error", "status=ok")    # 包含等号
chars_replace("[ERROR]", "[WARN]")            # 包含方括号

必须使用引号的场景：

• 包含逗号（,）
• 包含空格
• 包含等号（=）
• 包含方括号（[]）
• 包含其他特殊符号

3. 混合使用

可以混合使用带引号和不带引号的参数：

chars_replace("test,old", new_value)
chars_replace(old_value, "new,value")

4. 空字符串（删除文本）

使用空引号删除目标字符串：

# 删除 "DEBUG: " 前缀
chars_replace("DEBUG: ", "")

# 删除逗号
chars_replace(",", "")

实际应用场景

场景 1：标准化日志级别

# 统一大小写
chars_replace(error, ERROR)
chars_replace(warning, WARNING)

# 标准化格式
chars_replace("[ERROR]", "ERROR:")
chars_replace("[WARN]", "WARNING:")

场景 2：清理日志内容

# 删除调试前缀
chars_replace("DEBUG: ", "")

# 删除多余的空格
chars_replace("  ", " ")

# 删除换行符
chars_replace("\n", " ")

场景 3：URL 参数替换

chars_replace("status=error", "status=ok")
chars_replace("code=500", "code=200")

场景 4：CSV 字段处理

# 替换带逗号的名字
chars_replace("Smith, John", "John Smith")
chars_replace("Doe, Jane", "Jane Doe")

场景 5：路径标准化

# Windows 路径转 Unix 路径
chars_replace("\\", "/")

# 简化路径
chars_replace("/usr/local/", "/opt/")

场景 6：多语言支持

# 中文替换
chars_replace(错误, 警告)
chars_replace("错误：", "警告：")

# 日文替换
chars_replace(エラー, 警告)

场景 7：敏感信息脱敏

# 替换密码
chars_replace("password=12345", "password=***")

# 替换令牌
chars_replace("token=abc123xyz", "token=***")

使用限制

不支持的特性

1. 转义字符：

   # ❌ 不支持（会解析错误）
   chars_replace("say \"hello\"", "say 'hi'")
   

2. 正则表达式：

   # ❌ 不支持正则
   chars_replace("[0-9]+", "NUMBER")  # 会按字面匹配
   

3. 通配符：

   # ❌ 不支持通配符
   chars_replace("error*", "warning")  # 会按字面匹配
   

类型限制

chars_replace 只能处理字符串类型的字段：

# ✅ 正确 - 字段是字符串
message: "error occurred" -> chars_replace(error, warning)

# ❌ 错误 - 字段是数字
status_code: 500 -> chars_replace(500, 200)  # 会失败

# ❌ 错误 - 字段是 IP 地址
ip_address: 192.168.1.1 -> chars_replace(192, 10)  # 会失败

替换行为

• 全局替换：替换字段中所有匹配的子字符串

  # 输入: "hello hello hello"
  chars_replace(hello, hi)
  # 输出: "hi hi hi"
  

• 大小写敏感：区分大小写

  # 输入: "Error error ERROR"
  chars_replace(error, warning)
  # 输出: "Error warning ERROR"  # 只替换小写的 error
  

完整示例

示例 1：日志级别标准化流水线

rule log_normalization {
    # 标准化不同格式的 ERROR
    | chars_replace("[ERROR]", "ERROR:")
    | chars_replace("ERR:", "ERROR:")
    | chars_replace("Err:", "ERROR:")

    # 标准化 WARNING
    | chars_replace("[WARN]", "WARNING:")
    | chars_replace("Warn:", "WARNING:")

    # 删除调试信息
    | chars_replace("DEBUG: ", "")
}

示例 2：CSV 数据清理

rule csv_cleanup {
    # 标准化姓名格式（从 "Last, First" 到 "First Last"）
    | chars_replace("Smith, John", "John Smith")
    | chars_replace("Doe, Jane", "Jane Doe")

    # 删除多余的引号
    | chars_replace("\"", "")

    # 标准化分隔符
    | chars_replace(";", ",")
}

示例 3：多步骤替换

rule multi_step_replace {
    # 第一步：替换日志级别
    | chars_replace(error, ERROR)

    # 第二步：添加时间戳前缀（通过替换空字符串）
    | chars_replace("", "[2024-01-29] ")

    # 第三步：替换服务名
    | chars_replace(old-service, new-service)
}

性能说明

• 时间复杂度：O(n) - n 为字段长度
• 空间复杂度：O(n) - 需要创建新字符串
• 性能建议：
  • 短字符串（< 1KB）：性能优秀，延迟 < 1μs
  • 长字符串（1-10KB）：仍然快速，延迟 < 10μs
  • 超长字符串（> 10KB）：考虑性能影响

错误处理

常见错误

1. 字段不存在

   错误: chars_replace | no active field
   原因: 当前没有活动字段
   解决: 使用 take() 或其他选择器先选择字段
   

2. 字段类型不匹配

   错误: chars_replace
   原因: 字段不是字符串类型
   解决: 确保字段是 Chars 类型
   

3. 语法错误

   错误: invalid symbol, expected need ','
   原因: 包含逗号的参数未使用引号
   解决: 使用引号包裹参数
   

与其他函数配合使用

与字段选择器配合

# 先选择字段，再替换
| take(message)
| chars_replace(error, warning)

与条件检查配合

# 只在特定条件下替换
| chars_has(error)
| chars_replace(error, warning)

与转换函数配合

# 先解码 Base64，再替换
| base64_decode()
| chars_replace(old_value, new_value)

最佳实践

1. 优先使用不带引号的格式

# ✅ 推荐（简洁）
chars_replace(error, warning)

# ⚠️ 可以但不必要
chars_replace("error", "warning")

2. 复杂字符串使用引号

# ✅ 正确
chars_replace("status=error", "status=ok")

# ❌ 错误（语法错误）
chars_replace(status=error, status=ok)

3. 空字符串删除文本

# ✅ 推荐（明确意图）
chars_replace("DEBUG: ", "")

# ⚠️ 不清晰
chars_replace("DEBUG: ", nothing)  # 不存在 nothing 关键字

4. 按顺序执行多次替换

# ✅ 正确（逐步替换）
| chars_replace(error, ERROR)
| chars_replace(ERROR, WARNING)
# 结果: error -> ERROR -> WARNING

# ⚠️ 注意顺序
| chars_replace(ERROR, WARNING)
| chars_replace(error, ERROR)
# 结果: error -> ERROR（第二步不会再变成 WARNING）

5. 测试边界情况

# 测试空字符串
chars_replace("", "prefix")  # 在每个字符间插入

# 测试单字符
chars_replace(",", ";")      # 简单替换

# 测试长字符串
chars_replace("very long string to find", "replacement")

调试技巧

1. 逐步测试

# 第一步：只做替换
| chars_replace(error, warning)

# 第二步：添加更多替换
| chars_replace(error, warning)
| chars_replace(warning, info)

2. 检查字段类型

# 使用 has() 确认字段存在
| has()

# 使用 chars_has() 确认是字符串类型
| chars_has(some_value)

3. 查看替换结果

在测试环境中打印替换前后的值：

# 使用 WP-Motor 的调试模式
wp-motor --debug rule.wpl < test.log

常见问题 (FAQ)

Q1: 如何替换换行符？

# 方法 1：使用实际的换行符（如果解析器支持）
chars_replace("\n", " ")

# 方法 2：根据实际编码处理
chars_replace("
", " ")  # 实际换行

Q2: 如何同时替换多个不同的字符串？

# 使用多个 chars_replace 调用
| chars_replace(error, ERROR)
| chars_replace(warning, WARNING)
| chars_replace(info, INFO)

Q3: 如何实现大小写不敏感的替换？

chars_replace 是大小写敏感的，需要多次调用：

| chars_replace(error, ERROR)
| chars_replace(Error, ERROR)
| chars_replace(ERROR, ERROR)

Q4: 替换会修改原始字段吗？

是的，chars_replace 会直接修改活动字段的值。

Q5: 性能够用吗？

对于大多数日志处理场景，性能完全足够：

• 单条日志 < 10KB：几乎无感知
• 高吞吐量场景：可处理 100K+ 日志/秒

更多资源

• 开发指南: docs/guide/wpl_field_func_development_guide.md
• 解析器实现: docs/guide/chars_replace_parser_tests.md
• 性能分析: docs/guide/take_quoted_string_performance.md
• 源代码: crates/wp-lang/src/ast/processor/function.rs

版本历史

• 1.11.0 (2026-01-29)
  • 初始实现
  • 支持基本字符串替换
  • 支持带引号字符串（包含逗号、空格等）
  • 添加完整的测试覆盖

提示: 如果您在使用过程中遇到问题，请参考错误处理章节或查看开发指南。

regex_match 函数使用指南

概述

regex_match 是 WPL (WP Language) 中的正则表达式匹配函数，用于检查日志字段的字符串内容是否匹配指定的正则表达式模式。使用 Rust 的 regex 引擎，支持完整的正则表达式语法。

快速开始

基本语法

regex_match('pattern')

• pattern: 正则表达式模式（推荐使用单引号）
• 匹配成功返回 Ok，失败返回 Err

简单示例

# 匹配纯数字
regex_match('^\d+$')

# 匹配邮箱格式
regex_match('^\w+@\w+\.\w+$')

# 匹配 IP 地址
regex_match('^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$')

# 匹配 HTTP 方法
regex_match('^(GET|POST|PUT|DELETE)$')

重要提示：引号使用

推荐：使用单引号（原始字符串）

# ✅ 推荐：单引号不处理转义，适合正则表达式
regex_match('^\d+$')           # \d 保持原样
regex_match('^\w+@\w+\.\w+$')  # \w, \. 保持原样
regex_match('^[A-Z]+\d+$')     # 完美工作

避免：双引号会导致转义问题

# ❌ 错误：双引号会尝试转义 \d
regex_match("^\d+$")  # 解析失败！\d 不是有效的转义序列

# ❌ 错误：\w 也会失败
regex_match("^\w+$")  # 解析失败！

原因：WPL 的双引号字符串解析器只支持 \", \\, \n, \t 这几种转义字符，而正则表达式中的 \d, \w, \s 等会导致解析错误。

正则表达式语法

regex_match 使用 Rust regex 引擎，支持以下特性：

1. 基本匹配

# 字面字符
regex_match('hello')          # 匹配 "hello"
regex_match('error')          # 匹配 "error"

2. 字符类

# 数字
regex_match('\d')             # 匹配任意数字 [0-9]
regex_match('\d+')            # 匹配一个或多个数字
regex_match('\d{3}')          # 匹配恰好3个数字

# 字母和数字
regex_match('\w')             # 匹配 [a-zA-Z0-9_]
regex_match('\w+')            # 匹配一个或多个单词字符

# 空白字符
regex_match('\s')             # 匹配空格、制表符、换行符
regex_match('\s+')            # 匹配一个或多个空白字符

# 自定义字符类
regex_match('[a-z]')          # 匹配小写字母
regex_match('[A-Z]')          # 匹配大写字母
regex_match('[0-9]')          # 匹配数字
regex_match('[a-zA-Z0-9]')    # 匹配字母或数字

3. 量词

# * - 0次或多次
regex_match('a*')             # 匹配 "", "a", "aa", "aaa"...

# + - 1次或多次
regex_match('a+')             # 匹配 "a", "aa", "aaa"... (不匹配空串)

# ? - 0次或1次
regex_match('colou?r')        # 匹配 "color" 或 "colour"

# {n} - 恰好n次
regex_match('\d{4}')          # 匹配4位数字

# {n,m} - n到m次
regex_match('\d{2,4}')        # 匹配2到4位数字

# {n,} - 至少n次
regex_match('\d{3,}')         # 匹配3位或更多数字

4. 锚点

# ^ - 字符串开始
regex_match('^\d+')           # 必须以数字开头

# $ - 字符串结束
regex_match('\d+$')           # 必须以数字结尾

# ^...$ - 完全匹配
regex_match('^\d+$')          # 整个字符串必须是数字

5. 分组和选择

# (...) - 分组
regex_match('(ab)+')          # 匹配 "ab", "abab", "ababab"...

# | - 选择（或）
regex_match('cat|dog')        # 匹配 "cat" 或 "dog"
regex_match('^(GET|POST)$')   # 匹配 "GET" 或 "POST"

# (?:...) - 非捕获分组
regex_match('(?:ab)+')        # 与 (ab)+ 功能相同，但不捕获

6. 特殊字符转义

# 转义元字符
regex_match('\.')             # 匹配点号 .
regex_match('\[')             # 匹配左方括号 [
regex_match('\(')             # 匹配左括号 (
regex_match('\$')             # 匹配美元符号 $
regex_match('\*')             # 匹配星号 *

7. 标志

# (?i) - 大小写不敏感
regex_match('(?i)error')      # 匹配 "error", "ERROR", "Error"

# (?m) - 多行模式
regex_match('(?m)^line')      # ^ 匹配每行开始

# (?s) - 单行模式（. 匹配换行符）
regex_match('(?s).*')         # . 可以匹配换行符

实际应用场景

场景 1：日志级别匹配

rule log_level_filter {
    # 选择日志消息字段
    | take(message)

    # 匹配包含 ERROR 或 FATAL 的消息（大小写不敏感）
    | regex_match('(?i)(error|fatal)')
}

# 示例数据：
# message: "Error occurred"     → ✅ 匹配
# message: "FATAL exception"    → ✅ 匹配
# message: "Warning message"    → ❌ 不匹配

场景 2：邮箱地址验证

rule email_validation {
    # 选择邮箱字段
    | take(email)

    # 验证邮箱格式
    | regex_match('^\w+(\.\w+)*@\w+(\.\w+)+$')
}

# 示例数据：
# email: "user@example.com"           → ✅ 匹配
# email: "john.doe@company.co.uk"     → ✅ 匹配
# email: "invalid-email"              → ❌ 不匹配
# email: "@example.com"               → ❌ 不匹配

场景 3：IP 地址匹配

rule ip_address_filter {
    # 选择 IP 地址字段
    | take(client_ip)

    # 匹配内网 IP（192.168.x.x）
    | regex_match('^192\.168\.\d{1,3}\.\d{1,3}$')
}

# 示例数据：
# client_ip: "192.168.1.1"    → ✅ 匹配
# client_ip: "192.168.0.100"  → ✅ 匹配
# client_ip: "10.0.0.1"       → ❌ 不匹配
# client_ip: "8.8.8.8"        → ❌ 不匹配

场景 4：URL 路径过滤

rule api_endpoint_filter {
    # 选择请求路径
    | take(path)

    # 匹配 API 端点（/api/v1/...）
    | regex_match('^/api/v\d+/')
}

# 示例数据：
# path: "/api/v1/users"         → ✅ 匹配
# path: "/api/v2/products"      → ✅ 匹配
# path: "/static/image.png"     → ❌ 不匹配

场景 5：时间戳格式验证

rule timestamp_validation {
    # 选择时间戳字段
    | take(timestamp)

    # 匹配 ISO 8601 格式（YYYY-MM-DD HH:MM:SS）
    | regex_match('^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$')
}

# 示例数据：
# timestamp: "2024-01-29 15:30:45"  → ✅ 匹配
# timestamp: "2024-1-9 5:3:5"       → ❌ 不匹配（缺少前导零）
# timestamp: "29/01/2024 15:30"     → ❌ 不匹配（格式不同）

场景 6：HTTP 方法验证

rule http_method_check {
    # 选择 HTTP 方法字段
    | take(method)

    # 只接受安全的 HTTP 方法
    | regex_match('^(GET|HEAD|OPTIONS)$')
}

# 示例数据：
# method: "GET"     → ✅ 匹配
# method: "HEAD"    → ✅ 匹配
# method: "POST"    → ❌ 不匹配
# method: "DELETE"  → ❌ 不匹配

场景 7：版本号匹配

rule version_check {
    # 选择版本字段
    | take(version)

    # 匹配语义化版本号（如 1.2.3）
    | regex_match('^\d+\.\d+\.\d+$')
}

# 示例数据：
# version: "1.0.0"     → ✅ 匹配
# version: "2.10.5"    → ✅ 匹配
# version: "1.0"       → ❌ 不匹配（缺少补丁版本）
# version: "v1.2.3"    → ❌ 不匹配（有前缀）

场景 8：SQL 注入检测

rule sql_injection_detection {
    # 选择用户输入字段
    | take(user_input)

    # 检测常见的 SQL 注入模式
    | regex_match('(?i)(union|select|insert|update|delete|drop|;|--|\|)')
}

# 示例数据：
# user_input: "SELECT * FROM users"  → ✅ 匹配（检测到）
# user_input: "'; DROP TABLE --"     → ✅ 匹配（检测到）
# user_input: "normal search query"  → ❌ 不匹配（安全）

场景 9：文件扩展名过滤

rule image_file_filter {
    # 选择文件名字段
    | take(filename)

    # 只匹配图片文件
    | regex_match('\.(?i)(jpg|jpeg|png|gif|bmp|svg)$')
}

# 示例数据：
# filename: "photo.jpg"      → ✅ 匹配
# filename: "image.PNG"      → ✅ 匹配（大小写不敏感）
# filename: "document.pdf"   → ❌ 不匹配

场景 10：MAC 地址验证

rule mac_address_validation {
    # 选择 MAC 地址字段
    | take(mac)

    # 匹配 MAC 地址格式（XX:XX:XX:XX:XX:XX）
    | regex_match('^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$')
}

# 示例数据：
# mac: "00:1B:44:11:3A:B7"  → ✅ 匹配
# mac: "AA:BB:CC:DD:EE:FF"  → ✅ 匹配
# mac: "invalid-mac"        → ❌ 不匹配

使用限制

类型限制

regex_match 只能处理字符串类型的字段：

# ✅ 正确 - 字段是字符串
message: "error occurred" -> regex_match('error')

# ❌ 错误 - 字段是数字
status_code: 404 -> regex_match('\d+')  # 会失败

# ❌ 错误 - 字段是 IP 地址（非字符串类型）
ip: 192.168.1.1 -> regex_match('\d+')  # 会失败

性能考虑

1. 正则表达式编译开销：

   • 每次调用都会重新编译正则表达式
   • 复杂的正则表达式编译可能需要几微秒

2. 匹配性能：

   • 简单模式：微秒级
   • 复杂模式（大量回溯）：可能较慢
   • 建议：避免过度复杂的正则表达式

3. 优化建议：

   # ✅ 推荐：简单直接的模式
   regex_match('^\d{4}$')
   
   # ⚠️ 慎用：复杂的回溯模式
   regex_match('^(a+)+b$')  # 可能导致性能问题
   

不支持的特性

1. 不支持命名捕获组：

   # ❌ 不支持（无法提取捕获的内容）
   regex_match('(?P<year>\d{4})')
   

2. 不支持替换：

   # ❌ regex_match 只做匹配，不做替换
   # 需要替换请使用 chars_replace
   

3. 不支持多个模式：

   # ❌ 不能传递多个模式
   regex_match('pattern1', 'pattern2')
   
   # ✅ 使用选择符 |
   regex_match('pattern1|pattern2')
   

完整示例

示例 1：日志分类流水线

rule log_classification {
    # 选择日志消息
    | take(message)

    # 分类为错误日志
    (
        | regex_match('(?i)(error|exception|failed|fatal)')
        | tag(level, ERROR)
    )
    |
    # 或分类为警告日志
    (
        | regex_match('(?i)(warn|warning|deprecated)')
        | tag(level, WARNING)
    )
    |
    # 或分类为普通日志
    (
        | tag(level, INFO)
    )
}

示例 2：安全审计过滤

rule security_audit {
    # 检查用户输入中的危险模式
    | take(user_input)

    # 检测脚本注入
    | regex_match('(?i)(<script|javascript:|onerror=)')

    # 或检测 SQL 注入
    | regex_match('(?i)(union|select.*from|insert.*into)')

    # 或检测路径遍历
    | regex_match('(\.\./|\.\.\\)')

    # 匹配到任何一个就记录为安全事件
    | tag(security_event, true)
}

示例 3：结构化日志解析

rule structured_log_parsing {
    # 验证 JSON 日志格式
    | take(raw_message)
    | regex_match('^\{.*\}$')

    # 验证包含必需字段
    | regex_match('"timestamp":\s*"\d{4}-\d{2}-\d{2}')
    | regex_match('"level":\s*"(INFO|WARN|ERROR)"')
    | regex_match('"message":\s*"[^"]+"')

    # 所有验证通过后继续处理
}

性能说明

• 正则编译：每次调用都会编译，建议使用简单模式
• 匹配速度：
  • 简单模式（如 ^\d+$）：< 1μs
  • 中等复杂度（如邮箱验证）：1-10μs
  • 复杂模式（大量回溯）：可能 > 100μs
• 内存开销：每个正则表达式约 1-10KB

错误处理

常见错误

1. 无效的正则表达式

   错误: regex_match | invalid regex pattern
   原因: 正则表达式语法错误
   解决: 检查正则表达式语法
   

2. 字段不存在

   错误: regex_match | no active field
   原因: 当前没有活动字段
   解决: 使用 take() 先选择字段
   

3. 字段类型不匹配

   错误: regex_match | field is not a string
   原因: 字段不是字符串类型
   解决: 确保字段是 Chars 类型
   

4. 模式不匹配

   错误: regex_match | not matched
   原因: 字段内容不匹配正则表达式
   解决: 这是正常的过滤逻辑
   

与其他函数配合使用

与字段选择器配合

# 先选择字段，再匹配
| take(message)
| regex_match('error')

与条件检查配合

# 组合多个条件
| take(status)
| regex_match('^[45]\d{2}$')  # 4xx 或 5xx

与 chars_replace 配合

# 先匹配，再替换
| regex_match('error')
| chars_replace(error, ERROR)

与分支逻辑配合

# 不同模式走不同分支
(
    | regex_match('^2\d{2}$')  # 2xx
    | tag(status_class, success)
)
|
(
    | regex_match('^4\d{2}$')  # 4xx
    | tag(status_class, client_error)
)

最佳实践

1. 优先使用单引号

# ✅ 推荐
regex_match('^\d+$')

# ❌ 避免（会导致解析错误）
regex_match("^\d+$")

2. 使用锚点明确匹配范围

# ✅ 推荐：完全匹配
regex_match('^\d{4}$')  # 恰好4位数字

# ⚠️ 可能不符合预期：部分匹配
regex_match('\d{4}')    # 包含4位数字即可

3. 简化正则表达式

# ✅ 推荐：简单清晰
regex_match('^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$')

# ⚠️ 过度复杂
regex_match('^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$')

4. 使用注释文档化复杂模式

# 匹配邮箱：用户名@域名.后缀
regex_match('^\w+@\w+\.\w+$')

5. 测试边界情况

# 测试模式的边界
regex_match('^\d{2,4}$')
# 测试：1 ❌, 12 ✅, 123 ✅, 1234 ✅, 12345 ❌

正则表达式测试

在线测试工具

1. regex101.com

   • 选择 Rust flavor
   • 测试你的正则表达式
   • 查看匹配详情和性能

2. regexr.com

   • 可视化匹配过程
   • 提供备忘清单

命令行测试

# 使用 WP-Motor 测试
echo "test_value: 12345" | wp-motor test.wpl

# 查看匹配结果
wp-motor --debug test.wpl < test_data.log

常见问题 (FAQ)

Q1: 为什么必须使用单引号？

因为 WPL 的双引号字符串解析器只支持有限的转义序列（\", \\, \n, \t），而正则表达式需要 \d, \w, \s 等，这些会导致解析失败。

Q2: 如何匹配点号（.）？

# 使用反斜杠转义
regex_match('\.')  # 匹配字面的点号

Q3: 如何实现大小写不敏感匹配？

# 使用 (?i) 标志
regex_match('(?i)error')  # 匹配 error, ERROR, Error

Q4: 正则表达式是完全匹配还是部分匹配？

默认是部分匹配。使用 ^ 和 $ 实现完全匹配：

# 部分匹配
regex_match('\d+')     # "abc123def" → ✅ 匹配

# 完全匹配
regex_match('^\d+$')   # "abc123def" → ❌ 不匹配

Q5: 如何匹配多行文本？

# 使用 (?m) 多行模式
regex_match('(?m)^ERROR')  # 匹配任意行开头的 ERROR

# 使用 (?s) 单行模式让 . 匹配换行符
regex_match('(?s)start.*end')  # 跨行匹配

Q6: 性能如何？

• 简单模式：非常快（微秒级）
• 复杂模式：可能较慢
• 建议：避免过度复杂的回溯模式

Q7: 能否提取匹配的内容？

不支持。regex_match 只做匹配判断，不提取内容。

正则表达式速查表

常用模式

更多资源

• Rust Regex 文档: https://docs.rs/regex/
• 开发指南: docs/guide/wpl_field_func_development_guide.md
• 源代码: crates/wp-lang/src/ast/processor/function.rs
• 测试用例: crates/wp-lang/src/eval/builtins/pipe_fun.rs

版本历史

• 1.13.1 (2026-02-02)
  • 初始实现
  • 支持完整的 Rust regex 语法
  • 支持所有标准正则表达式特性
  • 添加完整的测试覆盖

提示: regex_match 功能强大但也可能影响性能。对于简单的字符串匹配，优先考虑使用 chars_has 或 chars_in；对于数值范围检查，使用 digit_range 或 digit_in。正则表达式适合复杂的模式匹配场景。

digit_range 函数使用指南

概述

digit_range 是 WPL (WP Language) 中的数值范围检查函数，用于判断日志字段的数值是否在指定的单个范围内。这是一个简单高效的闭区间检查函数。

快速开始

基本语法

digit_range(begin, end)

• begin: 范围下界（标量值）
• end: 范围上界（标量值）
• 检查方式：begin <= value <= end（闭区间）

简单示例

# 检查数值是否在 [0, 100] 范围内
digit_range(0, 100)

# 检查 HTTP 成功状态码（200-299）
digit_range(200, 299)

# 检查端口号是否在标准范围内（0-65535）
digit_range(0, 65535)

参数格式

1. 单个范围

检查单个连续范围：

# 检查端口号是否在标准范围内（0-65535）
digit_range(0, 65535)

# 检查 HTTP 成功状态码（200-299）
digit_range(200, 299)

# 检查年龄是否成年（18-150）
digit_range(18, 150)

2. 范围限制说明

注意: 从 1.13.1 版本开始，digit_range 仅支持单个范围检查。如需检查多个不连续的范围，请使用多个规则或分支逻辑（见下文“与分支逻辑配合“部分）。

# ✅ 单个范围检查
digit_range(200, 299)  # 2xx 状态码

# ❌ 不再支持多范围数组语法
# digit_range([200, 300], [299, 399])  # 旧版本语法，已废弃

3. 边界值处理

范围检查是闭区间，包含边界值：

# [100, 200] - 包含 100 和 200
digit_range(100, 200)

# 检查值 100: ✅ 通过（等于下界）
# 检查值 200: ✅ 通过（等于上界）
# 检查值 150: ✅ 通过（在范围内）
# 检查值 99:  ❌ 失败（小于下界）
# 检查值 201: ❌ 失败（大于上界）

4. 负数范围

支持负数范围：

# 温度范围检查（-20°C 到 40°C）
digit_range(-20, 40)

# 海拔范围（死海 -400m 到 珠峰 8848m）
digit_range(-400, 8848)

实际应用场景

场景 1：HTTP 状态码分类

rule http_success_check {
    # 选择状态码字段
    | take(status_code)

    # 检查是否为成功状态码（2xx）
    | digit_range(200, 299)
}

# 示例数据：
# status_code: 200  → ✅ 通过（在 [200,299] 范围内）
# status_code: 204  → ✅ 通过（在 [200,299] 范围内）
# status_code: 301  → ❌ 失败（不在范围内）
# status_code: 404  → ❌ 失败（不在范围内）

# 如需检查多个状态码范围（如 2xx 或 3xx），使用分支逻辑：
rule http_ok_or_redirect {
    | take(status_code)
    | (digit_range(200, 299) | digit_range(300, 399))
}

场景 2：性能指标监控

rule response_time_check {
    # 选择响应时间字段（毫秒）
    | take(response_time)

    # 检查响应时间是否在正常范围（0-500ms）
    | digit_range(0, 500)
}

# 示例数据：
# response_time: 50   → ✅ 通过（快速响应）
# response_time: 200  → ✅ 通过（正常响应）
# response_time: 1000 → ❌ 失败（超时）

场景 3：端口号验证

rule system_port_check {
    # 选择端口字段
    | take(port)

    # 检查是否为系统保留端口（1-1023）
    | digit_range(1, 1023)
}

# 示例数据：
# port: 80    → ✅ 通过（HTTP 默认端口）
# port: 443   → ✅ 通过（HTTPS 默认端口）
# port: 8080  → ❌ 失败（用户端口）

场景 4：时间段过滤

rule morning_hours_check {
    # 选择小时字段
    | take(hour)

    # 检查是否在上午工作时间（9-12）
    | digit_range(9, 12)
}

# 示例数据：
# hour: 10  → ✅ 通过（上午工作时间）
# hour: 11  → ✅ 通过（上午工作时间）
# hour: 15  → ❌ 失败（下午时间）

# 检查多个时间段，使用分支逻辑：
rule business_hours_check {
    | take(hour)
    | (digit_range(9, 12) | digit_range(14, 18))
}

场景 5：年龄分段

rule adult_age_check {
    # 选择年龄字段
    | take(age)

    # 成年人年龄段（18-65）
    | digit_range(18, 65)
}

# 示例数据：
# age: 30  → ✅ 通过（成年人）
# age: 50  → ✅ 通过（成年人）
# age: 15  → ❌ 失败（未成年）
# age: 70  → ❌ 失败（老年人）

场景 6：优先级过滤

rule high_priority_filter {
    # 选择优先级字段
    | take(priority)

    # 只处理高优先级（1-3）
    | digit_range(1, 3)
}

# 示例数据：
# priority: 1  → ✅ 通过（高优先级）
# priority: 3  → ✅ 通过（高优先级）
# priority: 5  → ❌ 失败（中优先级）

场景 7：数据质量检查

rule data_quality_check {
    # 检查温度传感器数据
    | take(temperature)

    # 正常温度范围（-40°C 到 80°C）
    | digit_range(-40, 80)
}

# 示例数据：
# temperature: 25   → ✅ 通过（正常室温）
# temperature: -10  → ✅ 通过（冬季温度）
# temperature: 100  → ❌ 失败（异常数据）
# temperature: -100 → ❌ 失败（传感器故障）

使用限制

类型限制

digit_range 只能处理数值类型的字段：

# ✅ 正确 - 字段是数字
status_code: 200 -> digit_range(200, 299)

# ❌ 错误 - 字段是字符串
level: "200" -> digit_range(200, 299)  # 会失败

# ❌ 错误 - 字段是 IP 地址
ip: 192.168.1.1 -> digit_range(192, 200)  # 会失败

参数要求

1. 参数必须是标量值：

   # ✅ 正确 - 使用标量值
   digit_range(1, 10)
   
   # ❌ 错误 - 不支持数组参数（旧版本语法）
   digit_range([1], [10])  # 已废弃
   

2. 范围下界应小于等于上界：

   # ✅ 正确
   digit_range(1, 10)      # 1 <= x <= 10
   digit_range(10, 10)     # x == 10（单点）
   
   # ⚠️ 逻辑错误（不会匹配任何值）
   digit_range(10, 1)      # 10 <= x <= 1（永远为假）
   

不支持的特性

1. 不支持浮点数精确匹配：

   # ⚠️ 注意：内部使用 i64，浮点数会被舍入
   digit_range(1, 10)  # 只能匹配整数
   

2. 不支持无限范围：

   # ❌ 不支持
   digit_range(0, infinity)  # 没有无限值
   

3. 不支持多范围数组：

   # ❌ 不支持（旧版本语法已废弃）
   digit_range([1, 100], [10, 200])  # 请使用分支逻辑替代
   

完整示例

示例 1：日志严重性过滤

rule log_error_filter {
    # 选择严重性级别字段
    | take(severity)

    # 过滤 ERROR 级别（1-2）
    | digit_range(1, 2)

    # 后续处理...
}

# 日志级别定义：
# 1 = CRITICAL
# 2 = ERROR
# 3 = WARNING
# 4 = WARN
# 5 = INFO
# 6 = DEBUG

示例 2：性能监控组合

rule performance_monitor {
    # 检查响应时间
    | take(response_ms)
    | digit_range(0, 1000)  # 0-1000ms 认为正常

    # 检查状态码
    | take(status)
    | digit_range(200, 299)  # 2xx

    # 两个条件都满足才通过
}

示例 3：时间窗口分析

rule weekday_check {
    # 工作日检查（1=周一, 7=周日）
    | take(day_of_week)
    | digit_range(1, 5)  # 周一到周五

    # 只分析工作日数据
}

性能说明

• 时间复杂度：O(1) - 单次比较
• 空间复杂度：O(1) - 原地检查
• 性能特点：
  • 纳秒级执行时间
  • 简单的整数比较操作
  • 性能极佳，适合高频调用

错误处理

常见错误

1. 字段不存在

   错误: <pipe> | not in range
   原因: 当前没有活动字段
   解决: 使用 take() 先选择字段
   

2. 字段类型不匹配

   错误: <pipe> | not in range
   原因: 字段不是数字类型（Digit）
   解决: 确保字段是数值类型
   

3. 数值不在任何范围内

   错误: <pipe> | not in range
   原因: 字段值不满足任何一个范围条件
   解决: 检查范围设置是否正确