Layouts: fixed-width and multi-record files

Many files exchanged between systems are text with no column names: each line is a record, and which characters of it hold which field is written in a manual. Bank files (CNAB 240), tax files (SPED), and the SDF export of dBase and Clipper are like this. A layout tells Xylem where each field is, and the viewer then shows the file as a table: one sheet per kind of record, each row starting with its line in the file.

Opening a file through a layout

Xylem recognizes some files by their first line and opens them as a table on its own, with V and in Autoview (F7). The note says which layout it used: Layout: FEBRABAN CNAB 240 — Padrão Geral · K changes it. For any other file, press K.

The sheets come in the order each kind of record first appears in the file: 0 - Header de Arquivo (1), 3A - Segmento A (420)… A line that matches no record goes to the sheet ! No record type, whole. The first column, #line, is the line in the file, which is how validators of banks and of the tax authorities point to an error. When a field has codes with a meaning, the last line of the grid shows it: Content: 2 — Retorno (Banco → Cliente).

Values are read as the layout says: codes keep their zeros (00012345), dates become 2026-11-09, times 14:30:00, and amounts keep their exact decimal places (1234.50); nothing is rounded. A value that is not what the layout says (letters in a number, the 31st of February) shows as written, and i counts them.

Checks of the totals

Trailers carry totals: the lines of a batch, the number of batches, the sum of the payments. Xylem counts and adds them while reading, in integers, and says in i which agree and which do not, with the line, what the file says and what was counted. When one disagrees, the header says so: 1 check failed: i shows. A file read only in part (stopped by Esc or the time limit) has no checks.

Where layouts come from

A layout file in the folder being browsed is never read on its own: a downloaded or extracted folder could bring one made to deceive. When you pick it, it is read as strictly as the data (see Security below).

The catalog has, for now:

The layouts/ folder of the repository lists what is planned and how to contribute a layout, with no Rust involved.

SDF from a .dbf

COPY TO file SDF in dBase and Clipper writes the records side by side, each field with its width. In K, a .dbf next to the file (or one given with F2) gives its layout: the fields in order, dates as YYYYMMDD, numbers with a point. Memo fields are not exported by SDF and are left out.

Writing a layout

A layout is a TOML file whose name ends in .xlayout.toml. A positional one:

schema = 1
name = "Customers of the old system"
line_length = 40
[discriminator]
pos = [1, 1]
[[records]]
id = "0"
name = "Header"
role = "header"
fields = [
  { name = "type", pos = [1, 1], type = "code" },
  { name = "created", pos = [2, 9], type = "date", format = "YYYYMMDD" },
  { pos = [10, 40], type = "filler" },
]
[[records]]
id = "1"
name = "Customer"
fields = [
  { name = "type", pos = [1, 1], type = "code" },
  { name = "code", pos = [2, 7], type = "code" },
  { name = "name", pos = [8, 30], type = "text" },
  { name = "balance", pos = [31, 40], type = "decimal", decimals = 2, sign = "trailing" },
]

Positions are 1-based and inclusive: pos = [8, 30] is from the 8th to the 30th character. start = 8, len = 23 says the same, and len next to pos must agree with it, which catches typing mistakes. With strict_positions (on by default), the fields of a record must cover the whole line, with no gap and no overlap: name the empty parts as filler.

Each [[records]] has an id (its code for the discriminator; ids adds more codes), a name, a role (header, batch_header, detail, batch_trailer or trailer) and its fields. When the code alone does not tell records apart, match adds conditions on the line, and batch_match conditions on the line of its batch header: in CNAB 240, segment A of a payment and of a debit differ only by the operation in the batch header. A condition is a place (pos or col) and one of value = "3", in = ["1", "2"] or regex = "^[0-9]+$". Among records with the same code, the one with more conditions is tried first.

COBOL copybooks (copybook = ...), EBCDIC and packed numbers (COMP-3) are planned, and not read yet.

Security

Both the data and a layout picked from outside your folder can be hostile. A layout is read as strictly as data: at most 1 MiB, any unknown key or type is refused, every position and size is checked, names cannot have control or text direction characters, and records, fields, codes, conditions and regular expressions have limits. Regular expressions run in linear time. A layout cannot read other files: copybook is refused for now.

The data is read with the limits of the table mode: 3 s (100 ms in Autoview), 50,000 rows per sheet, 256 columns, and lines over 512 KiB are not split into fields. Esc stops the reading. Cells are made safe for the terminal like any other: control and text direction characters show as ·.

See also: the viewer.