rson-core 1.0.0

# 🦀 rson-core

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

[![Crates.io](https://img.shields.io/crates/v/rson-core.svg)](https://crates.io/crates/rson-core)
[![Documentation](https://docs.rs/rson-core/badge.svg)](https://docs.rs/rson-core)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

---

## 🎯 **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

```toml
[dependencies]
rson-core = "1.0.0"
```

### Basic Usage

```rust
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**

```rust
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**

```rust
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**

```rust
use rson_core::validate_rson;

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

---

## 🎨 **RSON Syntax Examples**

### **Structs**
```rson
User(
    id: 123,
    name: "John",
    active: true,
)
```

### **Enums** 
```rson
Status::Active
Result::Ok("success")
Color::RGB(255, 128, 0)
```

### **Options**
```rson
Some("value")
None
```

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

---

## 🔧 **Advanced Usage**

### **Custom Parsing**

```rust
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**

```rust
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**

```rust
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**
```rust
// 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**
```rust
// 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](https://docs.rs/rson-core)** - Complete API reference
- **[RSON Specification](https://rson.org/docs/spec)** - Language specification
- **[Examples](https://github.com/RSON-Rust-Serialized-Object-Notation/RSON-core/tree/main/rson-core/examples)** - Usage examples

---

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guide](https://github.com/RSON-Rust-Serialized-Object-Notation/RSON-core/blob/main/CONTRIBUTING.md).

**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](LICENSE) file for details.

---

## 🔗 **Related Projects**

- **[serde_rson](https://crates.io/crates/serde_rson)** - Serde integration for RSON
- **[rson-cli](https://crates.io/crates/rson-cli)** - Command-line tools
- **[rson-schema](https://crates.io/crates/rson-schema)** - Schema validation
- **[RSON Website](https://rson.org)** - Documentation and playground

---

**Made with 🦀 by the RSON community**