ek9_format

Rewrites the file in canonical EK9 style (indentation, spacing, blank-line and line-break conventions); answers status, edits[] (one per changed line) and summary, an unparseable file as conflicts[] (source-not-parseable).

Category: Editor · Compare: Reformat Code (IntelliJ Ctrl+Alt+L)

When to use it

'Reformat customer.ek9 to canonical style' is one call with file - the whole file is re-rendered, never a region, and nothing the code does changes.

When not to use it

Details

Deterministic and idempotent: format-twice yields byte-identical output. edits[] carries one REPLACE per changed line, INSERT per added line, DELETE per removed line, and doubles as a training signal for canonical EK9 style. A file that does not parse is repaired first where each fault has exactly one reading (tabs, indent width, shebang, comma-separated parameters, ...), each repair in corrected[]. The only conflict kind is 'source-not-parseable' (a syntax error with no one-reading repair - resolve via ek9_compile first).

Arguments

ArgumentTypeRequiredWhat it is
filestringyesThe .ek9 source file to format (workspace-relative; an absolute path inside the workspace is accepted).

It also takes the arguments every tool takes.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it. 3 of the 4 recorded are shown.

Format dry run shape

Request

{
  "dryRun" : true,
  "file" : "seed.ek9"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 0,
    "lineCount" : 0,
    "touchesPublicApi" : false,
    "touchesTests" : false
  },
  "status" : "ready",
  "summary" : "File seed.ek9 is already canonical - no changes",
  "workspaceHash" : "<workspace-hash>",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Format refuses unparseable

Request

{
  "file" : "broken.ek9"
}

Response

{
  "conflicts" : [ {
    "file" : "broken.ek9",
    "kind" : "source-not-parseable",
    "reason" : "Force format: the source still does not parse - line 7: unexpected '<-' expecting ')'"
  } ],
  "edits" : [ ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 0,
    "lineCount" : 0,
    "touchesPublicApi" : false,
    "touchesTests" : false
  },
  "status" : "conflicts",
  "summary" : "Formatter cannot parse broken.ek9",
  "workspaceHash" : "<workspace-hash>",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Format repairs one reading slips

Request

{
  "file" : "slips.ek9"
}

Response

{
  "conflicts" : [ ],
  "corrected" : [ "tabs used for layout replaced by two spaces each - EK9 is space-indented (a tab inside a String or a comment is kept)", "line 7: '-> count as Integer, unit as String' -> a bare '->' and one parameter per line (2 lines) - EK9 never separates parameters with commas" ],
  "edits" : [ {
    "after" : "      ->",
    "before" : "      -> count as Integer, unit as String",
    "endLine" : 7,
    "file" : "slips.ek9",
    "startLine" : 7,
    "type" : "replace"
  }, {
    "after" : "        count as Integer",
    "before" : "      <- rtn as String: `${count} ${unit}`",
    "endLine" : 8,
    "file" : "slips.ek9",
    "startLine" : 8,
    "type" : "replace"
  }, {
    "after" : "        unit as String",
    "before" : "",
    "endLine" : 9,
    "file" : "slips.ek9",
    "startLine" : 9,
    "type" : "replace"
...

Cut short here: 72 more lines. The whole recorded call.

See also