Backends

Parser backends convert C/C++ source code into the headerkit IR. The ParserBackend protocol defines the interface that all backends implement.

Backends are accessed through a registry. Use get_backend() to obtain an instance and list_backends() to discover what is available.

Available Backends

Backend	Description	C++ Support	Macro Extraction
libclang	LLVM clang-based parser	Yes	Yes

Protocol

See ParserBackend on the IR Types page for the full protocol definition including parse(), name, supports_macros, and supports_cpp.

Exceptions

LibclangUnavailableError

Bases: RuntimeError

Raised when libclang shared library cannot be found or loaded.

Registry Functions

get_backend

get_backend(name=None)

Get a parser backend instance.

Returns a new instance of the requested backend. If no name is provided, returns the default backend (libclang).

::

from headerkit.backends import get_backend

# Get default backend
backend = get_backend()

# Get libclang backend
clang = get_backend("libclang")

# Parse a header
header = backend.parse(code, "myheader.h")

Parameters:

Name	Type	Description	Default
name	str | None	Backend name (e.g., "libclang"), or None for the default backend.	None

Returns:

Type	Description
ParserBackend	New instance of the requested backend.

Raises:

Type	Description
ValueError	If the requested backend is not available. Example

get_default_backend

get_default_backend()

Get the name of the default backend.

Returns the name of the currently configured default backend.

::

from headerkit.backends import get_default_backend

default = get_default_backend()
print(f"Default backend: {default}")

Returns:

Type	Description
str	Backend name (e.g., "libclang").

Raises:

Type	Description
ValueError	If no backends are available. Example

list_backends

list_backends()

List names of all registered backends.

::

from headerkit.backends import list_backends

for name in list_backends():
    print(f"Available: {name}")

Returns:

Type	Description
list[str]	List of backend names that can be passed to :func:get_backend. Example

is_backend_available

is_backend_available(name)

Check if a backend is available for use.

For backends that require external libraries (e.g. libclang), this performs a real load test -- not just a registry lookup. The result is not cached on failure so that a subsequent auto_install() can make the library appear.

Parameters:

Name	Type	Description	Default
name	str	Backend name to check.	required

Returns:

Type	Description
bool	True if the backend is registered and its underlying library is loadable.

register_backend

register_backend(name, backend_class, is_default=False)

Register a parser backend.

Called by backend modules during import to add themselves to the registry. The first registered backend becomes the default unless is_default is explicitly set on a later registration.

Parameters:

Name	Type	Description	Default
name	str	Unique name for the backend (e.g., "libclang").	required
backend_class	type[ParserBackend]	Class implementing the :class:~headerkit.ir.ParserBackend protocol.	required
is_default	bool	If True, this becomes the default backend for :func:get_backend.	False

get_backend_info

get_backend_info()

Get information about all known backends.

Returns:

Type	Description
list[dict[str, str | bool]]	List of dicts with name, available, default, and description.