XQPath

A jq-inspired expression parser and evaluator for structured data in Rust

🎯 概述

XQPath 是一个用于结构化数据（JSON/YAML）路径提取与操作的高性能 Rust 工具，提供 jq 风格的表达式语法。

双重形态

• Rust 库：嵌入到 Rust 项目中使用
• 命令行工具：处理文件和管道数据

✨ 主要特性

• 路径提取：支持 .field、[index]、*、** 等路径语法
• 管道操作：expr1 | expr2 管道操作符
• 逗号操作：expr1, expr2 多路选择
• 内置函数：length(), keys(), map(), select(), sort_by() 等
• 条件表达式：if-then-else 条件判断
• 比较与逻辑：==, !=, >, <, and, or, not
• 错误处理：try-catch 表达式和 ? 操作符
• 字面量：支持字符串、数字、数组、对象字面量

🚀 快速开始

安装

[dependencies]
xqpath = "1.2.1"

基本用法

use xqpath::{parse_path_expression, evaluate_path_expression};
use serde_json::json;

let data = json!({
    "users": [
        {"name": "Alice", "age": 30, "active": true},
        {"name": "Bob", "age": 25, "active": false}
    ]
});

// 基本路径提取
let expr = parse_path_expression(".users[0].name")?;
let result = evaluate_path_expression(&expr, &data)?;
// 结果: ["Alice"]

// 管道操作
let expr = parse_path_expression(".users | length()")?;
let result = evaluate_path_expression(&expr, &data)?;
// 结果: [2]

// 条件过滤
let expr = parse_path_expression(".users | select(.active) | map(.name)")?;
let result = evaluate_path_expression(&expr, &data)?;
// 结果: [["Alice"]]

// 条件表达式
let expr = parse_path_expression("
    .users | map(if .age >= 30 then \"senior\" else \"junior\" end)
")?;
let result = evaluate_path_expression(&expr, &data)?;
// 结果: [["senior", "junior"]]

📖 表达式语法

路径语法

• .field - 字段访问
• [0] - 数组索引
• [*] - 数组通配符
• ** - 递归通配符

操作符

• | - 管道：将左侧结果传递给右侧
• , - 逗号：收集多个表达式结果
• ==, !=, >, <, >=, <= - 比较操作符
• and, or, not - 逻辑操作符

内置函数

• length() - 获取数组长度
• keys() - 获取对象键名
• type() - 获取值类型
• map(expr) - 数组映射
• select(condition) - 条件过滤
• sort(), sort_by(expr) - 排序
• unique(), reverse() - 数组操作

条件与错误处理

# 条件表达式
if condition then expr1 else expr2 end

# 错误处理
try expr catch fallback
expr?  # 可选操作符

🖥️ 命令行工具

# 安装命令行工具
cargo install xqpath

# 基本用法
echo '{"name": "Alice", "age": 30}' | xqpath '.name'

# 从文件读取
xqpath '.users | length()' data.json

# 复杂查询
cat data.json | xqpath '.users | select(.active) | map(.name)'

🔧 高级用法

复杂数据处理

let expr = parse_path_expression("
    .orders
    | select(.status == \"completed\")
    | group_by(.customer_id)
    | map({
        customer: .[0].customer_id,
        total: map(.amount) | add,
        count: length()
      })
    | sort_by(.total)
    | reverse()
")?;

错误处理

let expr = parse_path_expression("
    try .config.database.url 
    catch \"sqlite://default.db\"
")?;

📚 文档

• 完整文档 - 详细的 API 文档和指南
• 功能示例 - 各种使用示例
• 开发路线图 - 项目发展计划

🤝 贡献

我们欢迎各种形式的贡献！请查看 文档目录 了解项目详情。

📄 许可证

本项目采用 Apache-2.0 许可证。

设计理念: XQPath 致力于提供简单、高效、可扩展的结构化数据处理体验，无论是在命令行环境还是 Rust 应用程序中。