Jaesve

一个纯 Rust 编写的 CLI 工具，用于将 stdin 和/或文件中的 JSON 对象流转换为一系列 CSV 值，并输出到 stdout 或文件。

安装

• 安装 rust
  1. 从 cargo 安装
     • cargoinstall jaesve
  2. 从仓库安装
     • 运行 rustup default stable
     • 运行 git clone https://github.com/bazaah/jaesve.git; cd jaesve
     • 运行 cargo run --release
     • 二进制文件可以在 target/release/ 中找到

CLI

Jaesve 配备了 CLI，由 clap.rs 提供。您可以输入 -h 或 --help 查看可用设置，或浏览以下完整列表。

标志

• -h --help 显示帮助（使用 --help 显示更详细的消息）
• -V --version 显示版本信息
• -a --append 追加到输出文件，而不是覆盖
• -q --quiet 静音错误消息
• -v 调试信息的详细程度
  • 最大：3

选项

• -o --output 设置要写入的输出文件
  • 默认：stdout
• -l --line 将 stdin 设置为从每行读取一个 JSON 文档，并从该行开始处理
  • 默认：0
• -E --regex 设置正则表达式以过滤输出
• -c --column 设置字段以匹配正则表达式
  • 可能值： ident, jptr, type, value, jmes
• -f --format 用点 '.' 分隔的字段列表，描述输出格式
  • 默认值： ident.jptr.type.value
  • 可能值： ident, jptr, type, value, jmes, all
• -d --delim 设置输出字段之间的分隔符
  • 默认值： ,
• -g --guard 设置字段引用字符
  • 默认值： "

子命令

• config 配置各种程序内嵌特性
  • 这些参数是不稳定的，未来可能会更改
  • config --help 查看当前列表
• completions 自动补全脚本生成器
  • completions[FILE] -- <SHELL>
    • 如果没有指定 FILE，则默认为标准输出
    • 可能 SHELL： bash, zsh, fish

参数

• 一个空格分隔的有效文件路径列表，其中 - 代表 stdin。如果你想在 Arg 后添加标志和选项，你必须以 - 结尾。
  • 例如
    • jaesve--quiet--append-o output.csv input1 input2-input4//这是快乐的
    • jaesve input1 input2-input4--quiet--append-o output.csv//这是悲伤的
    • jaesve input1 input2-input4: --quiet--append-o output.csv//这是快乐的

持久参数

上述标志和选项的子集可以通过环境变量或配置文件设置。如下所示

• debug (--v)
• quiet
• append
• line
• delim
• guard
• format
• buf_in
• buf_out
• linereader_eol
• factor

它们期望与 CLI 变体相同的输入类型，带有标志（例如 quiet）采用常见的布尔表示形式 - 例如 true、No、1 等。

当从多个来源提供变量时，程序将按以下顺序优先级排序：（从高到低）

1. CLI
2. 环境
3. $HOME/jaesve.conf
4. $CONFIG/jaesve.conf
5. /etc/jaesve.conf （如果是在 *nix 上）
6. 默认 （如果有）

环境

程序将检查格式为 JAESVE_<VAR_NAME> 的变量。

文件

默认情况下配置文件是禁用的，如果您想使用它们，请在您的cargo install/build命令中添加--features=config-file。期望的格式是TOML，下面是一个示例文件。

quiet = false
delim = ","

# Note this corresponds to the 'config' CLI subcommand
[config]
factor = "K"

性能

速度

在初步测试中，它在3分钟内解析了2G的JSON。

内存

Jaesve被编写为最小化内存使用。它使用基于流的解析JSON的方法，并尝试展开嵌套对象。其最大内存占用可以描述如下：

• sizeof最大对象/数组 +
• sizeof组合元素NOT不包括任何对象/从文档开始到最大对象/数组 +
• 程序开销

TLDR：嵌套越深、对象/数组越大，内存占用就越大。

示例用法

作为一个简单的示例，让我们使用以下JSON：

//sample.json
{
  "aliceblue": "#f0f8ff",
  "antiquewhite": "#faebd7",
  "azure": "#f0ffff",
  "beige": "#f5f5dc",
  "black": "#000000",
  "blanchedalmond": "#ffebcd",
  "gradient": {
    "blues": ["#0000f0", "#0000f1", "#0000f2"],
    "green": "#00ff00"
  }
}

运行jaesve sample.json会打印出：

"1","/gradient/blues/0","String","#0000f0"
"1","/gradient/blues/1","String","#0000f1"
"1","/gradient/blues/2","String","#0000f2"
"1","/gradient/green","String","#00ff00"
"1","/gradient/blues","Array",""
"1","/aliceblue","String","#f0f8ff"
"1","/antiquewhite","String","#faebd7"
"1","/azure","String","#f0ffff"
"1","/beige","String","#f5f5dc"
"1","/black","String","#000000"
"1","/blanchedalmond","String","#ffebcd"
"1","/gradient","Object",""

其中

• "INTEGER"表示值来自哪个输入源
• "/.../..."是该记录的json pointer
• "JSON TYPE"是记录类型
• VALUE是与该记录关联的值，如果它是一个端点即不是对象或数组

错误

除非设置--quiet并使用-v、-vv和-vvv进行信息提升，否则Jaesve会将任何错误打印到stderr。

它将在以下条件下出错

1. JSON对象格式不正确/包含无效的Unicode点
2. 无法从输入文件中读取
3. 无法创建输出文件（它不会创建目录）
4. 无法写入输出

错误

上述错误预计将由用户处理，如果出现其他错误，它们被认为是错误，如果您愿意，请提供一个描述错误以及您收到的错误信息的issue。