Using SYNX in code

Mirrored from the format repository — docs/spec/SPECIFICATION_EN.md, SYNX 3.7.4. Changes are made there.

🚀 Core Principle: SYNX is read by your code directly. No conversion to JSON is needed. The library parses the .synx file itself and returns a native object for your language — dict in Python, Object in JavaScript. You work with data immediately.

5.1 Installation

# JavaScript / TypeScript
npm install @aperturesyndicate/synx-format

# Python
pip install synx-format

5.2 Python — Reading .synx Directly

from synx import Synx

# Read a .synx file — and get a dict immediately
data = Synx.load('config.synx')

# Done. Data is ready. Work with it like a regular dictionary:
print(data['app_name'])                # "TotalWario"
print(data['server']['port'])          # 8080
print(data['gameplay']['base_hp'])     # 100
print(data['gameplay']['boss_hp'])     # 500 (computed by :calc)
print(data['gameplay']['greeting'])    # "Wario time!" (chosen by :random)

# Lists are regular lists:
for map_name in data['map_rotation']:
    print(f'Loading map: {map_name}')

# Nesting is regular dicts:
if data['server']['ssl_enabled']:
    print('SSL is enabled')

Synx.load(path) — reads the file and parses in one call.
Synx.parse(text) — parses a string (if you already have the content).

# Alternatively — from a string:
with open('config.synx', 'r', encoding='utf-8') as f:
    data = Synx.parse(f.read())

5.3 JavaScript — Reading .synx Directly

const Synx = require('@aperturesyndicate/synx-format');

// Read a .synx file — get a regular JS object
const data = Synx.loadSync('config.synx');

// Work with it like a normal object using dot notation:
console.log(data.app_name);               // "TotalWario"
console.log(data.server.port);             // 8080
console.log(data.gameplay.base_hp);        // 100
console.log(data.gameplay.boss_hp);        // 500
console.log(data.gameplay.greeting);       // random phrase

// Lists are regular Arrays:
data.map_rotation.forEach(map => {
    console.log(`Loading map: ${map}`);
});

// Destructuring:
const { base_hp, boss_hp, greeting } = data.gameplay;
console.log(`Boss HP: ${boss_hp}, greeting: ${greeting}`);

Synx.loadSync(path) — reads the file and parses synchronously.
Synx.load(path) — async version (returns Promise).
Synx.parse(text) — parses a string.

// Async variant:
const data = await Synx.load('config.synx');

// From a string:
const fs = require('fs');
const text = fs.readFileSync('config.synx', 'utf-8');
const data = Synx.parse(text);

5.4 TypeScript — With Type Safety

import Synx from '@aperturesyndicate/synx-format';

// Define the structure of your config:
interface GameConfig {
  app_name: string;
  version: string;
  server: {
    port: number;
    host: string;
    ssl_enabled: boolean;
  };
  gameplay: {
    base_hp: number;
    boss_hp: number;
    greeting: string;
    loot_tier: string;
  };
  map_rotation: string[];
}

// The parser returns a typed object:
const data = Synx.loadSync<GameConfig>('config.synx');

console.log(data.gameplay.boss_hp);  // number — autocomplete works
console.log(data.server.port);       // number

5.5 Using SYNX Data for CSS

SYNX returns a plain object — Object in JS, dict in Python. You can use this data to generate CSS, CSS custom properties, or pass it into any styling system.

Example: CSS custom properties from SYNX in Node.js

# theme.synx
primary #5a6eff
secondary #ff5a8a
font_size 16
border_radius 8
spacing 12

const Synx = require('@aperturesyndicate/synx-format');
const fs = require('fs');

const theme = Synx.loadSync('theme.synx');

// Generate CSS custom properties
const css = `:root {
  --color-primary: ${theme.primary};
  --color-secondary: ${theme.secondary};
  --font-size: ${theme.font_size}px;
  --border-radius: ${theme.border_radius}px;
  --spacing: ${theme.spacing}px;
}`;

fs.writeFileSync('theme.css', css);

Example: Inline styles in React

import Synx from '@aperturesyndicate/synx-format';

const theme = Synx.loadSync('theme.synx');

function Button({ children }) {
  return (
    <button style={{
      backgroundColor: theme.primary,
      borderRadius: `${theme.border_radius}px`,
      padding: `${theme.spacing}px`,
      fontSize: `${theme.font_size}px`,
    }}>
      {children}
    </button>
  );
}

Example: CSS-in-JS (styled-components, Tailwind config)

// tailwind.config.js
const Synx = require('@aperturesyndicate/synx-format');
const theme = Synx.loadSync('theme.synx');

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: theme.primary,
        secondary: theme.secondary,
      },
      spacing: {
        base: `${theme.spacing}px`,
      },
    },
  },
};

SYNX doesn't replace CSS — it provides data (colors, sizes, tokens) that your code uses to generate styles. This is especially useful for design systems and theming.

5.6 Rust — Type-Safe Parsing

The SYNX Rust crate (synx) provides zero-dependency parsing with a rich type system.

Installation (Cargo.toml):

[dependencies]
synx-core = "3.6"

Basic Usage:

use synx::Synx;

fn main() {
    // Parse a .synx file
    let data = Synx::parse_file("config.synx").unwrap();
    
    // Access values with type safety
    if let Some(port) = data.get("server").and_then(|s| s.get("port")) {
        let port_num: i64 = port.as_int().unwrap_or(8080);
        println!("Server running on port {}", port_num);
    }
    
    // Work with nested objects
    let app_name = data
        .as_object()
        .and_then(|obj| obj.get("app_name"))
        .and_then(|v| v.as_str());
    
    // Convert to JSON if needed
    let json = serde_json::to_string(&data).unwrap();
}

Value type methods:

• .as_str() → Option<&str>
• .as_int() → Option<i64>
• .as_float() → Option<f64>
• .as_bool() → Option<bool>
• .as_object() → Option<&HashMap<String, Value>>
• .as_array() → Option<&Vec<Value>>
• .is_null() → bool

Indexing:

let value = data["server"]["port"];

Note: The Rust synx-core crate supports both static and !active modes, including all markers, constraints, .synxb compilation, and !tool parsing. It is the reference implementation.

5.7 C — FFI to synx-core (JSON strings)

The supported C integration is bindings/c-header: the header include/synx.h plus a shared or static library produced by the Rust crate synx-c (cdylib / staticlib). Functions return UTF-8 JSON strings (or byte buffers for .synxb); there is no SynxValue AST in C — use your JSON library if you need a native tree.

Build the library (from the repo root):

cargo build -p synx-c --release
# Linux: target/release/libsynx_c.so
# macOS: target/release/libsynx_c.dylib
# Windows: target/release/synx_c.dll (+ MSVC import .lib)

Include:

#include "synx.h"

Memory: every char* result is heap-allocated; the caller must synx_free() exactly once. Byte buffers from synx_compile must be released with synx_free_bytes(ptr, len).

Functions (v3.6): synx_parse, synx_parse_active, synx_stringify, synx_format, synx_parse_tool, synx_compile, synx_decompile, synx_is_synxb, synx_diff — see bindings/c-header/include/synx.h.

Minimal example:

#include "synx.h"
#include <stdio.h>

int main(void) {
    char *json = synx_parse("name John\nage 25\n");
    if (!json) {
        fputs("parse failed\n", stderr);
        return 1;
    }
    puts(json);
    synx_free(json);
    return 0;
}

Parity: This path uses the same engine as synx-core 3.6.x (!active, !tool, .synxb, canonical JSON).

5.8 C++ — thin wrapper (bindings/cpp)

The supported C++ surface is bindings/cpp/include/synx/synx.hpp (namespace synx) — a thin C++17 wrapper over §5.7. It exposes std::optional-based helpers for std::string_view / std::string and std::vector<unsigned char> for .synxb. You must link the same synx-c library and place both include directories on your path (bindings/cpp/include, bindings/c-header/include).

Example:

#include <synx/synx.hpp>
#include <iostream>

int main() {
    auto json = synx::parse("name Wario\nage 30\n");
    if (!json) return 1;
    std::cout << *json << '\n';
    return 0;
}

Wrappers: parse, parse_active, stringify, format, parse_tool, diff, compile, decompile, is_synxb — same semantics as synx.h.

Build notes: bindings/cpp/README.md and bindings/cpp/CMakeLists.txt (optional minimal example).

Parity: Behavior is identical to Rust synx-core for all FFI-exported operations.

5.9 C# — .NET 8 library (parsers/dotnet)

The supported C# implementation is parsers/dotnet/src/Synx.Core, targeting .NET 8.0. NuGet package ID APERTURESyndicate.Synx (the ID Synx.Core is taken on nuget.org).

Install via NuGet:

dotnet add package APERTURESyndicate.Synx

Listing: nuget.org/packages/APERTURESyndicate.Synx. Until the package is on the feed, use a project reference or local .nupkg — see parsers/dotnet/README.md.

Basic usage:

using Synx;

var map = SynxFormat.Parse("server\n  host 0.0.0.0\n  port 8080\n");
if (map["server"] is SynxValue.Obj server
    && server.Map["port"] is SynxValue.Int port)
    Console.WriteLine(port.Value);

var json = SynxFormat.ToJson(map);

// !active resolution (markers, constraints, includes)
var resolved = SynxFormat.ParseActive("!active\nport:env:default:8080 PORT\n");

Entry points (SynxFormat): Parse, ParseActive, ParseFull, ParseFullActive, ParseTool, ToJson.

Values: SynxValue discriminated records — Null, Bool, Int, Float, Str, Secret, Arr, Obj.

Parity: Static parse and canonical JSON match synx-core for covered conformance cases; ParseActive runs the managed !active engine. .synxb in C# is not implemented yet (use synx-core or bindings that wrap synx-c).

5.10 Go — cgo binding to synx-c (JSON API)

The supported Go integration is bindings/go: cgo wraps the same synx.h / synx-c library as C and C++. Functions return UTF-8 strings (JSON or SYNX text) or byte slices (.synxb); use encoding/json if you need a tree.

Requirements: Go 1.21+, CGO_ENABLED=1, a C toolchain, and synx_c installed/built (cargo build -p synx-c --release). Linux/macOS link flags default to -L../../target/release -lsynx_c relative to bindings/go. Windows: link synx_c.dll.lib via CGO_LDFLAGS, put synx_c.dll on PATH — see bindings/go/README.md.

Example:

package main

import (
    "fmt"
    synx "github.com/APERTURESyndicate/synx-format/bindings/go"
)

func main() {
    j, err := synx.Parse("name Wario\nage 30\n")
    if err != nil {
        panic(err)
    }
    fmt.Println(j)
}

API (v3.6): Parse, ParseActive, Stringify, Format, ParseTool, Compile, Decompile, IsSynxb, Diff — mirror synx.h.

Parity: Same engine as synx-core (!active, !tool, .synxb, canonical JSON).

5.11 Mojo — Python interop (bindings/mojo)

Mojo can call CPython via Python.import_module. The supported way to get SYNX 3.6 parity with synx-core is to import synx_native (the same PyO3 / maturin wheel as pip install synx-format). This is not a standalone Mojo grammar implementation (that would be a separate, large port — analogous to maintaining synx-js alongside Rust).

Setup: Install Python synx_native (wheel from this repo or PyPI). Optionally Python.add_to_path(...) if you built locally with maturin develop.

String helpers (also on synx_native for thin callers): parse_to_json, parse_active_to_json, parse_tool_to_json, stringify_json, format, compile_hex, decompile_hex, is_synxb_hex, diff_json.

Example (bindings/mojo/examples/demo.mojo pattern):

from std.python import Python
from synx.interop import parse_json

def main() raises:
    var j = parse_json("name Wario\nage 30\n")
    print(j)

See bindings/mojo/README.md.

Parity: Identical to synx-core because execution runs inside synx_native (Rust).

5.12 Kotlin / JVM — bindings/kotlin (JNA + synx-c)

The supported JVM integration in this repository is bindings/kotlin: SynxEngine loads synx_c through JNA. Parse results are canonical JSON String values (or ByteArray for .synxb) unless you decode them yourself.

1. Build the native library (repo root): cargo build -p synx-c --release.

2. Build / test from bindings/kotlin: set SYNX_LIB_DIR to the directory containing libsynx_c / synx_c.dll, then ./gradlew test. See bindings/kotlin/README.md.

Example:

import com.aperturesyndicate.synx.SynxEngine

val json = SynxEngine.parse("name Wario\nage 30\n")
val tool = SynxEngine.parseTool("!tool\nweb_search\n  query test\n")
val active = SynxEngine.parseActive("!active\nport:env:default:8080 PORT\n")

API (v3.6): SynxEngine.parse, parseActive, stringify, format, parseTool, diff, compile, decompile, isSynxb — mirrors bindings/c-header/include/synx.h.

Parity: Same engine as synx-core (including !active, !tool, .synxb, diff). Tooling uses JDK 17+ for Gradle; published com.aperturesyndicate:synx-kotlin may follow (use publishToMavenLocal until then).

5.13 Swift — SwiftPM + synx-c (C interop)

The supported Swift integration is bindings/swift: a Swift Package that wraps synx.h / synx-c via CSynx (module.modulemap, link "synx_c"). Types are String / Data; parse results are canonical JSON strings unless you decode yourself.

Build the C library (repo root): cargo build -p synx-c --release, then link libsynx_c when building the package (swift build -Xlinker -L… -Xlinker -lsynx_c). See bindings/swift/README.md.

Example:

import Synx

let json = try SynxEngine.parse("name Wario\nage 30\n")
print(json)

let tool = try SynxEngine.parseTool("!tool\nweb_search\n  query test\n")

API (v3.6): SynxEngine.parse, parseActive, stringify(json:), format, parseTool, diff, compile, decompile(_:), isSynxb — mirrors synx.h.

Parity: Same engine as synx-core. Sources/CSynx/synx.h must stay in sync with bindings/c-header/include/synx.h.

5.14 Lua — Zero-Dependency Parser

Installation:

Copy synx.lua into your project:

local synx = require("synx")

Usage:

local synx = require("synx")

-- Parse from string
local data = synx.parse(text)
print(data:get("server"):get("port"):as_int())  -- 8080

-- Parse from file
local data = synx.parse_file("config.synx")
print(data:get("server"):get("host"):as_str())  -- localhost

-- Full parse (mode detection)
local result = synx.parse_full(text)
print(result.mode)  -- "static" or "active"

API:

• synx.parse(text) → SynxValue
• synx.parse_full(text) → { root, mode }
• synx.parse_file(path) → SynxValue, err
• SynxValue:get(key) — child by key or 1-based index
• SynxValue:as_bool(), :as_int(), :as_float(), :as_str()
• SynxValue:len(), :keys(), :type(), :is_null()

📌 Note: The Lua parser is static-only. No active function evaluation. Works with Lua 5.1+ and LuaJIT.

5.15 Dart / Flutter — Native Parser

Installation (pubspec.yaml):

dependencies:
  synx:
    git:
      url: https://github.com/APERTURESyndicate/synx-format.git
      path: packages/synx-dart

Usage:

import 'package:synx/synx.dart';

// Parse from string
final data = Synx.parse(text);
print(data['server']['port'].asInt); // 8080

// Parse from file
final data = Synx.parseFile('config.synx');

// Full parse (mode detection)
final result = Synx.parseFull(text);
print(result.mode); // SynxMode.active

Flutter usage:

import 'package:synx/synx.dart';
import 'package:flutter/services.dart' show rootBundle;

Future<SynxValue> loadConfig() async {
  final text = await rootBundle.loadString('assets/config.synx');
  return Synx.parse(text);
}

API:

• Synx.parse(text) → SynxValue
• Synx.parseFull(text) → SynxParseResult { root, mode }
• Synx.parseFile(path) → SynxValue
• SynxValue[key] — subscript by string key or int index
• .asBool, .asInt, .asFloat, .asStr
• .length, .keys, .type, .isNull

📌 Note: The Dart parser is static-only. No active function evaluation. Requires Dart 3.0+.

5.16 PHP — Native Parser

Installation:

Copy Synx.php into your project:

require_once 'Synx.php';

Usage:

require_once 'Synx.php';

// Parse from string
$data = Synx::parse($text);
echo $data->get('server')->get('port')->asInt(); // 8080

// Parse from file
$data = Synx::loadFile('config.synx');

// Full parse (mode detection)
$result = Synx::parseFull($text);
echo $result->mode; // "static" or "active"

API:

• Synx::parse($text) → SynxValue
• Synx::parseFull($text) → SynxParseResult { root, mode }
• Synx::loadFile($path) → SynxValue
• ->get($key) — child by string key or int index
• ->asBool(), ->asInt(), ->asFloat(), ->asStr()
• ->length(), ->keys(), ->type(), ->isNull()

📌 Note: The PHP parser is static-only. No active function evaluation. Requires PHP 8.0+.

5.17 Bash / PowerShell — Shell Parsers

Bash (4.0+)

Installation:

source synx.sh

Usage:

source synx.sh

synx_parse_file "config.synx"
echo "$(synx_get server.host)"     # localhost
echo "$(synx_get server.port)"     # 8080
echo "$(synx_type server.port)"    # int
echo "$(synx_mode)"                # static

# Arrays
echo "$(synx_get items.0)"         # Sword
echo "$(synx_get items.__length)"  # 3

API:

• synx_parse "$text" — parse SYNX text
• synx_parse_file "$path" — read and parse file
• synx_get "$path" — value at dot-notation path
• synx_type "$path" — type name
• synx_mode — document mode

Note: Values are stored in flat associative arrays with dot-notation keys (e.g. server.host).

PowerShell (5.1+)

Installation:

. .\Synx.ps1

Usage:

. .\Synx.ps1

$result = Read-SynxFile "config.synx"
$result.Root.server.host           # localhost
$result.Root.server.port           # 8080 (int)
$result.Root.items[0]              # Sword
$result.Mode                       # static

API:

• ConvertFrom-Synx $text → PSCustomObject { Root, Mode }
• Read-SynxFile $path → same

Objects are [ordered]@{}, arrays are native PowerShell arrays, scalars are typed ([long], [double], [bool], [string], $null).

📌 Note: Both shell parsers are static-only. No active function evaluation.

5.18 Comparison: SYNX Directly vs JSON

By language: