paulc/struct-cli

# struct-cli 通过命令行或 Rust 代码打包和解包二进制结构体。 ## 字段类型 运行 `struct-cli types` 获取完整参考。摘要： | 类型 | 描述 | |------|-------------| | `u8`/`u16`/`u32`/`u64`/`u128` | 无符号整数 | | `i8`/`i16`/`i32`/`i64`/`i128` | 有符号整数 | | `bool` | 1 字节布尔值 (0=false，非零=true) | | `b1`..`b7` | N 位的位域，在一个字节内按 MSB 优先打包 | | `sN` | 固定长度为 N 字节的 UTF-8 字符串，零填充 | | `s` | 无界 UTF-8 字符串，消耗剩余的所有输入 | | `p` | Pascal 字符串：1 字节长度前缀 + 数据（最大 255 字节） | | `xN` | 恰好为 N 字节的原始字节，以十六进制编码 | | `x` | 无界原始字节，消耗剩余的所有输入 | ## 字节序 所有数字类型默认为**小端序（little-endian）**。在类型前加上 `>` 前缀表示大端序，或加上 `<` 表示显式的小端序。 ``` u16 little-endian (default) >u16 big-endian [] Pack and unpack binary structs. Options: --dump-json print effective parameters as JSON and exit without executing --help, help display usage information Commands: decode Decode binary data into typed fields. encode Encode typed fields into binary data. run Execute encode or decode using a saved JSON config file. types Show supported field types and value syntax. ``` ### decode ``` Usage: struct-cli decode [-t ] [--types-json ] [-x ] [-n ] [--stdin-hex] [-o

] [-d ] Decode binary data into typed fields. Options: -t, --types struct definition: comma-separated types (e.g. u8,>u16,s8) --types-json struct definition as JSON array (e.g. '["u8",">u16","s8"]') -x, --hex hex-encoded input bytes on the command line -n, --numeric numeric value with type prefix (e.g. u64::123456) --stdin-hex read hex-encoded bytes from stdin instead of raw bytes -o, --output output format: delimited (default), json, json-detailed -d, --delimiter field delimiter for delimited output (default: ,) --help, help display usage information ``` 输入优先级：`-x`（十六进制字符串） > `-n`（数字） > stdin（默认为原始数据，使用 `--stdin-hex` 时为十六进制）。 输出格式： - `delimited` - 以分隔符分隔的值（默认为 `,`） - `json` - 字符串 JSON 数组 - `json-detailed` - 包含 `{"type": ..., "value": ...}` 对象的 JSON 数组 ### encode ``` Usage: struct-cli encode [-t ] [--types-json ] [-v ] [--values-json ] [-f ] [--fields-json ] [--stdin-values] [--stdin-format ] [--stdin-delimiter ] [-o

] Encode typed fields into binary data. Options: -t, --types struct definition: comma-separated types --types-json struct definition as JSON array -v, --values values as comma-separated list (positional match to types) --values-json values as JSON array of strings -f, --fields merged type::value pairs, comma-separated (e.g. u8::42,>u16::1000) --fields-json merged fields as JSON: array of {"type":...,"value":...} or {"types":[...],"values":[...]} --stdin-values read values from stdin (requires -t/--types or --types-json) --stdin-format stdin values format: delimited (default) or json --stdin-delimiter delimiter for delimited stdin values (default: ,) -o, --output output format: hex (default), raw, u8, u16, u32, u64, u128 --help, help display usage information ``` 输入优先级：`--fields-json` > `-f`（合并字段） > `-t`/`-v`（分离的类型+值）。 注意：`-f` 合并格式使用逗号分隔字段。包含逗号的字符串值需要改用 `-t`/`-v` 或 `--fields-json`。 输出格式： - `hex` - 输出到 stdout 的大写十六进制（默认） - `raw` - 输出到 stdout 的原始字节 - `u8`/`u16`/`u32`/`u64`/`u128` - 将字节解释为小端序并打印十进制数值 ### types ``` struct-cli types ``` 打印所有支持的字段类型及其值语法的参考。 ### run ``` Usage: struct-cli run ``` 读取 JSON 配置文件并执行其所描述的 encode 或 decode 操作。配置文件必须包含一个设置为 `"encode"` 或 `"decode"` 的 `mode` 字段。 ## JSON 配置 使用 `--dump-json` 从任何命令生成配置文件（这是一个必须出现在子命令之前的根级别标志）： ``` struct-cli --dump-json decode -t "u8,>u16,bool" -x "2A03E801" -o json > my-struct.json ``` ``` { "mode": "decode", "types": ["u8", ">u16", "bool"], "hex_data": "2A03E801", "output": "json", "delimiter": "," } ``` 然后直接运行它： ``` struct-cli run my-struct.json ``` `--dump-json` 也可以与 `run` 一起使用，以便在执行前检查加载的配置： ``` struct-cli --dump-json run my-struct.json ``` 配置文件的键包括：`mode`、`types`、`values`、`fields`、`stdin_values`、`stdin_format`、`stdin_delimiter`、`input`、`hex_data`、`numeric`、`output`、`delimiter`、`encode_output`。 一个完整的 encode 配置示例： ``` { "mode": "encode", "types": ["u8", ">u16", "bool"], "values": ["42", "1000", "true"], "encode_output": "hex" } ``` ## 示例 ### Encode 合并的 type::value 格式： ``` struct-cli encode -f "u8::42,u16::1000,bool::true" # 2AE80301 ``` 分离的类型和值： ``` struct-cli encode -t "u8,u16,bool" -v "42,1000,true" # 2AE80301 ``` 大端序字段： ``` struct-cli encode -f "u8::42,>u16::1000,bool::true" # 2A03E801 ``` 混合字节序： ``` struct-cli encode -f "u16::1,>u16::1" # 01000100 ``` 来自 stdin 的值： ``` echo "42,1000,true" | struct-cli encode -t "u8,u16,bool" --stdin-values printf "42\n1000\ntrue" | struct-cli encode -t "u8,u16,bool" --stdin-values --stdin-delimiter '\n' echo '["42","1000","true"]' | struct-cli encode -t "u8,u16,bool" --stdin-values --stdin-format json ``` JSON 字段输入： ``` struct-cli encode --fields-json '[{"type":"u8","value":"42"},{"type":">u16","value":"1000"}]' struct-cli encode --fields-json '{"types":["u8",">u16"],"values":["42","1000"]}' ``` 数字输出： ``` struct-cli encode -f "u32::305419896" -o u32 # 305419896 ``` ### Decode 从命令行的十六进制输入： ``` struct-cli decode -t "u8,u16,bool" -x "2AE80301" # 42,1000,true struct-cli decode -t "u8,>u16,bool" -x "2A03E801" # 42,1000,true ``` 自定义分隔符： ``` struct-cli decode -t "u8,u16,bool" -x "2AE80301" -d "|" # 42|1000|true ``` JSON 输出： ``` struct-cli decode -t "u8,u16,bool" -x "2AE80301" -o json # ["42","1000","true"] struct-cli decode -t "u8,u16,bool" -x "2AE80301" -o json-detailed # [{"type":"u8","value":"42"},{"type":"u16","value":"1000"},{"type":"bool","value":"true"}] ``` 来自 stdin 的十六进制： ``` echo "2AE80301" | struct-cli decode -t "u8,u16,bool" --stdin-hex ``` 来自 stdin 的原始字节（通过管道从 encode 传入）： ``` struct-cli encode -f "u8::42,u16::1000" | struct-cli decode -t "u8,u16" # 42,1000 ``` 数字输入： ``` struct-cli decode -t "u32" -n "u32::305419896" # 305419896 ``` ### 位域 位域在一个字节内按 MSB 优先打包。连续的位域总位数必须等于或少于 8 位。 ``` struct-cli encode -f "b4::1010,b4::0101" # A5 struct-cli decode -t "b4,b4" -x "A5" # 1010,0101 struct-cli encode -f "b3::101,b2::11,b3::010" # BA struct-cli decode -t "b3,b2,b3" -x "BA" # 101,11,010 ``` ### 字符串 ``` # 定长字符串（零填充至 8 字节） struct-cli encode -f "s8::hello" struct-cli decode -t "s8" -x "68656C6C6F000000" # hello # Pascal 字符串 struct-cli encode -f "p::hello world" struct-cli decode -t "p" -x "0B68656C6C6F20776F726C64" # hello world # 有符号整数和剩余字符串 struct-cli encode -f "i16::-1234,s::payload data" struct-cli decode -t "i16,s" -x "2EFBCE7061796C6F61642064617461" # -1234,payload data ``` ### 十六进制字节 ``` struct-cli encode -f "x4::DEADBEEF" # DEADBEEF struct-cli decode -t "x4" -x "DEADBEEF" # DEADBEEF # 末尾无限长 hex struct-cli encode -f "u8::1,x::CAFEBABE" struct-cli decode -t "u8,x" -x "01CAFEBABE" # 1,CAFEBABE ``` ## Library API 添加到 `Cargo.toml`： ``` [dependencies] struct-cli = { path = "..." } ``` 核心函数： ``` use struct_cli::{encode_fields, decode_fields, parse_type_list, DecodeResult}; // Encode let types = parse_type_list("u8,>u16,bool").unwrap(); let values = vec!["42".to_string(), "1000".to_string(), "true".to_string()]; let bytes: Vec = encode_fields(&types, &values).unwrap(); // Decode let results: Vec = decode_fields(&types, &bytes).unwrap(); for r in &results { println!("{}: {}", r.type_name, r.value); } ``` 请参阅 `cargo doc --open` 获取完整的 API 文档。

标签：Rust, 二进制数据处理, 可视化界面, 底层开发工具, 数据序列化, 数据解析, 文档结构分析, 网络流量审计, 通知系统