### `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](https://zillowe.qzz.io/docs/zds/zoi):
```bash
zoi install @zillowe/zoko
```
### From Source
```bash
# 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
```bash
cargo install zoko-cli
```
### Add to Your Rust Project
```bash
cargo add zoko-parser
```
## Quick Start
### Create a Zoko File
Create a file named `config.zo`:
```toml
name: "My Application",
version: "1.0.0",
debug: true,
database: {
host: "localhost",
port: 5432,
},
tags: ["production", "api"],
```
### Parse and Validate
```bash
# 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
```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
```toml
// 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
```bash
# 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:
```toml
// main.zo
@include("common.zo"),
@include("database.zo"),
app_name: "MyApp",
debug: true,
```
### Environment Variables
Use environment variables in configuration:
```toml
database_url: `${DATABASE_URL}`,
api_endpoint: `${API_ENDPOINT:-https://api.example.com}`,
```
### Schema Validation
Define and validate schemas:
```rust
use zoko_parser::{Schema, SchemaType, validate_schema};
let schema = Schema {
properties: properties_map,
required: vec!["name".to_string()],
};
validate_schema(&zoko_file, &schema)?;
```