query tool
Use query to find code by its syntax, as xpd run does, and to
preview a replacement. Give exactly one of pattern and kind. It changes no file, and
rewrite writes a replacement.
query(query, paths=null)- Changes no file
- A second call with the same arguments changes nothing more
- Stays inside the project
Tags: structure.
Description
Section titled “Description”The server gives the agent this description of the tool.
Find AST patterns or syntax kinds and preview replacements without changing files.
Arguments
Section titled “Arguments”Type: object. Required.
The pattern or kind to find, and the replacement to preview.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
query.pattern |
string or null | no | null |
AST pattern with $VARIABLE captures. |
query.kind |
string or null | no | null |
Syntax kind instead of a pattern. |
query.language |
string or null | no | null |
The language of the pattern, such as python. Default: each file's extension. |
query.selector |
string or null | no | null |
The kind of the part of the pattern that is the match. |
query.rewrite |
string or null | no | null |
Replacement template to preview. |
Type: list of string or null. Optional, default null.
Files or folders inside the project root. Default: the whole root.
Result
Section titled “Result”The 17 fields of the result
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
result |
list of object | yes | ||
result[].text |
string | yes | ||
result[].file |
string | yes | ||
result[].language |
string | yes | ||
result[].range |
object | yes | ||
result[].range.byteOffset |
object | yes | ||
result[].range.byteOffset.start |
integer | yes | ||
result[].range.byteOffset.end |
integer | yes | ||
result[].range.start |
object | yes | ||
result[].range.start.line |
integer | yes | ||
result[].range.start.column |
integer | yes | ||
result[].range.end |
object | yes | ||
result[].range.end.line |
integer | yes | ||
result[].range.end.column |
integer | yes | ||
result[].replacement |
string or null | no | null |
|
result[].replacementOffsets |
object or null | no | null |
|
result[].metaVariables |
object | no |
Example
Section titled “Example”{"query":{"pattern":"$X.iterrows()","language":"python"},"paths":["samples/bad.py"]}The result is a list with one entry for each match. The one match is shown without its byte offsets and metavariables. Lines and columns count from zero.
[{"text":"df.iterrows()","file":"samples/bad.py","language":"Python","range":{"start":{"line":4,"column":14},"end":{"line":4,"column":27}},"replacement":null,"lines":"for i, row in df.iterrows():"}]Errors
Section titled “Errors”A query with both or neither of pattern and kind fails with "Provide exactly one of pattern
or kind." A path outside the project root fails before xpd runs. No match is an empty list, not an error.