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

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>.
}