get_source
Get the exact body of a C/C++ function, enum, or macro using AST-precise extents. Returns ifdef-filtered source with line numbers, so you see only code that compiles for the current build.
Instructions
Read a C/C++ function/method/enum/macro body using libclang exact extents — no guessing line numbers. Uses AST-precise {start, end} extents so you get exactly the function body. Generic file readers don't know where a function actually ends — libclang tracks exact {start, end} from the AST.
The body is ifdef-filtered: a line of an inactive #if branch
comes back blank, thus the text holds only the code that compiles for
this build. The line numbers do not move. source_origin says where
the text came from — "index" is the filtered copy, "disk" is the
file itself and holds EVERY branch. A body reaches you from the disk
only when the file changed after the last index run, and
stale_warning says so.
For enums, includes a constants array listing all member constants
with their values. For macros, returns kind="macro" with signature
(#define NAME or #define NAME(a, b)), is_function_like,
value (the replacement text ALONE — the parameter list is not part
of it) and expanded_value (preprocessor-resolved).
For rich context (who calls this, what does it call) use
get_symbol_context instead — it returns body, callers, and callees
in a single call. For the full file, use a normal file read.
Read-only. No side effects.
Args: name: Fully qualified symbol name. Returns exact function body via libclang extent. project_root: Project root. 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. variant: Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build. image: Sysbuild image within the variant. Required when the variant holds several: each image is a separate program.
Returns:
dict: {name, qualified_name, kind, file, line, signature,
docstring, is_definition, is_template, is_virtual, is_pure_virtual,
source (str — the function/enum/macro body, truncated at 8000 chars),
warning (str, optional — when source file cannot be read)}.
May also include end_line (the last line of the extent),
template_usr, parent_usr, enum_value, constants
(list for enums), value (raw macro definition),
expanded_value (preprocessor-resolved macro value) when
applicable. A declaration has no extent, thus it gets no
end_line.
``line`` and ``end_line`` are the extent of the symbol, thus they
are the citation: quote ``file:line-end_line``. Do not count the
lines of ``source`` to find the end.
``source`` carries a line-number prefix on every line — four
columns, right-aligned, then two spaces (``" 20 bool ..."``).
This tool always numbers its text. ``read_file`` numbers its
``content`` when you pass ``line_numbers=True``, and the ``source``
of ``search_bodies`` is always bare. Strip the prefix before you
compare the text with anything.
When the file changed after the last index run, the dict adds
``stale`` (True) and ``stale_warning`` (str). ``source_origin`` then
tells where the body comes from: ``"disk"`` when the symbol did not
move, ``"index"`` when it did and the body comes from the index
instead. A moved symbol never gives the code of another symbol.
``_source_truncated`` (True) marks a body that a cap cut:
``index.max_symbol_body_lines`` bounds the number of lines, and a
second cap bounds the characters. The character cut lands in the
middle of a line, thus a body with this mark can end in an
unbalanced brace. Read the rest with ``read_file`` and a range.
An ``ambiguous_warning`` key means that *name* matched more than one
symbol, such as two classes with a method of the same name. This
body belongs to ONE of them, and the key names it and lists the
others. Give the full qualified name to get one symbol only. It is
separate from ``warning``, which reports a body that could not be
read from the disk.
On failure the dict holds ``error`` with the reason. One failure
carries more than that: when the best match for *name* is in a file
outside the project root, the dict also holds ``candidates``,
``candidates_total`` and a ``hint``. Read them — a common name
matches many symbols, and one of the others is often inside the
project.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Fully qualified symbol name. Returns exact function body via libclang extent. | |
| image | No | Sysbuild image within the variant. Required when the variant holds several: each image is a separate program. | |
| 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 | Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build. | |
| 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. |