zoko-parser 0.2.0

Zoko

A JSON-like format for data storing

Zoko is a human-readable data format that extends JSON with additional features like comments, trailing commas, and multiple string types. It's designed for configuration files, data storage, and any use case where you need the flexibility of JSON with better readability.

Features

• Enhanced Data Types: Support for integers, floats, decimals, dates, times, durations, and binary data
• File Includes: Split configuration into reusable modules using @include("file.zo")
• Environment Variables: Substitute environment variables in backtick strings using ${VAR} syntax
• Schema Validation: Built-in schema validation for type safety and structure validation
• Human-Readable Syntax: Clean and intuitive syntax that's easy to read and write
• Comments: Single-line (//) and multi-line (/* */) comments for better documentation
• Trailing Commas: No need to worry about trailing commas - they're fully supported
• Multiple String Types: Double-quoted, single-quoted, and multi-line backtick strings
• JSON & YAML Compatible: Easy conversion between Zoko, JSON, and YAML formats
• Order Preservation: Maintains the original order of objects and maps using IndexMap
• Type Safe: Full Rust API with strong typing and error handling
• CLI Tools: Command-line interface for parsing, validation, and formatting

Installation

You can install Zoko CLI using Zoi:

zoi install @zillowe/zoko

From Source

# Clone the repository
git clone https://github.com/akuolwa/zoko.git
cd zoko

# Build the project
cargo build --release

# The CLI binary will be available at target/release/zoko-cli

Using Cargo

cargo install zoko-cli

Add to Your Rust Project

cargo add zoko-parser

Quick Start

Create a Zoko File

Create a file named config.zo:

name: "My Application",
version: "1.0.0",
debug: true,
database: {
  host: "localhost",
  port: 5432,
},
tags: ["production", "api"],

Parse and Validate

# Validate a Zoko file
zoko-cli validate config.zo

# Parse to JSON
zoko-cli parse config.zo --output config.json

# Parse to YAML
zoko-cli parse config.zo --yaml --output config.yaml

# Format a Zoko file
zoko-cli fmt config.zo

Use in Rust

use zoko_parser::{parse_zoko, parse_zoko_to_json, Schema, SchemaType, validate_schema};

fn main() {
    let zoko_content = r#"
name: "My Application",
version: 1.0.0,
debug: true,
"#;

    // Parse the Zoko content
    let zoko_file = parse_zoko(zoko_content).expect("Failed to parse Zoko");
    println!("Parsed {} entries", zoko_file.entries.len());

    // Convert to JSON
    let json = parse_zoko_to_json(zoko_content).expect("Failed to convert to JSON");
    println!("{}", json);

    // Validate against schema
    let mut properties = std::collections::IndexMap::new();
    properties.insert("name".to_string(), SchemaType::String);
    properties.insert("version".to_string(), SchemaType::Float);
    properties.insert("debug".to_string(), SchemaType::Boolean);

    let schema = Schema {
        properties,
        required: vec!["name".to_string(), "version".to_string()],
    };

    match validate_schema(&zoko_file, &schema) {
        Ok(_) => println!("Schema validation passed"),
        Err(e) => println!("Schema validation failed: {}", e),
    }
}

Example Zoko File

// Basic configuration
name: "My Application",
version: 1.0.0,
debug: false,
database: {
  host: "localhost",
  port: 5432,
},

// Enhanced data types
release_date: date("2024-06-21"),
timeout: duration("30s"),
price: decimal("19.99"),

// Environment variables (in backtick strings)
api_url: `${API_URL:-https://api.example.com}`,

// File includes
@include("common/config.zo"),
@include("database/settings.zo"),

// Tags and metadata
tags: ["production", "api"],
website: "https://example.com",

CLI Commands

# Parse and validate
zoko-cli validate config.zo
zoko-cli parse config.zo
zoko-cli parse config.zo --yaml

# Format files
zoko-cli fmt config.zo
zoko-cli fmt --check config.zo

# Check syntax
zoko-cli check config.zo

Advanced Usage

File Includes

Split large configuration files into smaller, reusable modules:

// main.zo
@include("common.zo"),
@include("database.zo"),

app_name: "MyApp",
debug: true,

Environment Variables

Use environment variables in configuration:

database_url: `${DATABASE_URL}`,
api_endpoint: `${API_ENDPOINT:-https://api.example.com}`,

Schema Validation

Define and validate schemas:

use zoko_parser::{Schema, SchemaType, validate_schema};

let schema = Schema {
    properties: properties_map,
    required: vec!["name".to_string()],
};

validate_schema(&zoko_file, &schema)?;