Convert & Cast

Five distinct operations: CONVERT transforms files and media between formats. CAST coerces a value between OcaltQL native types. ENCODE and DECODE change data representation. FORMAT NUMBER controls numeric display. PARSE deserialises a structured string into a native OcaltQL value. FORMAT DATE and FORMAT TIME are documented on the Date & Time page.

CONVERT

Converts a file or media asset from one format to another. The source can be a namespace path or a URL. AS writes to a specific path. SET captures the output path, written to /root/converted/{original_name}.{new_ext} — for example, converting photo.png to JPG produces /root/converted/photo.jpg.

Image

Supported formats
JPG  •  PNG  •  WEBP  •  GIF  •  BMP  •  TIFF  •  AVIF  •  ICO  •  SVG
Convert image — explicit output path
CONVERT IMAGE "/root/photo.png" TO JPG AS "/root/new.jpg"
Convert image — system assigned path
CONVERT IMAGE "/root/photo.png" TO WEBP SET ?path
AFTER EMIT ?path
(* Output: /root/converted/photo.webp *)
Convert image from URL
CONVERT IMAGE "https://example.ocalt.com/img/photo.tiff" TO PNG AS "/root/photo.png"
Async — SET PROMISE
CONVERT IMAGE "/root/photo.png" TO JPG SET PROMISE ?job
AFTER WAIT FOR ?job SET ?path
AFTER EMIT ?path
(* Conversion runs in the background; WAIT FOR blocks until it completes *)

Document

Supported formats
PDF  •  DOCX  •  DOC  •  RTF  •  ODT  •  TXT  •  HTML  •  XLSX  •  CSV  •  PPTX
Examples
CONVERT DOCUMENT "/root/report.docx" TO PDF AS "/root/report.pdf"
AFTER CONVERT DOCUMENT "/root/file.rtf" TO DOCX AS "/root/file.docx"
AFTER CONVERT DOCUMENT "/root/data.xlsx" TO CSV AS "/root/data.csv"
AFTER CONVERT DOCUMENT "https://example.ocalt.com/files/file.odt" TO PDF AS "/root/file.pdf"
Async — SET PROMISE
CONVERT DOCUMENT "/root/report.docx" TO PDF SET PROMISE ?job
AFTER WAIT FOR ?job SET ?path
AFTER EMIT ?path
(* Document conversion supports PROMISE identically across every format pair *)

Video

Supported formats
MP4  •  AVI  •  MKV  •  MOV  •  WEBM  •  FLV  •  3GP  •  GIF
Examples
CONVERT VIDEO "/root/clip.mp4" TO AVI AS "/root/clip.avi"
AFTER CONVERT VIDEO "/root/clip.mp4" TO GIF AS "/root/anim.gif"
AFTER CONVERT VIDEO "/root/anim.gif" TO MP4 AS "/root/anim.mp4"
AFTER CONVERT VIDEO "/root/clip.mov" TO WEBM AS "/root/clip.webm"
AFTER CONVERT VIDEO "/root/clip.mkv" TO 3GP AS "/root/clip.3gp"
Async — SET PROMISE
CONVERT VIDEO "/root/clip.mp4" TO AVI SET PROMISE ?job
AFTER WAIT FOR ?job SET ?path
AFTER EMIT ?path
(* Useful for larger video files where transcoding takes longer than the request should block for *)

Audio

Supported formats
MP3  •  WAV  •  FLAC  •  AAC  •  OGG  •  M4A  •  OPUS
Examples
CONVERT AUDIO "/root/track.wav" TO MP3 AS "/root/track.mp3"
AFTER CONVERT AUDIO "/root/track.flac" TO AAC AS "/root/track.aac"
AFTER CONVERT AUDIO "/root/track.ogg" TO WAV AS "/root/track.wav"
AFTER CONVERT AUDIO "/root/track.mp3" TO OPUS AS "/root/track.opus"
Async — SET PROMISE
CONVERT AUDIO "/root/track.wav" TO MP3 SET PROMISE ?job
AFTER WAIT FOR ?job SET ?path
AFTER EMIT ?path

CAST

Coerces a value to a different OcaltQL native type. The original variable is not modified — the result is always captured with SET.

Cast to STRING
NUMBER 42 SET ?n
AFTER CAST ?n AS STRING SET ?s
AFTER EMIT ?s
(* Output: "42" as a string value *)
Cast to NUMBER
STRING "3.14" SET ?s
AFTER CAST ?s AS NUMBER SET ?n
AFTER CALCULATE ?n * 2 SET ?result
AFTER EMIT ?result
(* Output: 6.28 *)
Cast to BOOL
STRING "true" SET ?s
AFTER CAST ?s AS BOOL SET ?b
AFTER IF ?b IS TRUE
OPEN
  EMIT "it is true"
CLOSE
Cast to DATE — from Unix timestamp or ISO 8601
NUMBER 1751356800 SET ?ts
AFTER CAST ?ts AS DATE SET ?d
AFTER EMIT ?d
(* Output: 2025-07-01 00:00:00 *)
Cast to DATE — from custom format string
STRING "01/07/2026" SET ?raw
AFTER CAST ?raw AS DATE FROM "d/m/Y" SET ?d
AFTER EMIT ?d
(* Output: 2026-07-01 00:00:00 *)

Cast to JSON or OQLOBJECT — objects

Objects require an explicit target format — there is no bare AS STRING for this type. AS JSON produces standard JSON text. AS OQLOBJECT produces the object’s native OcaltQL source form, wrapped in brackets — [NEW OBJECT [...]] — ready to be fed back through PARSE ?text AS OQLOBJECT. See Arrays & Objects for the full native-object-storage explanation.

Cast to JSON
NEW OBJECT ["name" AS "Alice" AND "age" AS 30] SET ?user
AFTER CAST ?user AS JSON SET ?jsontext
AFTER EMIT ?jsontext
(* Output: {"name": "Alice", "age": 30} *)
Cast to OQLOBJECT
NEW OBJECT ["name" AS "Alice" AND "age" AS 30] SET ?user
AFTER CAST ?user AS OQLOBJECT SET ?oqltext
AFTER EMIT ?oqltext
(* Output: [NEW OBJECT ["name" AS "Alice" AND "age" AS 30]] *)
Round trip — JSON in, OQLOBJECT out, and back
STRING '{"name":"Alice"}' SET ?raw
AFTER PARSE ?raw AS JSON SET ?obj
AFTER CAST ?obj AS OQLOBJECT SET ?oqltext
AFTER EMIT ?oqltext
(* Output: [NEW OBJECT ["name" AS "Alice"]] *)
AFTER PARSE ?oqltext AS OQLOBJECT SET ?obj2
AFTER CAST ?obj2 AS JSON SET ?jsontext
AFTER EMIT ?jsontext
(* Output: {"name": "Alice"} *)

ENCODE & DECODE

Change the representation of a value without changing its type. Every ENCODE scheme has a matching DECODE. ENCODE always produces a string; DECODE produces a string when the data is text and a bytes value when it is not.

DECODE returns bytes when the data is not text. Base64 or hex that decodes to valid UTF-8 comes back as a string, exactly as before. Anything else — a PNG, a PDF, a zip — comes back as a bytes value, OcaltQL's binary type. A bytes value prints as base64, reports its size through LENGTH, indexes one byte at a time with ?b(0), and is written to disk by FILE WRITE "path" CONTENT ?b with no BASE64 modifier needed — it is already binary. Passing it to ENCODE re-encodes the raw bytes rather than their printed form.
BASE64
STRING "hello world" SET ?s
AFTER ENCODE ?s AS BASE64 SET ?enc
AFTER EMIT ?enc
(* Output: aGVsbG8gd29ybGQ= *)

AFTER DECODE ?enc AS BASE64 SET ?dec
AFTER EMIT ?dec
(* Output: hello world *)
URL
STRING "hello world & more" SET ?s
AFTER ENCODE ?s AS URL SET ?enc
AFTER EMIT ?enc
(* Output: hello+world+%26+more *)

AFTER DECODE ?enc AS URL SET ?dec
AFTER EMIT ?dec
(* Output: hello world & more *)
HEX
STRING "ocalt" SET ?s
AFTER ENCODE ?s AS HEX SET ?enc
AFTER EMIT ?enc
(* Output: 6f63616c74 *)

AFTER DECODE ?enc AS HEX SET ?dec
AFTER EMIT ?dec
(* Output: ocalt *)

FORMAT NUMBER

Controls the display representation of a number. Produces a string. Does not alter the original value. FORMAT DATE and FORMAT TIME are documented on the Date & Time page.

Decimal places
NUMBER 3.14159 SET ?n
AFTER FORMAT NUMBER ?n WITH 2 DECIMALS SET ?s
AFTER EMIT ?s
(* Output: 3.14 *)

AFTER FORMAT NUMBER ?n WITH 0 DECIMALS SET ?s
AFTER EMIT ?s
(* Output: 3 *)
Integer
NUMBER 9.99 SET ?n
AFTER FORMAT NUMBER ?n AS INTEGER SET ?s
AFTER EMIT ?s
(* Output: 9 — truncates, does not round *)
Scientific notation
NUMBER 123456789 SET ?n
AFTER FORMAT NUMBER ?n AS SCIENTIFIC SET ?s
AFTER EMIT ?s
(* Output: 1.23456789e8 *)
Currency
NUMBER 1234.5 SET ?n
AFTER FORMAT NUMBER ?n AS CURRENCY SET ?s
AFTER EMIT ?s
(* Output: 1,234.50 *)

PARSE

Deserialises a structured string into a native OcaltQL value. The result type depends on the format: objects and arrays where the format supports them, a native HTML tree for HTML, and a rendered HTML string for MARKDOWN.

JSON
STRING '{"name":"Alice","age":30}' SET ?raw
AFTER PARSE ?raw AS JSON SET ?obj
AFTER EMIT ?obj("name")
(* Output: Alice *)
OQLOBJECT — native OcaltQL source text
STRING '[NEW OBJECT ["name" AS "Alice" AND "age" AS 30]]' SET ?raw
AFTER PARSE ?raw AS OQLOBJECT SET ?obj
AFTER EMIT ?obj("name")
(* Output: Alice *)
CSV
STRING "name,age
Alice,30
Bob,25" SET ?raw
AFTER PARSE ?raw AS CSV SET ?rows
AFTER EMIT ?rows(0)("name")
(* Output: Alice *)
XML
STRING "<user><name>Alice</name><age>30</age></user>" SET ?raw
AFTER PARSE ?raw AS XML SET ?obj
AFTER EMIT ?obj("name")
(* Output: Alice *)
YAML
STRING "name: Alice
age: 30" SET ?raw
AFTER PARSE ?raw AS YAML SET ?obj
AFTER EMIT ?obj("name")
(* Output: Alice *)
TOML
STRING `[server]
host = "localhost"
port = 8080` SET ?raw
AFTER PARSE ?raw AS TOML SET ?obj
AFTER EMIT ?obj("server")("host")
(* Output: localhost *)
Query string
STRING "name=Alice&age=30&city=Cape+Town" SET ?raw
AFTER PARSE ?raw AS QUERY STRING SET ?obj
AFTER EMIT ?obj("city")
(* Output: Cape Town *)
HTML — produces native HTML tree
FETCH "https://example.ocalt.com" SET ?raw
AFTER PARSE ?raw AS HTML SET ?doc
AFTER NEW HTML NODE SET ?para
OPEN
HTML "p" TEXT "Injected"
CLOSE
AFTER HTML APPEND ?para INTO ?doc WHERE TAG "body"
AFTER EMIT ?doc
Markdown — produces rendered HTML string
FILE READ "/root/readme.md" SET ?md
AFTER PARSE ?md AS MARKDOWN SET ?html
AFTER EMIT ?html
INCLUDE & SIDELOAD →