Rust HJSON处理库deser-hjson的使用指南

介绍

deser-hjson是一个Rust库，用于处理HJSON(人性化JSON)格式的数据。HJSON是JSON的一种更易读、更易写的变体，允许注释、省略引号和多行字符串等特性。

主要特性

• 支持标准的JSON解析和序列化
• 支持HJSON扩展语法(注释、无引号键、多行字符串等)
• 与serde框架无缝集成
• 人性化的错误报告

使用方法

添加依赖

在Cargo.toml中添加依赖：

[dependencies]
deser-hjson = "0.1"
serde = { version = "1.0", features = ["derive"] }

基本示例

反序列化HJSON

use serde::Deserialize;
use deser_hjson::from_str;

#[derive(Debug, Deserialize)]
struct Person {
    name: String,
    age: u8,
    hobbies: Vec<String>,
}

fn main() {
    let hjson_data = r#"
    {
        // 这是一个注释
        name: John Doe  // 键可以不加引号
        age: 30
        hobbies: [
            "reading"
            hiking  // 字符串也可以不加引号(如果没有特殊字符)
            "programming"
        ]
    }"#;

    let person: Person = from_str(hjson_data).unwrap();
    println!("{:?}", person);
}

序列化为HJSON

use serde::Serialize;
use deser_hjson::to_string_pretty;

#[derive(Debug, Serialize)]
struct Person {
    name: String,
    age: u8,
    hobbies: Vec<String>,
}

fn main() {
    let person = Person {
        name: "John Doe".to_string(),
        age: 30,
        hobbies: vec!["reading".to_string(), "hiking".to_string(), "programming".to_string()],
    };

    let hjson = to_string_pretty(&person).unwrap();
    println!("{}", hjson);
}

高级用法

自定义序列化/反序列化

use serde::{Deserialize, Serialize};
use deser_hjson::{from_str, to_string_pretty};

#[derive(Debug, Serialize, Deserialize)]
struct Config {
    #[serde(default = "default_host")]
    host: String,
    port: u16,
    #[serde(skip_serializing_if = "Option::is_none")]
    timeout: Option<u32>,
}

fn default_host() -> String {
    "localhost".to_string()
}

fn main() {
    let config_data = r#"
    {
        // 只指定端口，使用默认主机
        port: 8080
    }"#;

    let config: Config = from_str(config_data).unwrap();
    println!("Config: {:?}", config);
    
    let hjson = to_string_pretty(&config).unwrap();
    println!("HJSON output:\n{}", hjson);
}

处理多行字符串

use serde::{Deserialize, Serialize};
use deser_hjson::{from_str, to_string_pretty};

#[derive(Debug, Serialize, Deserialize)]
struct Article {
    title: String,
    content: String,  // 多行文本
}

fn main() {
    let article_data = r#"
    {
        title: My First Article
        content: '''
            这是文章的第一段。
            
            这是第二段，可以包含多行内容。
            甚至包含"引号"也不需要转义。
        '''
    }"#;

    let article: Article = from_str(article_data).unwrap();
    println!("Article: {:?}", article);
}

完整示例

下面是一个完整的配置管理示例，展示了如何使用deser-hjson读取和写入配置文件：

use serde::{Deserialize, Serialize};
use deser_hjson::{from_str, to_string_pretty};
use std::fs;

#[derive(Debug, Serialize, Deserialize)]
struct AppConfig {
    #[serde(default = "default_app_name")]
    app_name: String,
    debug_mode: bool,
    server: ServerConfig,
    features: Vec<String>,
}

#[derive(Debug, Serialize, Deserialize)]
struct ServerConfig {
    host: String,
    port: u16,
    #[serde(default = "default_timeout")]
    timeout: u32,
}

fn default_app_name() -> String {
    "MyApp".to_string()
}

fn default_timeout() -> u32 {
    30
}

fn main() {
    // 示例HJSON配置文件
    let config_data = r#"
    {
        // 应用配置
        debug_mode: true
        server: {
            host: 127.0.0.1
            port: 8080
            // 使用默认timeout
        }
        features: [
            logging
            auth
            "data-processing"  // 包含连字符需要引号
        ]
    }"#;

    // 解析配置
    let config: AppConfig = from_str(config_data).unwrap();
    println!("Loaded config: {:#?}", config);

    // 修改配置
    let mut config = config;
    config.server.port = 9090;
    config.features.push("caching".to_string());

    // 保存配置
    let updated_config = to_string_pretty(&config).unwrap();
    fs::write("config.hjson", &updated_config).unwrap();
    println!("Saved updated config:\n{}", updated_config);
}

注意事项

1. HJSON比标准JSON更宽松，但在与标准JSON系统交互时可能需要转换
2. 无引号的键和字符串在包含特殊字符时需要加引号
3. 注释在序列化时不会被保留

deser-hjson库为需要更人性化配置格式的Rust应用程序提供了很好的支持，特别适合配置文件、文档等场景。