Zillowe Docs - Getting Started

This guide will help you get started with Zoko, from installation to basic usage.

Installation

You can install Zoko CLI using Zoi:

zoi install @zillowe/zoko

From Source

Zoko is currently available as a Rust project. To build and install 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

If you have Rust installed, you can install directly via cargo:

cargo install zoko-cli

Your First Zoko File

Create a new file called config.zo:

// My first Zoko configuration
name: "My Application",
version: "1.0.0",
debug: true,
max_connections: 100,
allowed_hosts: ["localhost", "example.com"],

Parsing Zoko Files

Using the CLI

You can parse and validate Zoko files using the CLI:

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

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

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

Using the Rust Library

Add to your Cargo.toml:

[dependencies]
zoko-parser = "0.1"

Then use it in your Rust code:

use zoko_parser::{parse_zoko, parse_zoko_to_json};

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");

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

Basic Syntax

Objects and Maps

Zoko supports both simple objects and nested structures:

// Simple object
name: "value",

// Nested object (map)
config: {
  database: {
    host: "localhost",
    port: 5432,
  },
},

Arrays

Arrays can contain any type of value:

tags: ["production", "api", "v1"],
servers: [
  {host: "server1.example.com", port: 8080},
  {host: "server2.example.com", port: 8080},
],

Comments

Use comments to document your configuration:

// This is a single-line comment
name: "value",

/* This is a
   multi-line comment
   that spans multiple lines */
debug: true,

String Types

Zoko supports three string types:

double_quoted: "hello world",
single_quoted: 'hello world',
multi_line: `This is a
multi-line string
that preserves formatting`,

Converting to JSON

Zoko is designed to be compatible with JSON. You can easily convert between formats:

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

# The JSON output will be:
{
  "entries": {
    "name": "My Application",
    "version": "1.0.0",
    "debug": true
  }
}

Formatting

Use the built-in formatter to ensure your Zoko files are properly formatted:

# Format a file (in-place)
zoko-cli fmt config.zo

# Format to a different file
zoko-cli fmt config.zo --output formatted.zo

# Check if file is formatted (without modifying)
zoko-cli fmt --check config.zo

The formatter preserves:

Entry order (using IndexMap)
Original structure and nesting
Comments and their placement

Next Steps

Syntax Reference - Learn all the syntax features
CLI Reference - Explore all CLI commands
API Reference - Use Zoko in your Rust projects

Getting Started