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.

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: Optional[str] = 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.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_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

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: Optional[Callable[[str, Optional[str]], str]] = 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, Optional[str]], str]