---

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.