layout: default
Usage Guide
This guide provides in-depth examples for using zzson
in Rust and JavaScript/WebAssembly.
Basic Parsing (Rust)
The simplest way to use zzson is with the parse
function:
use zzson::parse;
fn main() {
let json_data = r#"{ key: "value", num: 123, // comment\n trailing: [1,2,3,], hex: 0xFF }"#;
let value = parse(json_data).unwrap();
println!("{:?}", value);
}
Customizing Parsing with ParserOptions
For more control, use parse_with_options
and configure ParserOptions
:
use zzson::{parse_with_options, ParserOptions};
fn main() {
let input = "a:1, b:2";
let options = ParserOptions {
allow_comments: true,
allow_unquoted_keys: true,
allow_trailing_commas: true,
allow_implicit_top_level: true,
allow_newline_as_comma: true,
allow_single_quoted_strings: true,
allow_extended_numbers: true,
..Default::default()
};
let value = parse_with_options(input, &options).unwrap();
println!("{:?}", value);
}
WebAssembly/JavaScript Usage
See docs/wasm.md for full API details.
import init, { parse_json_with_options } from './pkg/zzson.js';
await init();
const result = parse_json_with_options('{a:1}', { allow_comments: true });
console.log(result); // { a: 1 }
} } ```
Customizing Parsing with ParserOptions
For more control over the parsing behavior, you can use parse_with_options
and configure ParserOptions
.
use zzson::{parse_with_options, ParserOptions};
fn main() {
// Example: Strict JSON parsing (disabling all forgiving features)
let mut strict_options = ParserOptions::default();
strict_options.allow_comments = false;
strict_options.allow_trailing_commas = false;
strict_options.allow_unquoted_keys = false;
strict_options.allow_single_quotes = false;
strict_options.implicit_top_level = false;
strict_options.newline_as_comma = false;
let strict_json = r#"{"key": "value"}"#;
match parse_with_options(strict_json, strict_options) {
Ok(value) => println!("Parsed strictly: {:?}", value),
Err(e) => eprintln!("Strict parsing error: {}", e),
}
// Example: Allowing only unquoted keys and implicit top-level
let mut custom_options = ParserOptions::default();
custom_options.allow_unquoted_keys = true;
custom_options.implicit_top_level = true;
custom_options.allow_comments = false; // Keep other defaults or explicitly set
let custom_json = r#"myKey: "myValue", another: 42"#;
match parse_with_options(custom_json, custom_options) {
Ok(value) => println!("Parsed with custom options: {:?}", value),
Err(e) => eprintln!("Custom parsing error: {}", e),
}
}
Handling Forgiving Features
zzson
excels at parsing JSON with common relaxations. Here are examples of how it handles them:
Comments
Both single-line (//
, #
) and multi-line (/* ... */
) comments are ignored.
use zzson::parse;
fn main() {
let json_with_comments = r#"
{
// This is a single-line comment
"name": "Alice", /* This is a
multi-line comment */
"age": 30, # Another comment style
}
"#;
let value = parse(json_with_comments).unwrap();
println!("Parsed with comments: {:?}", value);
}
Trailing Commas
Trailing commas in arrays and objects are gracefully handled.
use zzson::parse;
fn main() {
let json_with_trailing_comma = r#"
[
1,
2,
3, // Trailing comma here
]
"#;
let value = parse(json_with_trailing_comma).unwrap();
println!("Parsed with trailing comma: {:#?}", value);
let obj_with_trailing_comma = r#"
{
key1: "value1",
key2: "value2", // Trailing comma here
}
"#;
let obj_value = parse(obj_with_trailing_comma).unwrap();
println!("Parsed object with trailing comma: {:#?}", obj_value);
}
Unquoted Keys
Object keys do not need to be quoted, as long as they are valid identifiers.
use zzson::parse;
fn main() {
let json_unquoted_keys = r#"{ firstName: "John", lastName: "Doe" }"#;
let value = parse(json_unquoted_keys).unwrap();
println!("Parsed with unquoted keys: {:#?}", value);
}
Implicit Top-Level Objects and Arrays
You don’t need to wrap your entire input in {}
or []
if it’s clearly an object or an array.
use zzson::parse;
fn main() {
// Implicit object
let implicit_obj = r#"name: "Bob", age: 25"#;
let obj_value = parse(implicit_obj).unwrap();
println!("Parsed implicit object: {:#?}", obj_value);
// Implicit array
let implicit_arr = r#""apple", "banana", "cherry""#;
let arr_value = parse(implicit_arr).unwrap();
println!("Parsed implicit array: {:#?}", arr_value);
}
Newline as Comma
When the newline_as_comma
option is enabled, newlines can act as implicit comma separators.
use zzson::{parse_with_options, ParserOptions};
fn main() {
let mut options = ParserOptions::default();
options.newline_as_comma = true;
let json_with_newlines = r#"
[
1
2
3
]
"#;
let value = parse_with_options(json_with_newlines, options).unwrap();
println!("Parsed with newlines as commas: {:#?}", value);
let obj_with_newlines = r#"
{
key1: "value1"
key2: "value2"
}
"#;
let obj_value = parse_with_options(obj_with_newlines, options).unwrap();
println!("Parsed object with newlines as commas: {:#?}", obj_value);
}
Error Handling
zzson
returns a Result<Value, Error>
which allows for robust error handling. You should always check the Result
to handle potential parsing issues.
use zzson::parse;
fn main() {
let invalid_json = r#"{ key: "value }"#; // Missing closing quote
match parse(invalid_json) {
Ok(value) => println!("Parsed: {:?}", value),
Err(e) => eprintln!("Parsing error: {}", e),
}
}
For more details on error types, refer to the API Reference.
For more details on the web tool, including its features and how to use it, refer to the Web Tool documentation.