63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# Lyng formatter (core, CLI, and IDE)
|
|
|
|
This document describes the Lyng code formatter included in this repository. The formatter lives in the core library (`:lynglib`), is available from the CLI (`lyng fmt`), and is used by the IntelliJ plugin.
|
|
|
|
## Core library
|
|
|
|
Package: `net.sergeych.lyng.format`
|
|
|
|
- `LyngFormatConfig`
|
|
- `indentSize` (default 4)
|
|
- `useTabs` (default false)
|
|
- `continuationIndentSize` (default 8)
|
|
- `maxLineLength` (default 120)
|
|
- `applySpacing` (default false)
|
|
- `applyWrapping` (default false)
|
|
- `LyngFormatter`
|
|
- `reindent(text, config)` — recomputes indentation from scratch (braces, `else/catch/finally` alignment, continuation indent under `(` `)` and `[` `]`), idempotent.
|
|
- `format(text, config)` — runs `reindent` and, depending on `config`, optionally applies:
|
|
- a safe spacing pass (commas/operators/colons/keyword parens; member access `.` remains tight; no changes to strings/comments), and
|
|
- a controlled wrapping pass for long call arguments (no trailing commas).
|
|
|
|
Both passes are designed to be idempotent. Extensive tests live under `:lynglib/src/commonTest/.../format`.
|
|
|
|
## CLI formatter
|
|
|
|
```
|
|
lyng fmt [--check] [--in-place|-i] [--spacing] [--wrap] <file1.lyng> [file2.lyng ...]
|
|
```
|
|
|
|
- Defaults: indent-only; spacing and wrapping are OFF unless flags are provided.
|
|
- `--check` prints files that would change and exits with code 2 if any changes are detected.
|
|
- `--in-place`/`-i` rewrites files in place (default if not using `--check`).
|
|
- `--spacing` enables the safe spacing pass (commas/operators/colons/keyword parens).
|
|
- `--wrap` enables controlled wrapping of long call argument lists (respects `maxLineLength`, no trailing commas).
|
|
|
|
Examples:
|
|
|
|
```
|
|
# check formatting without modifying files
|
|
lyng fmt --check docs/samples/fs_sample.lyng
|
|
|
|
# format in place with spacing rules enabled
|
|
lyng fmt --spacing -i docs/samples/fs_sample.lyng
|
|
|
|
# format in place with spacing + wrapping
|
|
lyng fmt --spacing --wrap -i src/**/*.lyng
|
|
```
|
|
|
|
## IntelliJ plugin
|
|
|
|
- Indentation: always enabled, idempotent; the plugin computes per-line indent via the core formatter.
|
|
- Spacing/wrapping: optional and OFF by default.
|
|
- Settings/Preferences → Lyng Formatter provides toggles:
|
|
- "Enable spacing normalization (commas/operators/colons/keyword parens)"
|
|
- "Enable line wrapping (120 cols) [experimental]"
|
|
- Reformat Code applies: indentation first, then spacing, then wrapping if toggled.
|
|
|
|
## Design notes
|
|
|
|
- Single source of truth: The core formatter is used by CLI and IDE to keep behavior consistent.
|
|
- Stability first: Spacing/wrapping are gated by flags/toggles; indentation from scratch is always safe and idempotent.
|
|
- Non-destructive: The formatter carefully avoids changing string/char literals and comment contents.
|