Simple API

The simple parser/collector iterates over the C++ file and returns a data structure with all elements in it. Not quite as flexible as implementing your own parser listener, but you can accomplish most things with it.

cxxheaderparser’s unit tests predominantly use the simple API for parsing, so you can expect it to be pretty stable.

The parse_string() and parse_file() functions are a great place to start:

from cxxheaderparser.simple import parse_string

content = '''
    int x;
'''

parsed_data = parse_string(content)

See below for the contents of the returned ParsedData.

Looking up declarations

Use get_declaration() to retrieve a parsed object by its qualified name:

from cxxheaderparser.simple import get_declaration, parse_string

data = parse_string('''
    namespace name {
        /** A counter. */
        struct Bar {
            /** Current count. */
            int count();
        };
    }
''')

print(get_declaration(data, "name::Bar::count").doxygen)
print(get_declaration(data, "name::Bar").class_decl.doxygen)

Classes return ClassScope, so their documentation is on class_decl.doxygen. Invalid or missing names raise KeyError; multiple matches (including overloads) raise AmbiguousNameError. Lookup does not follow inheritance, aliases, or using declarations.

Names are parsed with parse_name(), which returns a PQName and supports templates and operators without parameter lists. Use parse_typename() for type-ids such as const C* instead.

API reference

exception cxxheaderparser.simple.AmbiguousNameError

Raised by get_declaration() when multiple declarations match a name.

class cxxheaderparser.simple.ClassScope(class_decl, classes=<factory>, enums=<factory>, fields=<factory>, friends=<factory>, methods=<factory>, typedefs=<factory>, forward_decls=<factory>, using=<factory>, using_alias=<factory>)

Contains all data collected for a single C++ class

Parameters:
class_decl: ClassDecl

Information about the class declaration is here

classes: List[ClassScope]

Nested classes

enums: List[EnumDecl]
fields: List[Field]
forward_decls: List[ForwardDecl]
friends: List[FriendDecl]
methods: List[Method]
typedefs: List[Typedef]
using: List[UsingDecl]
using_alias: List[UsingAlias]
class cxxheaderparser.simple.Include(filename)
Parameters:

filename (str)

filename: str

The filename includes the surrounding <> or "

class cxxheaderparser.simple.NamespaceScope(name='', inline=False, doxygen=None, classes=<factory>, enums=<factory>, functions=<factory>, method_impls=<factory>, typedefs=<factory>, variables=<factory>, forward_decls=<factory>, using=<factory>, using_ns=<factory>, using_alias=<factory>, ns_alias=<factory>, concepts=<factory>, template_insts=<factory>, namespaces=<factory>, deduction_guides=<factory>)

Contains all data collected for a single namespace. Content for child namespaces are found in the namespaces attribute.

Parameters:
classes: List[ClassScope]
concepts: List[Concept]

Concepts

deduction_guides: List[DeductionGuide]

Deduction guides

doxygen: str | None = None
enums: List[EnumDecl]
forward_decls: List[ForwardDecl]
functions: List[Function]

Function declarations (with or without body)

inline: bool = False
method_impls: List[Method]

Method implementations outside of a class (must have a body)

name: str = ''
namespaces: Dict[str, NamespaceScope]

Child namespaces

ns_alias: List[NamespaceAlias]
template_insts: List[TemplateInst]

Explicit template instantiations

typedefs: List[Typedef]
using: List[UsingDecl]
using_alias: List[UsingAlias]
using_ns: List[UsingNamespace]
variables: List[Variable]
class cxxheaderparser.simple.ParsedData(namespace=<factory>, pragmas=<factory>, includes=<factory>)

Container for information parsed by the parse_file() and parse_string() functions.

Warning

Names are not resolved, so items are stored in the scope that they are found. For example:

namespace N {
    class C;
}

class N::C {
    void fn();
};

The ‘C’ class would be a forward declaration in the ‘N’ namespace, but the ClassDecl for ‘C’ would be stored in the global namespace instead of the ‘N’ namespace.

Parameters:
includes: List[Include]

Any #include directives encountered

namespace: NamespaceScope

Global namespace

pragmas: List[Pragma]

Any #pragma directives encountered

class cxxheaderparser.simple.Pragma(content)
Parameters:

content (Value)

content: Value
class cxxheaderparser.simple.SimpleCxxVisitor

A simple visitor that stores all of the C++ elements passed to it in an “easy” to use data structure

You probably don’t want to use this directly, use parse_file() or parse_string() instead.

data: ParsedData
on_class_end(state)
Parameters:

state (ClassBlockState[ClassScope, Union[ClassScope, NamespaceScope]])

Return type:

None

on_class_field(state, f)
Parameters:
Return type:

None

on_class_friend(state, friend)
Parameters:
Return type:

None

on_class_method(state, method)
Parameters:
Return type:

None

on_class_start(state)
Parameters:

state (ClassBlockState[ClassScope, Union[ClassScope, NamespaceScope]])

Return type:

Optional[bool]

on_concept(state, concept)
Parameters:
Return type:

None

on_deduction_guide(state, guide)
Parameters:
Return type:

None

on_enum(state, enum)
Parameters:
Return type:

None

on_extern_block_end(state)
Parameters:

state (ExternBlockState[NamespaceScope, NamespaceScope])

Return type:

None

on_extern_block_start(state)
Parameters:

state (ExternBlockState[NamespaceScope, NamespaceScope])

Return type:

Optional[bool]

on_forward_decl(state, fdecl)
Parameters:
Return type:

None

on_function(state, fn)
Parameters:
Return type:

None

on_include(state, filename)
Parameters:
Return type:

None

on_method_impl(state, method)
Parameters:
Return type:

None

on_namespace_alias(state, alias)
Parameters:
Return type:

None

on_namespace_end(state)
Parameters:

state (NamespaceBlockState[NamespaceScope, NamespaceScope])

Return type:

None

on_namespace_start(state)
Parameters:

state (NamespaceBlockState[NamespaceScope, NamespaceScope])

Return type:

Optional[bool]

on_parse_start(state)
Parameters:

state (NamespaceBlockState[NamespaceScope, NamespaceScope])

Return type:

None

on_pragma(state, content)
Parameters:
Return type:

None

on_template_inst(state, inst)
Parameters:
Return type:

None

on_typedef(state, typedef)
Parameters:
Return type:

None

on_using_alias(state, using)
Parameters:
Return type:

None

on_using_declaration(state, using)
Parameters:
Return type:

None

on_using_namespace(state, namespace)
Parameters:
Return type:

None

on_variable(state, v)
Parameters:
Return type:

None

class cxxheaderparser.simple.UsingNamespace(ns)
Parameters:

ns (str)

ns: str
cxxheaderparser.simple.get_declaration(data, qualified_name)

Find a named declaration in parsed data.

Names are relative to the global namespace; a leading :: is optional. Returns the original object, including ClassScope for classes and NamespaceScope for namespaces. Enum values are addressed as Enum::value. Names are parsed with parse_name() and compared structurally, allowing whitespace in qualified names and template arguments. Operator names are supported, including conversions such as C::operator bool or C::operator const int*.

This is declaration lookup, not C++ semantic name resolution: inheritance, using-directives/declarations, alias targets, and inline/anonymous namespace injection are not followed. Anonymous declarations, friends, deduction guides, and explicit template instantiations are not searched. Qualified declarations are matched even when stored outside their named scope.

Raises:

  • KeyError – The name is invalid or no declaration matches.

  • AmbiguousNameError – Multiple declarations match. Overloads, repeated declarations, and forward declarations are not merged.

Parameters:
Return type:

Union[NamespaceScope, ClassScope, EnumDecl, Enumerator, Function, Field, Typedef, Variable, ForwardDecl, UsingAlias, NamespaceAlias, Concept]

cxxheaderparser.simple.parse_file(filename, encoding=None, *, options=None)

Simple function to parse a header from a file and return a data structure

Parameters:

  • filename (Union[str, PathLike])

  • encoding (Optional[str])

  • options (Optional[ParserOptions])

Return type:

ParsedData

cxxheaderparser.simple.parse_name(name, *, filename='<str>', options=None)

Parse a qualified declaration name, returning a PQName.

Supports template arguments, constructors, destructors, and operator names without parameter lists. Conversion operators use a final NameSpecifier containing operator followed by a space and the formatted target type.

Unlike parse_typename(), this parses names rather than type-ids: C::operator bool is a name, whereas const C* is a type-id.

Raises:

CxxParseError – The input is not a supported declaration name.

Parameters:
Return type:

PQName

cxxheaderparser.simple.parse_string(content, *, filename='<str>', options=None, cleandoc=False)

Simple function to parse a header and return a data structure

Parameters:

  • content (str)

  • filename (str)

  • options (Optional[ParserOptions])

  • cleandoc (bool)

Return type:

ParsedData

cxxheaderparser.simple.parse_typename(typename, *, filename='<str>', options=None)

Parse a C++ type name and return a TypeId.

Parameters:

  • typename (str)

  • filename (str)

  • options (Optional[ParserOptions])

Return type:

Union[Array, MemberPointer, Pointer, MoveReference, Reference, Type, FunctionType]

class cxxheaderparser.options.ParserOptions(verbose=False, convert_void_to_zero_params=True, preprocessor=None)

Options that control parsing behaviors

Parameters:

  • verbose (bool)

  • convert_void_to_zero_params (bool)

  • preprocessor (Optional[Callable[[str, Optional[str]], str]])

convert_void_to_zero_params: bool = True

If true, converts a single void parameter to zero parameters

preprocessor: Callable[[str, str | None], str] | None = None

A function that will preprocess the header before parsing. See cxxheaderparser.preprocessor for available preprocessors

verbose: bool = False

If true, prints out

cxxheaderparser.options.PreprocessorFunction

arguments are (filename, content)

alias of Callable[[str, str | None], str]