ctoon

README

CToon

The fastest implementation of the TOON format — a compact, human-readable serialisation format designed to minimise LLM token usage. Achieves 30-60% token reduction versus JSON while remaining fully readable and structured.

CToon is built on a high-performance C core and exposes the same logic through idiomatic bindings for C++, Go, Julia, MATLAB, Python, Rust, and Zig, plus a standalone CLI. The name reflects its foundation: C + TOON.

Format Overview

# JSON  (352 bytes)                  # TOON  (165 bytes, -53 %)
{                                    order:
  "order": {                           id: ORD-12345
    "id": "ORD-12345",                 status: completed
    "items": [                         customer:
      {"product":"Book","qty":2},        name: John Doe
      {"product":"Pen","qty":5}          email: john@example.com
    ]                                  items[2]{product,qty}:
  }                                      Book,2
}                                        Pen,5

---

Quick Start

Pick your language below — each section is install, a short example, then a link to that language's full reference for everything else (flags, options, error handling, ...). Order matches the tabs on the documentation site.

CLI

pip install ctoon        # ships a pre-built `ctoon` binary — no compiler needed

ctoon input.json                 # JSON  -> TOON (auto-detected from extension)
ctoon input.toon -o output.json  # TOON  -> JSON
cat data.json | ctoon -e -       # stdin -> TOON

Building from source with CMake instead is also supported (sudo cmake --install build after building — see Building & Testing). → Full CLI reference

C

Requires CMake 3.19+ and a C99 compiler.

# CMakeLists.txt
include(FetchContent)
FetchContent_Declare(ctoon
  GIT_REPOSITORY https://github.com/MohammadRaziei/ctoon.git  GIT_TAG main)
FetchContent_MakeAvailable(ctoon)
target_link_libraries(my_app PRIVATE ctoon::ctoon)

#include "ctoon.h"

ctoon_doc *doc = ctoon_read("name: Alice\nage: 30", 20, 0);
ctoon_val *root = ctoon_doc_get_root(doc);
printf("%s\n", ctoon_get_str(ctoon_obj_get(root, "name")));  /* Alice */

size_t len;
char *toon = ctoon_write(doc, &len);   /* caller must free() */
free(toon);
ctoon_doc_free(doc);

→ Full C API reference (also summarised below)

C++

Requires CMake 3.19+ and a C++11 compiler. Header-only on top of the C core.

# same FetchContent block as C, then:
target_link_libraries(my_app PRIVATE ctoon::ctoonpp)

#include "ctoon.hpp"

auto doc  = ctoon::document::parse("name: Alice\nage: 30");
auto root = doc.root();
std::cout << root["name"].get_str().str() << "\n";  // Alice
std::cout << doc.to_json(2).c_str() << "\n";         // pretty JSON

→ Full C++ API reference

Go

Requires Go 1.21+ with CGo enabled; a C compiler must be on the build host.

go get github.com/mohammadraziei/ctoon

import ctoon "github.com/mohammadraziei/ctoon"

toon, _ := ctoon.Dumps(map[string]interface{}{"name": "Alice", "age": int64(30)})
val, _  := ctoon.Loads(toon)

→ Full Go reference

Julia

Requires Julia 1.7+ and a C compiler. Not yet in Julia's General registry.

import Pkg
Pkg.add(url="https://github.com/mohammadraziei/ctoon.git", subdir="src/bindings/julia")

using CToon

data = CToon.parse("""{"name": "Alice", "age": 30}""")
println(data["name"])   # Alice

→ Full Julia reference

MATLAB

Requires MATLAB R2014b+ and a C compiler configured for MEX (mex -setup C).

cd src/bindings/matlab
ctoon_install    % compiles the MEX gateway, adds it to your MATLAB path

s = ctoon.encode(struct('name', 'Alice', 'age', uint64(30)));
v = ctoon.decode(s);
v.name    % 'Alice'

→ Full MATLAB reference (type mapping, ctoon.read/ctoon.write, Python-style aliases, ...)

Python

Requires Python 3.9+. Pre-built wheels for Linux, macOS and Windows — no compiler needed.

pip install ctoon

import ctoon

toon = ctoon.dumps({"name": "Alice", "age": 30})
data = ctoon.loads(toon)

→ Full Python reference

Rust

Requires Rust 1.70+ and a C compiler on the build host.

[dependencies]
ctoon = { git = "https://github.com/mohammadraziei/ctoon.git" }

let val = ctoon::loads("name: Alice\nage: 30")?;
println!("{}", val["name"].as_str().unwrap()); // Alice
let toon = ctoon::dumps(&val)?;

→ Full Rust reference

Zig

Requires Zig 0.16.0+.

zig fetch --save git+https://github.com/mohammadraziei/ctoon.git

const ctoon = @import("ctoon");

var val = try ctoon.loads(gpa, "name: Alice\nage: 30");
defer val.deinit(gpa);
const toon = try ctoon.dumps(gpa, val);

→ Full Zig reference

---

TOON Spec Version

The toon-format/spec release a build targets is exposed in every language (spec §13: implementations SHOULD declare it). It is resolved at CMake configure time and recorded in supported_spec.conf; the bindings read it from the C core, so it can't drift. Each language gives you the version (4.1), the tag (v4.1.2) and the release date:

Language	Version	Tag	Date
C	CTOON_SPEC_VERSION_STRING	CTOON_SPEC_TAG_STRING	CTOON_SPEC_DATE_STRING
C++	ctoon::spec::version::string()	ctoon::spec::tag::string()	ctoon::spec::date::string()
Go	ctoon.SpecVersion()	ctoon.SpecTag()	ctoon.SpecDate()
Julia	CToon.spec_version()	CToon.spec_tag()	CToon.spec_date()
MATLAB	info.Spec.Version	info.Spec.Tag	info.Spec.Date ([~, info] = ctoon.version())
Python	ctoon.__toon_spec__	ctoon.__toon_spec_tag__	ctoon.__toon_spec_date__
Rust	ctoon::spec_version()	ctoon::spec_tag()	ctoon::spec_date()
Zig	ctoon.specVersion()	ctoon.specTag() (major/minor/patch)	ctoon.specDate()

In C and C++ the tag is also available as numbers (CTOON_SPEC_TAG_MAJOR/MINOR/PATCH, CTOON_SPEC_TAG_HEX; ctoon::spec::tag::major() etc.).

---

Building & Testing From Source

Each binding can be built, run and tested entirely with its own native tooling — cargo test for Rust, go test for Go, pytest for Python, zig build test for Zig, Pkg.test() for Julia, MATLAB's buildtool test — pick whichever's already open and go. But the project as a whole — building every language together, running the full cross-language test matrix, generating coverage, and building the documentation site — is driven by CMake, the same commands CI uses. This section covers that path; see CONTRIBUTING.md for the complete contributor workflow.

Configure

cmake -B build -DCMAKE_BUILD_TYPE=Release

By default this configures only C, C++ and the CLI. Each other language is opt-in via its own flag — and the flag changes what a missing toolchain does: silently skipped when the flag is OFF (the default, so the command above works on a machine with only some toolchains installed), a hard configure error when you've explicitly turned it ON:

# e.g. working on the Rust binding
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCTOON_BUILD_RUST=ON

# everything, like CI
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DCTOON_BUILD_PYTHON=ON -DCTOON_BUILD_GO=ON -DCTOON_BUILD_RUST=ON \
      -DCTOON_BUILD_ZIG=ON -DCTOON_BUILD_JULIA=ON

CMake options

Option	Default	Description
CTOON_BUILD_TESTS	ON (top-level)	Build and register tests.
CTOON_BUILD_EXAMPLES	ON (top-level)	Build the examples.
CTOON_BUILD_DOCS	OFF	Build documentation.
CTOON_BUILD_PYTHON	OFF	Build the Python extension (nanobind).
CTOON_BUILD_GO	OFF	Require the Go toolchain (error instead of skip if missing).
CTOON_BUILD_RUST	OFF	Require the Rust toolchain (error instead of skip if missing).
CTOON_BUILD_ZIG	OFF	Require the Zig toolchain (error instead of skip if missing).
CTOON_BUILD_JULIA	OFF	Require the Julia toolchain (error instead of skip if missing).
CTOON_BUILD_MATLAB	OFF	Require the MATLAB toolchain (error instead of skip if missing).
CTOON_BUILD_ALL_LANGS	OFF	Require every self-building language's toolchain at once.

JSON support is on by default. Define CTOON_DISABLE_JSON to turn it off — no external JSON library is required either way.

Build

cmake --build build -j

Test

ctest --test-dir build --output-on-failure --extra-verbose
# equivalently:
cmake --build build --target ctoon_test

Per-language targets, for iterating on one binding at a time: ctoon_test_c, ctoon_test_cpp, ctoon_test_go, ctoon_test_julia, ctoon_test_matlab, ctoon_test_python, ctoon_test_rust, ctoon_test_zig — each also runnable as a single ctest case, e.g. ctest --test-dir build -R rust.

Coverage

cmake --build build --target ctoon_coverage

Per-language: ctoon_coverage_c, ctoon_coverage_cpp, ctoon_coverage_go, ctoon_coverage_julia, ctoon_coverage_matlab, ctoon_coverage_python, ctoon_coverage_rust, plus ctoon_coverage_total (merged C/C++/Python/Go/Rust/Julia lcov report). Output lands in build/coverage/, with build/coverage/index.html as the dashboard — published at mohammadraziei.github.io/ctoon/coverage. (Zig has no coverage target yet — see the comment in tests/zig/CMakeLists.txt.)

Docs

cmake -B build -DCTOON_BUILD_DOCS=ON   # plus any CTOON_BUILD_<LANG>=ON you need
cmake --build build --target ctoon_docs

Per-language: ctoon_docs_c, ctoon_docs_cpp, ctoon_docs_julia, ctoon_docs_matlab, ctoon_docs_python, ctoon_docs_rust, plus ctoon_docs_index for the landing page (CLI and Zig are assembled straight from Markdown, no external doc tool needed). Output lands in build/docs/out/.

---

C API Reference

Parsing

/* from memory */
ctoon_doc *ctoon_read(const char *toon, size_t len, ctoon_read_flag flags);
ctoon_doc *ctoon_read_opts(char *toon, size_t len, ctoon_read_flag flags,
                            const ctoon_alc *alc, ctoon_read_err *err);
ctoon_doc *ctoon_read_opts_indent(char *toon, size_t len, ctoon_read_flag flags,
                                   int indent_size, const ctoon_alc *alc,
                                   ctoon_read_err *err);
/* from file */
ctoon_doc *ctoon_read_file(const char *path, ctoon_read_flag flags,
                            const ctoon_alc *alc, ctoon_read_err *err);
/* from JSON */
ctoon_doc *ctoon_read_json(char *json, size_t len, ctoon_read_flag flags,
                            const ctoon_alc *alc, ctoon_read_err *err);
ctoon_doc *ctoon_read_json_file(const char *path, ctoon_read_flag flags,
                                 const ctoon_alc *alc, ctoon_read_err *err);

Writing

/* TOON output */
char *ctoon_write(const ctoon_doc *doc, size_t *len);
char *ctoon_write_opts(const ctoon_doc *doc, const ctoon_write_options *opts,
                        const ctoon_alc *alc, size_t *len, ctoon_write_err *err);
char *ctoon_mut_write(const ctoon_mut_doc *doc, size_t *len);

/* JSON output */
char *ctoon_doc_to_json(const ctoon_doc *doc, int indent,
                         ctoon_write_flag flags, const ctoon_alc *alc,
                         size_t *len, ctoon_write_err *err);

Access

/* document */
ctoon_val *ctoon_doc_get_root(const ctoon_doc *doc);
void       ctoon_doc_free(ctoon_doc *doc);

/* type checks */
bool ctoon_is_null(ctoon_val *v);   bool ctoon_is_bool(ctoon_val *v);
bool ctoon_is_true(ctoon_val *v);   bool ctoon_is_false(ctoon_val *v);
bool ctoon_is_uint(ctoon_val *v);   bool ctoon_is_sint(ctoon_val *v);
bool ctoon_is_real(ctoon_val *v);   bool ctoon_is_str(ctoon_val *v);
bool ctoon_is_arr(ctoon_val *v);    bool ctoon_is_obj(ctoon_val *v);

/* getters */
const char *ctoon_get_str(ctoon_val *v);
uint64_t    ctoon_get_uint(ctoon_val *v);
int64_t     ctoon_get_sint(ctoon_val *v);
double      ctoon_get_real(ctoon_val *v);
bool        ctoon_get_bool(ctoon_val *v);

/* array */
size_t     ctoon_arr_size(ctoon_val *arr);
ctoon_val *ctoon_arr_get(ctoon_val *arr, size_t idx);   /* O(1) */

/* object */
size_t     ctoon_obj_size(ctoon_val *obj);
ctoon_val *ctoon_obj_get(ctoon_val *obj, const char *key);

/* iteration */
ctoon_obj_iter ctoon_obj_iter_with(ctoon_val *obj);
ctoon_val     *ctoon_obj_iter_next(ctoon_obj_iter *iter);
ctoon_val     *ctoon_obj_iter_get_val(ctoon_val *key);

Mutable documents

ctoon_mut_doc *ctoon_mut_doc_new(const ctoon_alc *alc);
void           ctoon_mut_doc_free(ctoon_mut_doc *doc);
void           ctoon_mut_doc_set_root(ctoon_mut_doc *doc, ctoon_mut_val *root);

ctoon_mut_val *ctoon_mut_null(ctoon_mut_doc *doc);
ctoon_mut_val *ctoon_mut_bool(ctoon_mut_doc *doc, bool val);
ctoon_mut_val *ctoon_mut_uint(ctoon_mut_doc *doc, uint64_t val);
ctoon_mut_val *ctoon_mut_sint(ctoon_mut_doc *doc, int64_t val);
ctoon_mut_val *ctoon_mut_real(ctoon_mut_doc *doc, double val);
ctoon_mut_val *ctoon_mut_str(ctoon_mut_doc *doc, const char *str);
ctoon_mut_val *ctoon_mut_arr(ctoon_mut_doc *doc);
ctoon_mut_val *ctoon_mut_obj(ctoon_mut_doc *doc);

bool ctoon_mut_arr_append(ctoon_mut_val *arr, ctoon_mut_val *item);
bool ctoon_mut_obj_put(ctoon_mut_val *obj, ctoon_mut_val *key, ctoon_mut_val *val);

/* convert between immutable and mutable */
ctoon_mut_doc *ctoon_doc_mut_copy(ctoon_doc *doc, const ctoon_alc *alc);
ctoon_doc     *ctoon_mut_doc_imut_copy(ctoon_mut_doc *doc, const ctoon_alc *alc);

---

Complexity

Operation	Time	Notes
ctoon_read / ctoon_read_json	O(n)	n = input bytes
ctoon_write / ctoon_doc_to_json	O(n)	zero extra copy for immutable doc
ctoon_arr_get(arr, i)	O(1)	direct index into flat arena
ctoon_obj_get(obj, key)	O(k)	linear scan; k = key count
ctoon_doc_free	O(chunks) ~= O(1)	arena freed in one shot

---

Thread Safety

Scenario	Safe?
Multiple threads reading different documents	Yes
Multiple threads reading the same document	Yes
Building a document from multiple threads	No — arena not thread-safe

---

License

MIT — see LICENSE.

Related

• toon-format/toon — the TOON format specification

Documentation

Overview

Package ctoon is the top-level Go entry-point for the CToon library.

It re-exports every public symbol from the implementation package (src/bindings/go/binding) so callers only need to import one path:

import "github.com/mohammadraziei/ctoon"

This file plays the same role as Python's __init__.py: nothing lives here except re-exports and type aliases.

Example:

data := map[string]interface{}{"name": "Alice", "age": int64(30)}
toon, _ := ctoon.Dumps(data)
fmt.Println(toon)

val, _ := ctoon.Loads(toon)
fmt.Println(val)

Index

• Constants
• Variables
• type DecodeOptions
• type Delimiter
• type EncodeOptions
• type ReadFlag
• type WriteFlag

Constants

const (
	ReadNoFlag              = binding.ReadNoFlag
	ReadAllowTrailingCommas = binding.ReadAllowTrailingCommas
	ReadAllowComments       = binding.ReadAllowComments
	ReadAllowInfAndNaN      = binding.ReadAllowInfAndNaN
	ReadAllowInvalidUnicode = binding.ReadAllowInvalidUnicode
	ReadToon5               = binding.ReadToon5
)

Read flag constants.

const (
	WriteNoFlag              = binding.WriteNoFlag
	WriteEscapeUnicode       = binding.WriteEscapeUnicode
	WriteEscapeSlashes       = binding.WriteEscapeSlashes
	WriteAllowInfAndNaN      = binding.WriteAllowInfAndNaN
	WriteInfAndNaNAsNull     = binding.WriteInfAndNaNAsNull
	WriteAllowInvalidUnicode = binding.WriteAllowInvalidUnicode
	WriteLengthMarker        = binding.WriteLengthMarker
	WriteNewlineAtEnd        = binding.WriteNewlineAtEnd
)

Write flag constants.

const (
	DelimiterComma = binding.DelimiterComma
	DelimiterTab   = binding.DelimiterTab
	DelimiterPipe  = binding.DelimiterPipe
)

Delimiter constants.

Variables

var Decode = binding.Decode

Decode parses a TOON string and returns the equivalent Go value.

val, err := ctoon.Decode(toonStr, ctoon.DefaultDecodeOptions())

var DecodeFromFile = binding.DecodeFromFile

DecodeFromFile reads and parses a TOON file, returning the Go value.

var DefaultDecodeOptions = binding.DefaultDecodeOptions

DefaultDecodeOptions returns lenient TOON5 parsing.

var DefaultEncodeOptions = binding.DefaultEncodeOptions

DefaultEncodeOptions returns compact TOON encoding with no special flags.

var DumpJSON = binding.DumpJSON

DumpJSON serialises v and writes JSON to path.

var Dumps = binding.Dumps

Dumps serialises v to a TOON string with default options. Alias for Encode.

var DumpsJSON = binding.DumpsJSON

DumpsJSON serialises v to a JSON string.

json, err := ctoon.DumpsJSON(myData, 2)

var DumpsToon = binding.DumpsToon

DumpsToon explicitly names the TOON format. Alias for Dumps.

var Encode = binding.Encode

Encode serialises a Go value to a TOON string.

toon, err := ctoon.Encode(myData, ctoon.DefaultEncodeOptions())

var EncodeToFile = binding.EncodeToFile

EncodeToFile serialises v and writes the TOON result to the file at path.

var JSONMarshal = binding.JSONMarshal

JSONMarshal serialises v to JSON-formatted bytes via ctoon's JSON writer. Same signature as encoding/json.Marshal. Named with the JSON prefix (not Marshal*JSON*) to avoid colliding in spirit with Go's json.Marshaler interface method name.

var JSONUnmarshal = binding.JSONUnmarshal

JSONUnmarshal parses JSON-formatted bytes via ctoon's JSON reader into the value pointed to by v. Same signature as encoding/json.Unmarshal.

var LoadJSON = binding.LoadJSON

LoadJSON reads and parses a JSON file.

var Loads = binding.Loads

Loads parses a TOON string with default options. Alias for Decode.

var LoadsJSON = binding.LoadsJSON

LoadsJSON parses a JSON string using ctoon's JSON reader.

var LoadsToon = binding.LoadsToon

LoadsToon explicitly names the TOON format. Alias for Loads.

var Marshal = binding.Marshal

Marshal serialises v to TOON-formatted bytes. Same signature as encoding/json.Marshal — for anyone reaching for the stdlib-idiomatic name out of habit. Loads/Dumps remain the primary API (kept consistent with every other ctoon binding's naming); this is a thin wrapper, not a separate implementation. Does not support struct reflection/tags — see binding.Marshal's doc comment for exactly what's supported.

var SpecDate = binding.SpecDate

SpecDate returns the release date of the targeted spec, e.g. "2026-07-26".

var SpecTag = binding.SpecTag

SpecTag returns the targeted toon-format/spec git tag, e.g. "v4.1.2".

var SpecVersion = binding.SpecVersion

SpecVersion returns the targeted TOON spec version, e.g. "4.1".

var Unmarshal = binding.Unmarshal

Unmarshal parses TOON-formatted bytes into the value pointed to by v. Same signature as encoding/json.Unmarshal.

Types

type DecodeOptions

type DecodeOptions = binding.DecodeOptions

DecodeOptions bundles all parsing settings.

type Delimiter

type Delimiter = binding.Delimiter

Delimiter selects the array-value separator used when writing TOON.

type EncodeOptions

type EncodeOptions = binding.EncodeOptions

EncodeOptions bundles all serialisation settings.

type ReadFlag

type ReadFlag = binding.ReadFlag

ReadFlag controls TOON parsing behaviour (bit flags).

type WriteFlag

type WriteFlag = binding.WriteFlag

WriteFlag controls TOON serialisation behaviour (bit flags).