⚡ v2.03 — Object Definition Language

ODL & ObjectWhack

One Object Definition to Rule Them All
Define once. Export to 14+ languages & formats. Store in binary.

⚡

Why ODL? — Define Once, Export Everywhere

📦

Binary .chd Storage

Memory-mapped monolithic block. Zero-copy, unbuffered, non-blocking I/O.

🌐

14+ Export Formats

Java, JavaScript, JSON, TypeScript, C, Go, Swift, Rust, Kotlin, C#, TOML, WASM, MessagePack, ODL.

🧩

Nested Objects

Objects can contain Objects. Multi-dimensional arrays. Sparse arrays.

⚡

MemoryChannel

HEAP, STACK, IPC, GPU, CLOUD, REGISTRY, PAGE — all in one memory model.

🔗

Network Serialization

Send Objects over sockets with zero-copy, endian-safe binary protocol.

📊

BQL Database

Query Objects with SQL-like commands. Monolithic index. Non-blocking.

🧠

Memory Type Prefixes — Optional Storage Hints

Default: All fields reside in the HEAP (dynamic memory) unless explicitly prefixed. The following qualifiers are parsed but ignored by the ODL compiler — they serve as hints for the runtime or for higher‑level frameworks. They do not affect the binary layout.

HEAP
default, malloc
STACK
automatic
IPC
inter‑process
GPU
device memory
CLOUD
remote storage
REGISTRY
global table
PAGE
mmap / file
Example with prefix
// Prefix is optional; without it, HEAP is assumed
STACK   char     name[64] = "USS Enterprise";
GPU     float    warp_speed = 9.975;
// no prefix → HEAP
int64_t  registry = 1701;
📡

Efficient Serialization — Unbuffered I/O & Socket Blast

Monolithic Block Design. The ObjectWhack runtime serializes an entire object graph into a contiguous memory region. This eliminates per‑field marshalling overhead and enables memory‑mapped I/O (mmap) for near‑zero‑copy deserialization.

Protocol Specification. The binary format (.chd) begins with a fixed header (SerialHeader) containing a magic number (0x4F57424A), version, flags, name length, field count, and total size. All multi‑byte integers are converted to network byte order (big‑endian) to ensure portability across architectures.

Unbuffered System Calls. The implementation uses write() and read() directly (wrapped as write_exact/read_exact). This bypasses the stdio buffer, ensuring that data is pushed to the kernel immediately — critical for low‑latency networking and real‑time systems. The entire object is written in a single write loop when possible, minimising system call overhead.

Bytecode Derivation. The serialization routine derives the bytecode directly from the in‑memory field descriptors — no intermediate AST or reflection is required. This yields a constant‑time serialization cost proportional to the total data size, with zero heap allocations during the write path.

Endian‑Aware Element Packing. Each elementary type (int8, int16, int32, int64, float, double) is individually byte‑swapped if the host is little‑endian. This ensures that the stored representation is canonical and can be read on any platform without further conversion.

⚡ Socket Blast – Zero‑Copy Network Transfer

FSendObject / FReceiveObject. The library provides two functions for direct socket I/O:

  • int64_t FSendObject(struct Object *obj, int fd); – serializes obj into a contiguous buffer and sends it via write_exact.
  • struct Object* FReceiveObject(int fd); – reads the header and payload via read_exact, reconstructing the object graph.

Because the serialised buffer is written directly to the socket descriptor, the data travels from the object’s memory to the network interface with zero intermediate copies in user space. This is what we call a "Socket Blast" – a single, unbuffered push of the entire object state over the wire.

Example (server side):

C – Socket Blast
int client_fd = accept(listen_fd, ...);
struct Object *ship = LoadObject("Starship");
if (ship) {
    int64_t bytes = FSendObject(ship, client_fd);
    printf("Sent %lld bytes\n", bytes);
    FreeObject(ship);
}
close(client_fd);

Client side:

C – Receive
int server_fd = connect(...);
struct Object *ship = FReceiveObject(server_fd);
if (ship) {
    PrintObject(ship);
    FreeObject(ship);
}
close(server_fd);

The same mechanism works for IPC (Unix domain sockets) and even stdin/stdout redirection, making ObjectWhack ideal for microservices and side‑car architectures.

Serialization Header (C)
typedef struct __attribute__((packed)) {
    uint32_t magic;      // 0x4F57424A
    uint32_t version;    // 1
    uint64_t flags;      // user flags
    uint32_t name_len;
    uint32_t field_count;
    uint32_t total_size; // entire serialised block size
} SerialHeader;
🔤

All Supported Types — Canonical & Short‑form Aliases

The ODL parser recognises both the standard C‑style names (from type_table) and the short‑form aliases listed in the table below. These aliases are accepted in all contexts — full multi‑line definitions, shorthand single‑line descriptions, and nested object initialisers.

int8_t
(i8)
signed 8‑bit · DATA_BYTE
byte8_t
—
unsigned 8‑bit · DATA_BYTE
uint8_t
(u8)
unsigned 8‑bit · DATA_BYTE
int16_t
(i16)
signed 16‑bit · DATA_SHORT
uint16_t
(u16)
unsigned 16‑bit · DATA_SHORT
int32_t
(i32)
signed 32‑bit · DATA_INT
uint32_t
(u32)
unsigned 32‑bit · DATA_INT
int64_t
(i64)
signed 64‑bit · DATA_LONG
uint64_t
(u64)
unsigned 64‑bit · DATA_LONG
float
(f32)
32‑bit IEEE 754 · DATA_FLOAT
double
(f64)
64‑bit IEEE 754 · DATA_DOUBLE
char
—
16‑bit Unicode · DATA_CHAR
Object
—
nested object · DATA_OBJECT

The parser maps i8 → int8_t, i16 → int16_t, i32 → int32_t, i64 → int64_t, u8 → uint8_t, u16 → uint16_t, u32 → uint32_t, u64 → uint64_t, f32 → float, and f64 → double.

📖

ODL Syntax — Full Multi‑Line Form

SyntaxDescriptionExample
OBJECT Name; Start an object definition OBJECT Ship;
{ ... } Encloses field definitions { ... }
HEAP|STACK|IPC|GPU|CLOUD|REGISTRY|PAGE type name; Memory type prefix (optional, default HEAP) GPU float warp_speed;
type name; Scalar field int32_t x; or i32 x;
type name[n]; Fixed‑size array char name[64];
type name[]; Sparse / dynamic array int32_t coords[]; or i32 coords[];
type name[n][m]; Multi‑dimensional array int32_t grid[10][10];
Object name; Nested object reference Object pilot;
type name = "value"; Scalar initializer char name[32] = "Enterprise";
type name = { 1, 2, 3 }; Array initializer int32_t coords[] = {1, 2, 3};
Complete Example (using aliases)
// Full form with short‑form aliases and braces
OBJECT Starship;
{
    i64       registry = 1701;
    char      name[64] = "USS Enterprise";
    f32       warp_speed = 9.975;
    i32       crew[3][3] = {
        {1, 2, 3}, {4, 5, 6}, {7, 8, 9}
    };
    Object    captain;
}
✂️

Compact Shorthand Syntax — Single‑Line Form for Interactive Use

The interactive n (new object) command accepts a comma‑separated single‑line description. This form omits the OBJECT keyword and trailing semicolon, but supports the same type names, array brackets, and initialisers as the full multi‑line syntax. The parser (AllocObject) splits on top‑level commas (respecting quotes and braces) and builds the object in one pass.

Aliases are fully supported — use i32, i64, f32, etc. for brevity.

Example 1 — Starship (with aliases) Starship, i64 registry=1701, char name[64]="USS Enterprise", f32 warp_speed=9.975, i32 position[3]={0,0,0}, Object captain
Example 2 — Neural Network (mixed) NeuralNetwork, i32 layers=50, f32 weights[][], f32 biases[], char dataset[256]="mnist"
Example 3 — GPUBuffer (with prefix and aliases) GPUBuffer, i32 width=1920, i32 height=1080, GPU u8 data[], i8 is_allocated=0
Implementation note: The shorthand parser is the same one used for nested object initialisers (e.g. Object captain = { ... }). It is designed for rapid prototyping and interactive use; for persistent definitions, the multi‑line OBJECT … ; { ... } form is recommended for clarity.
🚀

Tech Objects — 12 Complete Real‑World Examples

The examples below use the canonical type names for clarity; you may replace them with aliases at any time. Memory prefixes are omitted except where they add semantic value (e.g., GPU). All definitions use the brace‑enclosed syntax.

🚀 Starship

Starship

A complete starship definition for a space simulation.
OBJECT Starship;
{
    int64_t   registry = 1701;
    char      name[64] = "USS Enterprise";
    float     warp_speed = 9.975;
    int32_t   position[3] = {0, 0, 0};
    float     orientation[4] = {0.0, 0.0, 0.0, 1.0};
    int32_t   shield_level = 100;
    int32_t   hull_integrity = 100;
    Object    captain;
    Object    crew[];        // Sparse array
}
.chd .java .json .ts .rs
🧠 Neural

NeuralNetwork

Deep learning model definition with weights and architecture.
OBJECT NeuralNetwork;
{
    char      model_name[128] = "resnet50";
    int32_t   layers = 50;
    int32_t   neurons[] = {784, 256, 128, 10};
    float     weights[][];    // 2D weights matrix
    float     biases[];
    int8_t    activation = 0;   // 0=ReLU,1=Sigmoid,2=Tanh
    float     learning_rate = 0.001;
    int32_t   epochs = 100;
    char      dataset[256] = "mnist";
}
.java .go .wat
🔌 WebSocket

WebSocketConnection

Real‑time WebSocket connection state for chat/streaming.
OBJECT WebSocketConnection;
{
    int64_t   connection_id = 0;
    char      remote_addr[64] = "127.0.0.1";
    int32_t   port = 8080;
    char      protocol[32] = "ws";
    int8_t    state = 0;          // 0=Connecting,1=Open,2=Closing,3=Closed
    uint64_t  bytes_sent = 0;
    uint64_t  bytes_received = 0;
    float     latency = 0.0;
}
.js .ts .go .swift
⛓️ Block

BlockchainBlock

A block in a blockchain with transactions and proof‑of‑work.
OBJECT BlockchainBlock;
{
    int64_t   index = 0;
    char      timestamp[32] = "2026-01-01T00:00:00Z";
    char      prev_hash[64] = "0000...";
    char      hash[64];
    int32_t   nonce = 0;
    uint64_t  difficulty = 4;
    Object    transactions[];
    int64_t   merkle_root = 0;
}
.cs .kt .json .msgpack
🖥️ GPU

GPUBuffer

GPU memory buffer for graphics or compute workloads.
OBJECT GPUBuffer;
{
    int32_t   width = 1920;
    int32_t   height = 1080;
    int32_t   depth = 1;
    int32_t   format = 0;        // 0=RGBA8,1=Float32,2=Int32
    uint64_t  size = 0;
    GPU     uint8_t   data[];          // Raw GPU data
    float     memory_usage = 0.0;
    int8_t    is_allocated = 0;
}
.c .rs .wat
🌐 DNS

DNSRecord

DNS record with type, TTL, and resource data.
OBJECT DNSRecord;
{
    char      domain[256] = "example.com";
    int32_t   ttl = 3600;
    int16_t   record_type = 1;   // 1=A,2=NS,5=CNAME,15=MX,28=AAAA
    char      value[256] = "93.184.216.34";
    int32_t   priority = 10;       // For MX records
    int32_t   weight = 0;
    int16_t   port = 0;
}
.java .go .toml
🎮 Entity

GameEntity

Game entity with transform, components, and state.
OBJECT GameEntity;
{
    int64_t   entity_id = 1;
    char      tag[64] = "Player";
    float     position[3] = {0.0, 0.0, 0.0};
    float     rotation[4] = {0.0, 0.0, 0.0, 1.0};
    float     scale[3] = {1.0, 1.0, 1.0};
    int8_t    active = 1;
    uint64_t  component_mask = 0;
    Object    components[];
}
.cs .java .js .chd
🔀 API

APIRoute

API route definition with methods, middleware, and handlers.
OBJECT APIRoute;
{
    char      path[256] = "/api/v1/users";
    int8_t    methods[] = {0, 1};  // 0=GET,1=POST,2=PUT,3=DELETE,4=PATCH
    char      handler[128] = "UserController";
    char      middleware[][];
    int32_t   timeout = 30;
    int32_t   rate_limit = 100;
    char      description[512] = "User CRUD endpoints";
}
.ts .json .go .rs
📡 Sensor

SensorData

IoT sensor reading with timestamp and metadata.
OBJECT SensorData;
{
    char      sensor_id[64] = "temp-01";
    char      type[32] = "temperature";
    double    value = 23.5;
    int64_t   timestamp = 0;
    float     accuracy = 0.1;
    char      unit[16] = "C";
    int32_t   battery = 100;
    int8_t    status = 0;          // 0=OK,1=Warning,2=Error
}
.java .json .msgpack
☸️ K8s

KubernetesPod

Kubernetes pod definition with containers and resources.
OBJECT KubernetesPod;
{
    char      name[128] = "nginx-pod";
    char      namespace[64] = "default";
    char      labels[][];
    Object    containers[];
    char      node[128];
    int32_t   cpu_request = 100;
    int32_t   memory_request = 128;
    int8_t    phase = 0;          // 0=Pending,1=Running,2=Succeeded,3=Failed
}
.go .yaml .toml .chd
🤖 Transformer

AITransformer

Transformer model architecture with attention heads.
OBJECT AITransformer;
{
    char      model_id[128] = "gpt-style";
    int32_t   num_layers = 12;
    int32_t   num_heads = 12;
    int32_t   embed_dim = 768;
    int32_t   vocab_size = 50257;
    float     dropout = 0.1;
    float     weight[][][];     // 3D weight tensor
    float     bias[][];         // 2D bias tensor
}
.java .rs .wat
☁️ Cloud

CloudResource

Cloud resource with provider, region, and cost.
OBJECT CloudResource;
{
    char      resource_id[128] = "i-0abc123";
    char      provider[32] = "aws";
    char      region[32] = "us-east-1";
    char      type[64] = "ec2";
    char      tags[][];
    float     cost_per_hour = 0.0464;
    int32_t   cpu = 2;
    int64_t   memory = 4096;
    int8_t    state = 1;           // 0=Stopped,1=Running,2=Terminated
}
.kt .cs
.json .toml
💻

Command Line Options — Exact flags from ObjectWhack.c

Usage: ./ow [options] [file.odl ...]
If files are given they are processed; otherwise stdin is read.
If no files and stdin is a terminal → interactive mode.

FlagExport FormatNotes
-jJava (.java)public class
-kJavaScript (.js)const object
-zJSON (.json)name + fields
-vTypeScript (.ts)interface
-cC Header (.h)struct + include guard
-gGo (.go)type struct
-wSwift (.swift)struct
-oODL (.odl)re-emit definition
-aAll formatssets EXFLAG_ALL (includes Rust, Kotlin, C#, TOML, WASM, MessagePack)

Interactive mode commands (when run with no arguments on a TTY):

KeyAction
nNew object (compact single-line description)
PProcess all .odl files in object directory
lLoad object
sSave object (.chd)
pPrint current object
tList saved objects
bPrint all objects
aExport current object to all formats
o / j / k / z / v / y / c / g / wExport specific language
hHelp
qQuit
$ ./ow -a starship.odl
→ Exporting starship to all 14 formats
.chd .java .js .json .ts .h .go .swift .rs .kt .cs .toml .wat .msgpack
✓ starship.chd
✓ starship.java
✓ starship.ts
✓ starship.rs
Export complete.

$ ./ow -j -z -v player.odl
→ Exporting player to Java, JSON, TypeScript
✓ player.java
✓ player.json
✓ player.ts

$ ./ow -a ./objects/*.odl
→ Processing 12 ODL files
✓ Ship → all formats
✓ Player → all formats
✓ Weapon → all formats
... 9 more
📁

Export Formats — 14 Languages & Formats

.chd
Binary
.java
Java
.js
JavaScript
.json
JSON
.ts
TypeScript
.h
C Header
.go
Go
.swift
Swift
.rs
Rust
.kt
Kotlin
.cs
C#
.toml
TOML
.wat
WASM
.msgpack
MessagePack
Hits--