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 转义支持

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