Formatting source
In AEL, the Agent Engineering Language, ael fmt (command names may change before launch) will format your source files in one consistent style, so every project reads the same way and a review shows only real changes.
Status
Planned for AEL Beta 0.0.1. AEL is not available yet.
Usage
ael fmt
ael fmt src/agents/support.agent.ael
ael fmt --check
ael fmt --check --json
| Argument or option | Meaning |
|---|---|
[path] | A project folder or one .ael file. Without a path, the project in the current folder. |
--check | Write nothing; list the files that would change. |
--json | A machine-readable report of the files changed, or that would change. |
What it formats
It will format:
- Every source file of the project:
main.ael,pack.ael,metadata.aeland every component file. - A component and its extension files as one unit. Naming one extension file will format 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 will stay exactly as you wrote it. - Your files.
ael fmtwill never split a file, move code from one file to another or move a header. - The size limit. If formatting would push a file past the size limit, the file will be left exactly as it was and reported, with a suggestion to move helpers into an extension file.
Line breaks will be written as line feeds.
Formatting a formatted file will change nothing. Before writing, ael fmt will format its own result a second time, and it will write nothing at all unless both passes agree.
Checking formatting
ael fmt --check will build the same plan, write nothing, and list the files that would change. It will end with a failure status when any file would change, so an automated build can require formatted source:
ael fmt --check
How files are written
- Nothing will be written until every selected file has been formatted and checked.
- Files that would not change will not be touched.
- Each file will be replaced in one step, so nothing ever reads a half-written file.
- If a file changes while
ael fmtis working, that file will be left alone and reported.
Files will be written one after another; there will be no single step for the whole project. If writing stops part-way, for example because a disk is full, every file already written will be complete and formatted, the report will list them, and running ael fmt again will finish the rest.
Formatting will be separate from checking
ael fmt will read your files' structure, not their meaning. A formatted file may still fail ael check, and a file that formats cleanly will not have been type-checked or built.
Related
- Syntax basics: the layout the formatter writes.
- Checking source: checking will be a separate step.