# WPL Field Functions 函数索引
本文档列出了 WP-Motor WPL 语言中所有可用的 field function（字段函数）。
## 字段选择函数 (Field Selectors)
| `take` | `take(field_name)` | 选择指定名称的字段作为活动字段 | - |
| `last` | `last()` | 选择最后一个字段作为活动字段 | - |
## 字符串匹配函数 (String Matching)
| `chars_has` | `chars_has(value)` | 检查字符串字段是否等于指定值 | - |
| `chars_not_has` | `chars_not_has(value)` | 检查字符串字段是否不等于指定值 | - |
| `chars_in` | `chars_in([value1, value2, ...])` | 检查字符串字段是否在值列表中 | - |
| `f_chars_has` | `f_chars_has(target, value)` | 检查指定字段是否等于指定值 | - |
| `f_chars_not_has` | `f_chars_not_has(target, value)` | 检查指定字段是否不等于指定值 | - |
| `f_chars_in` | `f_chars_in(target, [values])` | 检查指定字段是否在值列表中 | - |
| `starts_with` | `starts_with('prefix')` | 检查字符串是否以指定前缀开始，否则转为 ignore | [📖 详细文档](./starts_with.md) |
| `regex_match` | `regex_match('pattern')` | 使用正则表达式匹配字符串字段 | [📖 详细文档](./regex_match.md) |
## 数值匹配函数 (Numeric Matching)
| `digit_has` | `digit_has(value)` | 检查数值字段是否等于指定值 | - |
| `digit_in` | `digit_in([value1, value2, ...])` | 检查数值字段是否在值列表中 | - |
| `digit_range` | `digit_range(begin, end)` | 检查数值是否在指定范围内（闭区间） | [📖 详细文档](./digit_range.md) |
| `f_digit_has` | `f_digit_has(target, value)` | 检查指定字段是否等于指定数值 | - |
| `f_digit_in` | `f_digit_in(target, [values])` | 检查指定字段是否在数值列表中 | - |
## IP 地址匹配函数 (IP Matching)
| `ip_in` | `ip_in([ip1, ip2, ...])` | 检查 IP 地址是否在列表中 | - |
| `f_ip_in` | `f_ip_in(target, [ips])` | 检查指定字段的 IP 地址是否在列表中 | - |
## 字段存在性检查 (Field Existence)
| `has` | `has()` | 检查当前活动字段是否存在 | - |
| `f_has` | `f_has(target)` | 检查指定字段是否存在 | - |
## 包装函数 (Wrapper Functions)
| `not` | `not(inner_function)` | 反转（取反）内部管道函数的成功/失败结果 | [📖 详细文档](./not.md) |
## 字符串转换函数 (String Transformation)
| `json_unescape` | `json_unescape()` | 解码 JSON 转义字符（`\n`, `\t`, `\"`, `\\` 等） | - |
| `base64_decode` | `base64_decode()` | Base64 解码字符串字段 | - |
| `chars_replace` | `chars_replace(target, replacement)` | 替换字符串中的子串 | [📖 详细文档](./chars_replace.md) |
## 函数分类总览
### 按功能分类
#### 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`
## 使用示例
### 基本流水线
```wpl
rule example_pipeline {
# 1. 选择字段
| take(message)
# 2. 检查条件
| chars_has(error)
# 3. 转换处理
| chars_replace(error, ERROR)
}
```
### 复杂条件组合
```wpl
rule complex_filter {
# 检查状态码范围
| take(status)
| digit_range(200, 299) # 2xx 成功状态码
# 检查消息内容
| take(message)
| regex_match('(?i)(success|ok|complete)')
}
```
### 分支逻辑
```wpl
rule branching_logic {
# 分支 1：错误日志
(
| take(level)
| chars_in([ERROR, FATAL])
)
|
# 分支 2：警告日志
(
| take(level)
| chars_in([WARN, WARNING])
)
}
```
## 性能参考
| 字段选择 | < 100ns | 极快，基于索引查找 |
| 字符串匹配 | < 1μs | 简单字符串比较 |
| 数值匹配 | < 100ns | 简单数值比较 |
| 范围检查 | < 500ns | 线性扫描多个范围 |
| 正则匹配 | 1-100μs | 取决于模式复杂度 |
| Base64 解码 | 1-10μs | 取决于字符串长度 |
| 字符串替换 | 1-10μs | 取决于字符串长度 |
## 最佳实践
### 1. 合理使用函数类型
```wpl
# ✅ 推荐：简单匹配使用 chars_has
| chars_has(error)
# ⚠️ 过度使用：简单匹配不需要正则
| regex_match('^error$') # 性能较差
```
### 2. 优先使用专用函数
```wpl
# ✅ 推荐：数值范围使用 digit_range
| digit_range(200, 299)
# ⚠️ 不推荐：用正则匹配数字
| regex_match('^2\d{2}$') # 性能较差
```
### 3. 先选择字段再处理
```wpl
# ✅ 正确
| take(message)
| chars_replace(old, new)
# ❌ 错误：没有活动字段
| chars_replace(old, new) # 会失败
```
### 4. 组合使用条件函数
```wpl
# ✅ 推荐：先用简单条件过滤，再用复杂条件
| chars_has(error) # 快速过滤
| regex_match('error:\d+') # 精确匹配
```
## 函数对比
### chars_has vs regex_match
| 用途 | 精确字符串匹配 | 模式匹配 |
| 性能 | 极快 | 相对较慢 |
| 灵活性 | 低 | 高 |
| 适用场景 | 已知固定值 | 复杂模式 |
```wpl
# 简单匹配：使用 chars_has
| chars_has(ERROR)
# 复杂匹配：使用 regex_match
| regex_match('(?i)error:\s*\d+')
```
### digit_in vs digit_range
| 用途 | 离散值检查 | 范围检查 |
| 参数 | 值列表 | 范围列表 |
| 适用场景 | 特定值（如状态码） | 连续范围 |
```wpl
# 离散值：使用 digit_in
| digit_in([200, 404, 500])
# 连续范围：使用 digit_range
| digit_range(200, 299)
```
### 目标字段函数 vs 活动字段函数
| 前缀 | 无 | `f_` |
| 字段选择 | 需要先 take | 自动选择 |
| 性能 | 稍快 | 稍慢（需查找） |
| 便利性 | 需要额外步骤 | 一步到位 |
```wpl
# 活动字段函数
| take(status)
| digit_has(200)
# 目标字段函数（更简洁）
| f_digit_has(status, 200)
```
## 相关文档
- **开发指南**: [WPL Field Function 开发指南](../../guide/wpl_field_func_development_guide.md)
- **字段引用**: [Field Reference](./field_reference.md)
- **分隔符**: [Separator Guide](./separator.md)
## 版本历史
- **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 转义支持
---
**提示**: 选择合适的函数类型可以显著提升性能。优先使用简单的专用函数，仅在需要复杂模式匹配时使用正则表达式。