Data formats¶
Reading values from text, and writing and reading them in other formats: JSON, CSV, XML, the query of a URL, base 64 and hexadecimal, checksums and compressed bytes.
load¶
Reads Trebol source text, or a file of it, into values: the value itself, or a block when there are several.
load source
source(string!binary!file!url!)/all: Gives a block even for one value
to-json¶
Writes a value as JSON text.
to-json value
value(any-type!)
load-json¶
Reads JSON text into Trebol values: objects as maps, lists as blocks.
load-json source
source(string!binary!)
load-csv¶
Reads CSV text into a block of rows, each a block of strings.
load-csv data
data(string!binary!)/with delimiter(char!string!): Another delimiter than a comma/header: The first line names the columns; gives columns unless /as-records/as-columns: A map of columns: name and block of values/as-records: A block of maps, one per row; implies /header/flat: One block with every field/trim: Leave out spaces around fields/quote qt-char(char!): Another quote character than a double quote
Every field is a string!, as in Red: "01001" stays a postal code, and the program turns what it means as
numbers or dates with to. Rows end at CRLF, LF or CR; a field in double quotes can hold the delimiter, line
breaks and quotes written twice (""). Empty lines and a byte order mark at the start are left out. A quote
that never closes is a syntax error.
Refinement |
What it gives |
|---|---|
none |
a block of rows, each a block of strings |
|
the first line names the columns: a map of columns, or records with |
|
a map of each column’s name and a block of its values; without |
|
a block of maps, one per row, keyed by the first line; a missing field is |
|
one block with every field |
|
another delimiter: a char such as |
|
leaves out the spaces around fields |
|
another quote character |
Column names are string keys, as in Red: select row "Name", or row/("Name"); a table finds them by its
column words. A name that repeats gets " 2", " 3" after it.
to-csv¶
Writes CSV text from rows: a block of blocks, of maps or objects (a header from their keys), a flat block with /skip, or a map of columns.
to-csv data
data(block!map!object!)/with delimiter(char!string!): Another delimiter than a comma/skip size(integer!): A flat block, so many fields to a row/quote qt-char(char!): Another quote character than a double quote/language lang(word!string!): Dates and amounts as a language writes them, and a semicolon where its decimals have a comma
What it takes: a block of blocks (each a row); a block of maps or objects, with a header line from their
keys in the order first seen; a flat block with /skip size; or a map of columns, each key with a block of
values. A block of plain values is one row. none is an empty field. Dates are written in ISO 8601, as
2026-11-10 or 2026-11-10 09:30:00, and amounts as plain numbers, 1250.50, as to-json writes them:
every program and spreadsheet reads them. Other values are written as form writes them. A field is put in quotes when it holds the delimiter, a quote or a line break, or starts or
ends with a space. Every row ends with a new line. /with and /quote work as in load-csv.
/language 'es writes dates, times, decimals, percents and amounts as that language does, as
format-local does (11/11/2026, 1250,50 €, 1,5), for a person who opens the file in a spreadsheet
in that language. Integers stay as they are, so an id gains no thousands separator. Where the language
writes decimals with a comma, the delimiter is a semicolon, which is what spreadsheets in that language
expect; /with still chooses another.
load-xml¶
Reads XML text into a block of nodes, each its name, content and attributes; a text is none, the text and none.
load-xml source
source(string!binary!)
XML loads in the shape of Red’s community codec: every node is three values, its name, its
content and its attributes. An element’s content is a block of nodes, empty for <linea/>; its
attributes are a map, or none when it has none. A text is none, the text and none, so
foreach [name content atts] content [...] walks any content:
>> load-xml {<factura id="7"><cliente nif="B123">Ana & Co</cliente><linea/></factura>}
== [factura [cliente [none "Ana & Co" none] #(nif: "B123") linea [] none] #(id: "7")]
Names are words when they read as one, as the keys of load-json, and strings otherwise: "fe:Facturae",
"xmlns:fe". Entities (&, é) and CDATA sections load as text; an entity XML does not define
stays as written. Comments, processing instructions, the <?xml ...?> line, the DOCTYPE and the spaces only
between tags are left out. A tag that is never closed, or closed by another, is a syntax error that says
on which line.
In a block written in code, none is a word, not the none value that load-xml puts there: both mold
the same, but they are not equal. Compare loaded XML with none? name.
to-xml¶
Writes XML text from a block of nodes, each its name, content and attributes, as load-xml gives them.
to-xml nodes
nodes(block!)/declaration: Start with the <?xml …?> line a whole document needs
Writes the nodes as load-xml gives them, so to-xml load-xml text is the same XML without the parts it
leaves out. Text is escaped (&, <, >, and " in attributes); an element with no content
is written <linea/>. In code, the word none counts as the none value, the attributes can be a map, an
object or a block of names and values, and the content can be a single value instead of a block, which is
its text:
>> to-xml [total 1250.5 [currency "EUR"] due 11-Nov-2026 none]
== {<total currency="EUR">1250.5</total><due>2026-11-11</due>}
Values are written as to-csv writes them: dates in ISO 8601, amounts as plain numbers. An attribute whose
value is none is left out. /declaration starts with <?xml version="1.0" encoding="UTF-8"?>, which a
whole document needs; without it the text can also go inside other XML.
to-query¶
Writes names and values as the query of a URL: q=caf%C3%A9&page=2.
to-query values
values(map!object!block!)
Writes each name and value as name=value, joined by &, with what a URL cannot hold as %xx escapes. A block
value gives the name once for each of its values, and a none value is left out. Values are written as to-csv
writes them: dates in ISO 8601, amounts as plain numbers.
>> to-query #(q: "café" tags: ["a" "b"] page: 2)
== "q=caf%C3%A9&tags=a&tags=b&page=2"
fetch/with url [query: #(...)] adds the same text to the URL it requests.
load-query¶
Reads the query of a URL as a map of strings; a name given twice holds a block.
load-query source
source(any-string!)
Takes the text after ?, or a whole URL, and gives a map. Names that read as words are words, the rest stay
strings; every value is a string!, as in load-csv. A name given more than once holds a block of its values, a
name with no = holds "", and + is a space, as forms send it.
>> load-query http://shop.example/search?q=caf%C3%A9+con+leche&tag=a&tag=b
== #(q: "café con leche" tag: ["a" "b"])
enbase¶
Writes bytes as text in base 64, or another base.
enbase value
value(binary!any-string!)/base base-value(integer!): 2, 16 or 64
debase¶
Reads bytes written as text in base 64, or another base.
debase value
value(any-string!binary!)/base base-value(integer!): 2, 16 or 64
to-hex¶
The value in hexadecimal, as an issue.
to-hex value
value(integer!tuple!)/size len(integer!): Use this many digits
enhex¶
Writes the characters a URL cannot hold as %xx escapes.
enhex value
value(any-string!)/uri: Write spaces as +, as forms send them
What stays as it is depends on the value, as in R3: in a url! or a file!, every character a URL may hold
(/ ? : @ & = + $ , ; # among them); in other text, only letters, digits and - _ . ! ~ * ' ( ), so the text can
go inside one part of a URL. /uri writes spaces as +.
dehex¶
Turns %xx escapes in a string or URL back into characters.
dehex value
value(any-string!)
checksum¶
A checksum or hash of the bytes: md5 sha1 sha256 give a binary, crc32 adler32 an integer.
checksum data method
data(binary!any-string!)method(word!)
compress¶
Compresses bytes, or text as UTF-8, into a binary.
compress data method
data(binary!string!)method(word!): gzip, zlib or deflate
The methods are R3’s and Red’s: gzip (the .gz file format), zlib (what HTTP calls deflate) and
deflate (the bare stream, as inside a ZIP file). What one writes, the others read: R3 decompresses what Trebol
compresses, and the other way round, although the bytes need not be the same. The browser does the work, so a
program waits for it as it does for fetch.
>> to string! decompress compress "a long text, a long text, a long text" 'gzip 'gzip
== "a long text, a long text, a long text"
decompress¶
The bytes that compress was given.
decompress data method
data(binary!)method(word!): gzip, zlib or deflate
Bytes that are not compressed with that method are a script/bad-compression error.