oak-json 0.0.1

High-performance incremental JSON parser for the oak ecosystem with flexible configuration, optimized for data interchange and configuration files.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

# Oak JSON Parser


[![Crates.io](https://img.shields.io/crates/v/oak-json.svg)](https://crates.io/crates/oak-json)
[![Documentation](https://docs.rs/oak-json/badge.svg)](https://docs.rs/oak-json)

High-performance incremental JSON parser for the oak ecosystem with flexible configuration, optimized for data processing and analysis.

## 🎯 Overview


Oak JSON is a robust parser for JSON, designed to handle complete JSON syntax including modern features. Built on the solid foundation of oak-core, it provides both high-level convenience and detailed AST generation for data processing and analysis.

## ✨ Features


- **Complete JSON Syntax**: Supports all JSON features including objects, arrays, primitives
- **Full AST Generation**: Generates comprehensive Abstract Syntax Trees
- **Lexer Support**: Built-in tokenization with proper span information
- **Error Recovery**: Graceful handling of syntax errors with detailed diagnostics

## 🚀 Quick Start


Basic example:

```rust
use oak_core::{Parser, SourceText, parser::session::ParseSession};
use oak_json::{JsonParser, JsonLanguage};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut session = ParseSession::<JsonLanguage>::default();
    let parser = JsonParser::new();
    let source = SourceText::new(r#"
        {
            "name": "Alice",
            "age": 30,
            "skills": ["Rust", "JavaScript", "Python"]
        }
    "#);
    
    let result = parser.parse(&source, &[], &mut session);
    println!("Parsed JSON successfully.");
    Ok(())
}
```

## 📋 Parsing Examples


### Object Parsing

```rust
use oak_core::{Parser, SourceText, parser::session::ParseSession};
use oak_json::{JsonParser, JsonLanguage};

let mut session = ParseSession::<JsonLanguage>::default();
let parser = JsonParser::new();
let source = SourceText::new(r#"{"name": "Alice", "age": 30}"#);

let result = parser.parse(&source, &[], &mut session);
println!("Object parsed successfully.");
```

### Array Parsing

```rust
use oak_core::{Parser, SourceText, parser::session::ParseSession};
use oak_json::{JsonParser, JsonLanguage};

let mut session = ParseSession::<JsonLanguage>::default();
let parser = JsonParser::new();
let source = SourceText::new(r#"[1, 2, 3, 4, 5]"#);

let result = parser.parse(&source, &[], &mut session);
println!("Array parsed successfully.");
```

## 🔧 Advanced Features


### Token-Level Parsing

```rust
use oak_core::{Parser, SourceText, parser::session::ParseSession};
use oak_json::{JsonParser, JsonLanguage};

let mut session = ParseSession::<JsonLanguage>::default();
let parser = JsonParser::new();
let source = SourceText::new(r#"{"key": "value"}"#);
let result = parser.parse(&source, &[], &mut session);
println!("Token parsing completed.");
```

### Error Handling

```rust
use oak_core::{Parser, SourceText, parser::session::ParseSession};
use oak_json::{JsonParser, JsonLanguage};

let mut session = ParseSession::<JsonLanguage>::default();
let parser = JsonParser::new();
let source = SourceText::new(r#"
    {
        "name": "Alice",
        "age": 30,
        "skills": ["Rust", "JavaScript", "Python"
    // Missing closing brace
"#);

let result = parser.parse(&source, &[], &mut session);
if let Some(errors) = result.result.err() {
    println!("Parse errors found: {:?}", errors);
} else {
    println!("Parsed successfully.");
}
```

## 🏗️ AST Structure


The parser generates a comprehensive AST with the following main structures:

- **JsonDocument**: Root container for JSON documents
- **Object**: JSON objects with key-value pairs
- **Array**: JSON arrays with ordered elements
- **Value**: JSON values (string, number, boolean, null)
- **Property**: Object properties with key-value pairs

## 📊 Performance


- **Streaming**: Parse large JSON files without loading entirely into memory
- **Incremental**: Re-parse only changed sections
- **Memory Efficient**: Smart AST node allocation
- **Fast Recovery**: Quick error recovery for better processing

## 🔗 Integration


Oak JSON integrates seamlessly with:

- **Data Processing**: JSON data extraction and transformation
- **Configuration Files**: Parsing application configurations
- **API Integration**: Processing JSON API responses
- **Static Analysis**: JSON schema validation and analysis
- **Code Generation**: Generating code from JSON schemas

## 📚 Examples


Check out the [examples](examples/) directory for comprehensive examples:

- Complete JSON document parsing
- Object and array analysis
- Data transformation
- Integration with development workflows

## 🤝 Contributing


Contributions are welcome! 

Please feel free to submit pull requests at the [project repository](https://github.com/ygg-lang/oaks/tree/dev/examples/oak-json) or open [issues](https://github.com/ygg-lang/oaks/issues).