Format-Aware File I/O

Writing Structured Data

Simply write your data to a file path. The extension determines the format automatically.

JSON and JSON Lines

(* Pretty-printed JSON *)
Write the <users> to "./output/users.json".

(* JSON Lines - one object per line, compact *)
Write the <events> to "./logs/events.jsonl".

JSON output:

[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob" }
]

JSONL output:

{"id":1,"name":"Alice"}
{"id":2,"name":"Bob"}

YAML and TOML

(* YAML - human readable *)
Write the <config> to "./settings.yaml".

(* TOML - configuration files *)
Write the <config> to "./settings.toml".

CSV and TSV

(* CSV with header row *)
Write the <report> to "./export/report.csv".

(* TSV - tab separated *)
Write the <data> to "./export/data.tsv".

CSV output:

id,name,email
1,Alice,alice@example.com
2,Bob,bob@example.com

XML

(* XML - variable name becomes root element *)
Write the <products> to "./catalog/products.xml".

XML output: (note: <products> is the root)

<?xml version="1.0" encoding="UTF-8"?>
<products>
  <item>
    <id>1</id>
    <name>Widget</name>
  </item>
</products>

Other Formats

(* Markdown table *)
Write the <summary> to "./docs/summary.md".

(* HTML table *)
Write the <report> to "./output/report.html".

(* SQL INSERT statements *)
Write the <users> to "./backup/users.sql".

(* Log file with timestamp *)
Write the <message> to "./app.log" with "Server started".

(* Environment file - uppercase keys with underscore nesting *)
Write the <config> to "./.env".

(* Plain text key=value *)
Write the <config> to "./output/config.txt".

Reading Structured Data

When reading files, the extension determines how content is parsed back into structured data.

(* JSON - parsed to object/array *)
Read the <config> from "./settings.json".

(* JSONL - parsed to array of objects *)
Read the <events> from "./logs/events.jsonl".

(* CSV - parsed to array with headers as keys *)
Read the <records> from "./data.csv".

(* YAML - parsed to object/array *)
Read the <settings> from "./config.yaml".

Bypass Parsing with as String

(* Read raw content without parsing *)
Read the <raw-json: String> from "./data.json".

Format Reference

URL Format Detection

When reading from URLs (see HTTP Services), the format is detected from the HTTP Content-Type header instead of the file extension.

(* JSON API - auto-parsed based on Content-Type header *)
Read the <users> from the <url: "https://api.example.com/users">.
(* users is now a structured object *)
Extract the <name> from the <users: 0.name>.

(* Bypass parsing with as String *)
Read the <raw: String> from the <url: "https://api.example.com/users">.

CSV/TSV Options

CSV and TSV formats support additional options via the with clause:

(* Custom delimiter *)
Write the <data> to "./export.csv" with { delimiter: ";" }.

(* Without header row *)
Write the <data> to "./export.csv" with { header: false }.

(* Read with custom options *)
Read the <data> from "./import.csv" with { delimiter: ";" }.

Complete Example

Here's a complete example that reads data from one format and exports to multiple formats:

(Application-Start: Multi-Format Export) {
    (* Create sample data *)
    Create the <users> with [
        { "id": 1, "name": "Alice", "email": "alice@example.com" },
        { "id": 2, "name": "Bob", "email": "bob@example.com" },
        { "id": 3, "name": "Charlie", "email": "charlie@example.com" }
    ].

    (* Export to multiple formats - same data, different files *)
    Write the <users> to "./output/users.json".
    Write the <users> to "./output/users.jsonl".
    Write the <users> to "./output/users.yaml".
    Write the <users> to "./output/users.csv".
    Write the <users> to "./output/users.xml".
    Write the <users> to "./output/users.md".

    Log "Exported to 6 formats!" to the <console>.

    (* Read back and verify *)
    Read the <json-data> from "./output/users.json".
    Read the <csv-data> from "./output/users.csv".

    Return an <OK: status> for the <export>.
}