🦀 rson-core

Core parsing and value types for RSON (Rust Serialized Object Notation)

🎯 What is rson-core?

rson-core is the foundational library for RSON (Rust Serialized Object Notation) - a human-readable data format that extends JSON with rich types, comments, and better developer experience.

This crate provides:

• RSON value types - Structs, enums, options, tuples
• Low-level parsing - Tokenization and AST construction
• Core utilities - Validation, formatting, conversion

🚀 Quick Start

Installation

[dependencies]
rson-core = "1.0.0"

Basic Usage

use rson_core::{RsonValue, parse_rson_value};

// Parse RSON text into value types
let rson_text = r#"
    User(
        id: 123,
        name: "John Doe",
        email: Some("john@example.com"),
        roles: ["admin", "user"],
    )
"#;

let value: RsonValue = parse_rson_value(rson_text)?;

// Work with the parsed value
match value {
    RsonValue::Struct(name, fields) => {
        println!("Struct: {}", name);
        for (key, val) in fields {
            println!("  {}: {:?}", key, val);
        }
    }
    _ => {}
}

📚 Core Types

RsonValue Enum

pub enum RsonValue {
    Null,
    Bool(bool),
    Number(f64),
    String(String),
    Array(Vec<RsonValue>),
    Object(IndexMap<String, RsonValue>),
    Struct(String, IndexMap<String, RsonValue>),
    Enum(String, Option<Box<RsonValue>>),
    Option(Option<Box<RsonValue>>),
    Tuple(Vec<RsonValue>),
}

Parsing Functions

use rson_core::{parse_rson_value, parse_rson_tokens};

// Parse complete RSON value
let value = parse_rson_value(text)?;

// Tokenize RSON text
let tokens = parse_rson_tokens(text)?;

Validation

use rson_core::validate_rson;

// Quick validation without full parsing
let is_valid = validate_rson(rson_text);

🎨 RSON Syntax Examples

Structs

User(
    id: 123,
    name: "John",
    active: true,
)

Enums

Status::Active
Result::Ok("success")
Color::RGB(255, 128, 0)

Options

Some("value")
None

Comments

// Line comment
Config(
    /* Block comment */
    name: "app",
    debug: true, // Trailing comma OK
)

🔧 Advanced Usage

Custom Parsing

use rson_core::{RsonParser, ParserConfig};

let config = ParserConfig {
    allow_comments: true,
    allow_trailing_commas: true,
    strict_mode: false,
};

let parser = RsonParser::with_config(config);
let value = parser.parse(rson_text)?;

Value Manipulation

use rson_core::RsonValue;

let mut value = RsonValue::Object(Default::default());

// Add fields to object
if let RsonValue::Object(ref mut map) = value {
    map.insert("name".to_string(), RsonValue::String("test".to_string()));
    map.insert("version".to_string(), RsonValue::Number(1.0));
}

Serialization

use rson_core::to_rson_string;

let value = RsonValue::Struct(
    "Config".to_string(),
    [("name".to_string(), RsonValue::String("app".to_string()))]
        .into_iter().collect()
);

let rson_text = to_rson_string(&value)?;
println!("{}", rson_text);
// Output: Config(name: "app")

🌍 Integration with Other Crates

With serde_rson

// For high-level Serde integration, use serde_rson
use serde_rson;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct MyStruct {
    field: String,
}

With rson-schema

// For schema validation
use rson_schema::validate_against_schema;

🎯 When to Use rson-core

Use rson-core when:

• Building custom RSON parsers or tools
• Need low-level access to RSON AST
• Creating language bindings for RSON
• Implementing custom serialization logic

Use serde_rson when:

• Working with Rust structs and enums
• Need high-level serialization/deserialization
• Building typical Rust applications

📖 Documentation

• API Documentation - Complete API reference
• RSON Specification - Language specification
• Examples - Usage examples

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Areas we need help with:

• Performance optimizations
• Additional parsing features
• Better error messages
• Documentation improvements

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• serde_rson - Serde integration for RSON
• rson-cli - Command-line tools
• rson-schema - Schema validation
• RSON Website - Documentation and playground

Made with 🦀 by the RSON community