lyng/docs/formatter.md

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.