get_file_map
Get a structural overview of C/C++ files by listing all symbols—functions, classes, enums—grouped by kind, with counts and optional signatures, to orient 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.
Paths are validated against the project root before read —
:func:_validate_path_in_root ensures resolved paths stay within bounds.
Pass a path relative to the project root (src/main.cpp) or just the
filename (main.cpp). 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. signatures: Include full function signatures. Default: False. max_per_kind: Max items per kind group (default 30, 0 = unlimited).
Returns: dict: {file, total_symbols, symbols: {kind: {count, items[], subgroups?[]}}}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | Sysbuild image name within the variant (multi-project). Omit for all images of the variant. | |
| variant | No | Build variant name (multi-project). Omit to use default_variant or fail-closed. Use '*' for all variants. | |
| 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). | |
| project_root | No | Project root. Auto-detected if omitted. |