ek9_search_text

Answers first: matchCount, files[], sites['file.ek9:LINE'] (truncated:true first when cut), then matches[{file,line,column,snippet}] - a literal or regex grep across the workspace with EK9-aware exclusions (build outputs, .ek9-cache/, dot-directories).

Category: Enquiry · Compare: ripgrep / grep / Find in Files

When to use it

You want every place a piece of TEXT or a regex appears across workspace files - one call with query:'TODO'; add pathPattern:'**/*.ek9' or path to bound it. Comments, strings, README mentions, config keys - when no symbol name or file path is known.

When not to use it

Uses of a NAMED construct or member - use ek9_query_references (symbol:'Type.member', semantic, exact); to find a construct by name use ek9_find_constructs_by_name.
Searching for a FILE NAME rather than content — use ek9_list_files.
Searching for compiler errors / warnings — use ek9_query_diagnostics.
As a 'locate first' pre-step before mutating — editors (e.g. ek9_edit_localized_text, ek9_organize_localized_text) do their own discovery; dispatch straight to them.

Details

Pure lexical grep — never consults symbol tables or the AST, so identical results regardless of compile state; requires watched roots (run ek9_compile first). Literal mode matches EK9 operators (<=> ? :=?) verbatim with no escaping; regex mode needs a valid java.util.regex.Pattern. caseSensitive defaults to true when the query is an identifier containing an uppercase letter (a symbol name) and false otherwise; pass it explicitly to override. path bounds the root (a directory, or a single file to search only it), pathPattern filters within it (intersection, cannot un-exclude); maxResults default 100 max 1000 - a cut result opens with truncated:true and matchTotal. column is 0-based, the base every EK9 tool uses.

Arguments

Argument	Type	Required	What it is
`caseSensitive`	boolean		Omit it: an identifier with an uppercase letter (a symbol name) is searched case-sensitively, anything else case-insensitively. Set it to override.
`includeHidden`	boolean		When true, includes dot-files and otherwise-excluded build directories in the scan.
`isRegex`	boolean		When true, query is parsed as a java.util.regex.Pattern.
`maxResults`	integer		Cap on matches[] (default 100, max 1000). A cut result opens with truncated:true and matchTotal (the true count).
`path`	string		Bounds the search: a workspace-relative directory, or ONE file to search just that file ('m04.ek9'). Defaults to the workspace root.
`pathPattern`	string		Optional glob restricting which files are searched, applied relative to path (e.g. "*/.ek9", "src/main/**"). Intersects with default exclusions — cannot bring back excluded paths.
`query`	string	yes	Literal text (default) or regex pattern (when isRegex:true). Literal mode matches special characters verbatim — no escaping needed for operators like <=> ? :=? * ( ) [ ] \.
`verbosity`	string: full \| summary \| none		full (default) returns matches[] records; summary keeps the headline only (files, sites, counts); none collapses the lists to counts.

Recorded calls

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

Search bounded to one file

Request

{
  "path" : "MyRecord.ek9",
  "query" : "MyRecord"
}

Response

{
  "caseSensitive" : true,
  "fileCount" : 1,
  "files" : [ "MyRecord.ek9" ],
  "isRegex" : false,
  "matchCount" : 1,
  "matches" : [ {
    "column" : 4,
    "file" : "MyRecord.ek9",
    "line" : 5,
    "snippet" : "    MyRecord"
  } ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "query" : "MyRecord",
  "sites" : [ "MyRecord.ek9:5" ],
  "status" : "ok"
}

Search literal finds match

Request

{
  "caseSensitive" : true,
  "query" : "MyRecord"
}

Response

{
  "caseSensitive" : true,
  "fileCount" : 1,
  "files" : [ "MyRecord.ek9" ],
  "isRegex" : false,
  "matchCount" : 1,
  "matches" : [ {
    "column" : 4,
    "file" : "MyRecord.ek9",
    "line" : 5,
    "snippet" : "    MyRecord"
  } ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "query" : "MyRecord",
  "sites" : [ "MyRecord.ek9:5" ],
  "status" : "ok"
}