ek9_read_file

Answers first: content (numbered 'N| ' when lineNumbers:true), contentHash for expectedContentHash, and for .ek9 the structure outline {module, constructs[{kind,name,startLine,endLine,signature}]} - whole file up to 2,000 lines, truncated:true first when cut.

Category: Enquiry · Compare: cat / Read tool (Claude Code) / fs.readFile

When to use it

You know the file path and want its text - one call with path:'orders.ek9'; add lineNumbers:true before any line-anchored edit, startLine/endLine for a slice. The .ek9 structure outline comes free, so you can plan navigation without reading the body.

When not to use it

A SEMANTIC change - go straight to the editor with symbol:'<name>' (ek9_add_method, ek9_change_signature, ek9_rename_symbol, ...), no read first; a TEXT edit anchored on lines - read WITH lineNumbers:true first and quote those numbers into ek9_edit_file.
You know the construct name but NOT the file path — use ek9_read_construct (symbol:'Name').
You want a focused single-construct slice, not the whole file — use ek9_read_construct.
Searching or browsing rather than reading a known file — ek9_search_text (keyword search), ek9_list_files (directory listing), ek9_query_workspace (structure overview without file content).

Details

structure.constructs[].kind is the EK9 word for the construct (class/trait/record/enumeration/constrained-type/function/abstract-function/program/component/service/application/constant/text; dispatchers are just class); non-.ek9 files report the detected language (markdown/json/java/yaml/xml/properties/plaintext) with no structure. The raw read ignores compile success, but the workspace must be initialized via ek9_compile, and the .ek9 overlay needs a compiled workspace (else a degraded-provider warning; raw content still returned). contentHash is the value to pass as expectedContentHash to ek9_write_file / ek9_edit_file. A file over 2,000 lines is cut at 2,000 with truncated:true first and the startLine/endLine call that restores the rest. Hard errors: no workspace roots, path outside workspace (security), not found, directory (use ek9_list_files), binary, invalid range (start>end).

Arguments

Argument	Type	Required	What it is
`endLine`	integer		1-based last line of a slice (inclusive); clamped to the file's lineCount with a range-clamped warning.
`includeStructure`	boolean		When true (default), .ek9 files include the structure outline {module, constructs[{kind,name,startLine,endLine,signature}]}. Ignored for non-EK9 files.
`lineNumbers`	boolean		When true, 'content' is returned with each line prefixed by its 1-based number ('15\| sayHello() as pure'). Use it before ANY line-anchored call (edit_file line-replace, remove_statements, a 'line' argument) - counting lines in raw text miscounts. For the symbol tools prefer symbol:'<name>' and no line at all.
`path`	string	yes	File path: workspace-relative (preferred) or absolute inside the workspace. Must exist and be a text file.
`range`	object		IDE alias for the flat startLine/endLine pair: {"startLine": 100, "endLine": 200}.
`startLine`	integer		1-based first line of a slice (inclusive). With endLine; omit both for the whole file (capped at 2,000 lines).

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it.

Read with line numbers

Request

{
  "includeStructure" : false,
  "lineNumbers" : true,
  "path" : "MyRecord.ek9"
}

Response

{
  "byteCount" : 125,
  "content" : "1| #!ek9\n2| defines module com.example\n3| \n4|   defines record\n5|     MyRecord\n6|       name as String: String()\n7|       default operator\n8| \n9| //EOF\n10| ",
  "contentHash" : "sha256:7f5d05c57b329129ca15e7987b5459766b0b8be769d09ca971ed9e360e492d29",
  "encoding" : "UTF-8",
  "language" : "ek9",
  "lastModified" : "<timing>",
  "lineCount" : 9,
  "lineNumbers" : true,
  "meta" : {
    "serverMs" : "<timing>"
  },
  "path" : "MyRecord.ek9",
  "status" : "ok"
}

Read whole file with structure

Request

{
  "path" : "MyRecord.ek9"
}

Response

{
  "byteCount" : 125,
  "content" : "#!ek9\ndefines module com.example\n\n  defines record\n    MyRecord\n      name as String: String()\n      default operator\n\n//EOF\n",
  "contentHash" : "sha256:7f5d05c57b329129ca15e7987b5459766b0b8be769d09ca971ed9e360e492d29",
  "encoding" : "UTF-8",
  "language" : "ek9",
  "lastModified" : "<timing>",
  "lineCount" : 9,
  "meta" : {
    "serverMs" : "<timing>"
  },
  "path" : "MyRecord.ek9",
  "status" : "ok",
  "structure" : {
    "constructs" : [ {
      "endLine" : 7,
      "kind" : "record",
      "name" : "MyRecord",
      "signature" : "MyRecord",
      "startLine" : 5
    } ],
    "module" : "com.example"
  }
}