ek9_rename_symbol

Renames a symbol and every workspace reference to it atomically across all files (references blocks and `${...}` holes included); answers status, edits[] per site and conflicts[] (name-collision-in-target-scope, convention-mismatch, symbol-not-renameable).

Category: Editor · Compare: Refactor → Rename (IntelliJ) / LSP Rename Symbol

When to use it

'Rename Shape to Polygon everywhere' is one call with symbol:'Shape', newName:'Polygon' - no file or line needed (a member is 'Shape.area'; a local or parameter needs the file). Use it for a top-level construct, a member, a parameter or a local plus EVERY workspace reference, atomically.

When not to use it

Operators (==, <=>, $, ...) - fixed contracts, cannot be renamed; use ek9_safe_delete + ek9_add_operator.
Changing a construct's MODULE rather than its name — use ek9_move_construct (mode=cross-module).
Renaming the .ek9 FILE, not a symbol — use ek9_rename_file (module identity is the 'defines module' line, not the path).
Renaming a record/component FIELD specifically — ek9_rename_field is the field-scoped anchor; this tool handles fields too, but rename_field is the precise path.

Details

Collision, casing-convention and banned-identifier checks run before any rewrite; a colliding newName returns status:'conflicts' (kind 'name-collision-in-target-scope') — inspect, don't silently retry. The dry-run runs a scratch-workspace compile, so a semantically unsafe rename surfaces as status:'would-fail' before any disk write. Casing convention is enforced per symbol kind: PascalCase for types, camelCase for members/locals. alsoRename renames further symbols in the SAME changeset (the IDE's Find and Replace in symbols mode): any conflict refuses them all, and two on one line are rewritten together.

Arguments

Argument	Type	Required	What it is
`alsoRename`	array of object		OPTIONAL further symbols renamed in the same changeset, each {file, line, column, newName}: a place the symbol is written (its declaration or a reference; column 0-based) and its new name. Any conflict refuses them all.
`column`	integer		0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from `ek9_inspect_symbol_at_cursor` verbatim.
`file`	string		The .ek9 file containing the symbol's declaration (or a reference to it) - OPTIONAL when symbol is a construct name or 'Type.member'; required for a local or a parameter.
`line`	integer		1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use `ek9_read_file`(lineNumbers:true).
`newName`	string	yes	The new name. Must be a valid EK9 identifier honouring the symbol kind's casing convention (PascalCase for types, camelCase for members/locals) and not in EK9's banned non-descriptive set (temp/flag/data/value/...).
`symbol`	string	yes	A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there.

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 17 recorded are shown.

Rename symbol operator error

Request

{
  "column" : 7,
  "file" : "main.ek9",
  "line" : 13,
  "newName" : "isReady"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ ],
  "error" : {
    "message" : "Operators cannot be renamed — their identity IS the operator symbol. Use ek9_safe_delete + ek9_add_operator to replace"
  },
  "meta" : {
    "serverMs" : "<timing>"
  },
  "status" : "error",
  "summary" : "Operators cannot be renamed — their identity IS the operator symbol. Use ek9_safe_delete + ek9_add_operator to replace",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Rename symbol dry run none

Request

{
  "column" : 5,
  "dryRun" : true,
  "file" : "util.ek9",
  "line" : 5,
  "newName" : "formatGreeting",
  "verbosity" : "none"
}

Response

{
  "conflicts" : [ ],
  "editCount" : 2,
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "high",
    "fileCount" : 2,
    "lineCount" : 2,
    "touchesPublicApi" : true,
    "touchesTests" : false
  },
  "status" : "ready",
  "summary" : "Would rename function helper → formatGreeting (1 declaration + 1 reference across 2 files)",
  "workspaceHash" : "<workspace-hash>",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Rename symbol banned identifier error

Request

{
  "column" : 7,
  "file" : "main.ek9",
  "line" : 19,
  "newName" : "temp"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ ],
  "error" : {
    "message" : "Banned identifier: temp — EK9 rejects non-descriptive names (temp/flag/data/object/value/buffer family); choose a name that states the purpose"
  },
  "meta" : {
    "serverMs" : "<timing>"
  },
  "status" : "error",
  "summary" : "Banned identifier: temp — EK9 rejects non-descriptive names (temp/flag/data/object/value/buffer family); choose a name that states the purpose",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

When to use it

When not to use it

Details

Arguments

Recorded calls

Rename symbol operator error

Rename symbol dry run none

Rename symbol banned identifier error

See also