oxabl.toml reference

oxabl.toml holds a project’s settings. Put it at the root of the project. Every command looks for it in the directory it works on and in each directory above it, and uses the first one it finds. Paths in the file are relative to the file.

Every table is optional except [workspace], which needs a name. A key you leave out takes its default.

[workspace]
name = "acme"

[workspace.sources]
include_paths = ["src"]
encoding = "windows-1252"

[workspace.schema]
files = ["schema/sports.df"]

[workspace.preprocessor]
proversion = "12.8"
databases = ["sports"]

[workspace.lint]
enable = ["strict.locks"]
unused-variable = "info"

[[workspace.lint.overrides]]
files = ["src/legacy/**"]
disable = ["strict"]

[workspace.style]
indent_size = 2
keyword_case = "Uppercase"

When the file has a mistake

Parsing is strict: a key oxabl doesn’t know, or a value of the wrong type, is an error.

• oxabl check refuses to run and exits 2, so a mistake can’t turn into a pass.
• oxabl format prints the same message as a warning:, then formats with the default style.

error: failed to parse oxabl.toml: TOML parse error at line 1, column 1
  |
1 | [workspace]
  | ^^^^^^^^^^^
missing field `name`

The exceptions are rule and group names in [workspace.lint]: an unknown one is a warning, that entry is ignored, and the rest of the table applies.

For completion and validation while you edit the file, oxabl schema prints its JSON Schema.

[workspace]

[workspace.sources]

Where oxabl finds your code, and how it reads it.

encoding also accepts utf8, cp1252 and latin1. Without an encoding that fits, a single-byte file can’t be read:

error: cannot read src/app/latin.p: not valid UTF-8 (invalid byte at offset 55); set `[workspace.sources] encoding` for a single-byte source

oxabl only looks where it’s told. With no include_paths, it doesn’t report names from other files as undefined, because it hasn’t looked. With paths set, a RUN target, USING import or NEW that none of them supplies is LINT0001:

src/app/caller.p:2:5: error[LINT0001]: undefined symbol `lib/missing.p`: no file on the configured search paths declares it
    2 | run lib/missing.p.
  help: check `[workspace.sources].include_paths` in `oxabl.toml`, or pass the directory with `-I`; oxabl only searches the paths it is given

[workspace.schema]

A file that can’t be read is a warning, and the run goes on without it:

warning: schema: [SCHEMA0001] cannot read schema file `nosuch.df`: No such file or directory (os error 2)

[workspace.preprocessor]

The AVM answers some preprocessor names from the machine that compiles the code. oxabl has no such machine, so you describe it here, and every &IF that reads one of these names is decided against it. The keys are written with hyphens.

proversion has no default because a tool can’t guess it. Until you set it, an &IF that reads it is decided as if it were empty, and oxabl says so:

src/lib/env.p:1:1: warning[PREPROC009]: predefined name '{&PROVERSION}' has no value — the condition is decided as if it were empty
    1 | &IF PROVERSION >= "12" &THEN
  help: set `proversion` under [workspace.preprocessor] in oxabl.toml

Without databases, the file names in [workspace.schema] stand in for the logical names (schema/ledger.df connects ledger), as a partial list. With neither, a condition that asks about a database is a guess, and oxabl reports PREPROC010. Neither warning changes the exit code of check.

[workspace.lint]

Which rules run, and at what severity.

A severity is "off", "hint", "info", "warn" (or "warning") or "error". Every severity except off fails oxabl check.

The default group is always on and can’t be turned off as a group; set its rules to off one by one. The strict.* groups are off until you enable them, and their rules are in preview.

Overrides

[[workspace.lint.overrides]]
files = ["src/legacy/**", "src/old/report.p"]
disable = ["strict"]
undefined-symbol = "warn"

Settings apply lowest first: the rule’s default, then [workspace.lint], then each override whose files match, in the order they’re written. Put broad patterns before narrow ones. Within one table, a rule’s own setting beats its group’s, and disable beats enable.

Rules

The strict.locks, strict.transactions (except TX003, TX004 and TX006) and strict.access rules report only on tables in the loaded schema, so they’re quiet without one.

[workspace.style]

How oxabl format lays out code. --style on the command line replaces this table for one run, with a preset (oestandards or consultingwerk) or a style file holding these keys at the top level.

Six keys change what oxabl format writes today:

With keyword_case = "Preserve", "AbbreviateNothing" and end_with_type write the words they add in uppercase:

DEFINE VARIABLE i as INTEGER no-undo.

The other keys are accepted and validated, so a style file written for them works, but neither oxabl format nor oxabl check acts on them yet. max_line_length and wrap_long_lines are among them: a long line stays as long as it was.

To enforce NO-UNDO today, use the lint rule TX006 (missing-no-undo) instead of require_no_undo.