get_source
Read exact C/C++ function, method, enum, or macro bodies using libclang AST extents, so you get the precise code block without guessing line numbers.
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
when the file changed after the last index run (stale_warning says
so), or when the index holds no body for the symbol, such as a
declaration.
For enums, includes a constants array of the member constants
with their values (at most 200; constants_total counts them all,
and constants_hint names the call that pages them). 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 read_file.
Read-only. No side effects.
Args:
name: Symbol name, or qualified name (Class::method) to select
one symbol. 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: 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: {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 (macro replacement text),
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 (8000). 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. ``candidates``
(max 20, each with ``in_project_root``) lists the others and
``candidates_total`` counts them. Give a ``qualified_name`` from it
to get one symbol only. It is separate from ``warning``, which
reports a body that could not be read from the disk.
A body in a file outside the project root, such as an SDK header,
is returned and not refused.
On failure the dict holds only ``error`` with the reason.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name, or qualified name (Class::method) to select one symbol. Returns exact function body via libclang extent. | |
| 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. | |
| 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. | |
| 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. |