get_file_map
Generate a structural map of C/C++ symbols in a file, grouped by kind (functions, classes, enums), to preview its contents before reading.
Instructions
Fast structural map of all C/C++ symbols in a file grouped by kind — libclang-powered table of contents. Like a table of contents before reading a chapter: see what functions, classes, and enums a file defines at a glance.
The index decides which file a path may reach: a path that no file of this build answers for is refused, and a header of the SDK that the build compiles is reachable like any file of the application.
Pass a path relative to the project root (src/main.cpp) or just the
filename (main.cpp). The exact path wins; else the path matches
whole trailing path segments (config.h matches src/config.h,
not hw_config.h), a project file before a vendor file, then the
shortest path. Returns symbols keyed by kind (function, method,
class, struct, enum, ...). Each kind has count (total) and items (first N,
default 30). Set max_per_kind=0 for unlimited, signatures=true for full sigs.
Enum constants (enum_constant) are grouped into subgroups by
parent enum. Each subgroup has name, count, and constants
(list of {name, qualified_name, line, enum_value}). The subgroup
count reflects the real total even when max_per_kind limits the
constants list.
For detailed symbol information use get_symbol_context or
lookup_symbol.
Read-only. No side effects. Use before reading a large file to orient yourself — see what functions, classes, and enums it defines.
Args:
file_path: Path relative to project root, or just the filename.
project_root: Project directory. Auto-detected if omitted.
project: Project name or project_id — call list_projects to get them. Use
it to ask about a project that is not the project of the current
directory. It is an alternative to project_root, which takes a root
path. Give one of the two, not both.
signatures: Include full function signatures. Default: False.
max_per_kind: Max items per kind group (default 30, 0 = unlimited).
With kind, the size of the page.
kind: One symbol kind, for example "function" or
"enum_constant". Gives one page of the items of that kind
instead of the map.
offset: With kind: skip this many items of that kind. Reads
the next page; page names the offset to use.
variant: Variant of the build (a board, or a PlatformIO
environment). On a project of more than one build, give the
arguments of one build as the refusal lists them: the
variant, the image, or the two. fw-context does not select a
build. One query answers for ONE build.
image: Image of the build: a separate program, such as the
application or the bootloader. Give it when the build has an
image name.
Returns: dict: {file, total_symbols, symbols: {kind: {count, items[], subgroups?[]}}}
Each item holds ``name``, ``qualified_name``, and ``line``, plus
``end_line`` when the symbol is a definition. The two line numbers
are the extent, thus ``file:line-end_line`` is the citation. A
group that ``max_per_kind`` cut holds ``hint``, the call that pages
its items.
With ``kind``: {file, kind, count, items[], page}, where ``items``
is one flat page of that kind, enum constants too, and ``page`` is
the page notice ``{total, offset, shown, more, hint}``. A page
after the last item gives one ``info`` dict that names the total.
When the file changed after the last index run, the dict adds
``stale`` (True) and ``stale_warning`` (str).
On failure the dict holds ``error`` with the reason (plus the stale
keys when indexed files changed).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | One symbol kind, e.g. 'function' or 'enum_constant'. Gives one page of the items of that kind. | |
| image | No | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. | |
| offset | No | With kind: skip this many items of that kind. Reads the next page. | |
| project | No | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. | |
| variant | No | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build for you. One query answers for ONE build. | |
| file_path | Yes | Path to source file — relative to project root or just filename. | |
| signatures | No | Include full function signatures in output. | |
| max_per_kind | No | Max items per symbol kind group (default 30, 0 = unlimited). With kind, the size of the page. | |
| project_root | No | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |