Browse the documentation

Early preview

Formatting source

oel fmt formats your source files in one consistent style, so every project reads the same way and a review shows only real changes.

Usage

oel fmt
oel fmt src/agents/support.agent.oel
oel fmt --check
oel fmt --check --json
Argument or optionMeaning
[path]A project folder or one .oel file. Without a path, the project in the current folder.
--checkWrite nothing; list the files that would change.
--jsonA machine-readable report of the files changed, or that would change.

What it formats

It formats:

  • Every source file of the project: main.oel, pack.oel, metadata.oel and every component file.
  • A component and its extension files as one unit. Naming one extension file formats the whole component, all of its files or none of them.

What it keeps

  • Comments, strings and prompt text, byte for byte. A # or a backtick inside a string stays exactly as you wrote it.
  • Your files. oel fmt never splits a file, moves code from one file to another or moves a header.
  • The size limit. If formatting would push a file past the size limit, the file is left exactly as it was and reported, with a suggestion to move helpers into an extension file.

Line breaks are written as line feeds.

Formatting a formatted file changes nothing. Before writing, oel fmt formats its own result a second time, and it writes nothing at all unless both passes agree.

Checking formatting

oel fmt --check builds the same plan, writes nothing, and lists the files that would change. It ends with a failure status when any file would change, so an automated build can require formatted source:

oel fmt --check

How files are written

  • Nothing is written until every selected file has been formatted and checked.
  • Files that would not change are not touched.
  • Each file is replaced in one step, so nothing ever reads a half-written file.
  • If a file changes while oel fmt is working, that file is left alone and reported.

Files are written one after another; there is no single step for the whole project. If writing stops part-way, for example because a disk is full, every file already written is complete and formatted, the report lists them, and running oel fmt again finishes the rest.

Formatting is separate from checking

oel fmt reads your files' structure, not their meaning. A formatted file may still fail oel check, and a file that formats cleanly has not been type-checked or built.