xccmeta Documentation

xccmeta is a C++ metadata extraction library built on libclang. It parses C/C++ source code into a queryable AST, enabling reflection, code generation, and build pipeline integration.

Quick Start

#include <xccmeta.hpp>

const char* src = R"(
  /// @reflect
  struct Vec3 { float x, y, z; };
)";

xccmeta::compile_args args = xccmeta::compile_args::modern_cxx();
xccmeta::parser parser;
auto ast = parser.parse(src, args);

auto structs = ast->find_descendants([](auto& n) {
  return n->get_kind() == xccmeta::node::kind::struct_decl
      && n->has_tag("reflect");
});

for (auto& s : structs) {
  for (auto& field : s->get_fields()) {
    auto type = field->get_type().get_spelling();
    auto name = field->get_name();
  }
}

Architecture

Source Code (C/C++)
       |
[compile_args] <- Language standard, defines, includes
       |
   [parser] <- libclang wrapper, preprocessing
       |
    [node] <- AST tree with metadata
       |
   [filter] <- Collect nodes by kind/tags
       |
 [generator] <- Emit code to files

Data flow:

1. importer reads files (wildcards supported)
2. parser converts source to AST (node tree)
3. node::find_descendants() or filter collects relevant declarations
4. Extract metadata via node methods (get_type(), get_tags(), etc.)
5. generator writes output with type_info data

Modules

Core:

• parser - Source to AST conversion
• node - AST representation and queries
• type_info - Type introspection
• tags - Metadata annotation system

Configuration:

• compile_args - Compiler arguments builder

Utilities:

• filter - AST node collection with deduplication
• generator - Code generation output writer
• import - File I/O and glob patterns
• source - Source locations and ranges
• warnings - Compile-time warning injection

Optional:

• preprocess - Preprocessor text extraction (rarely needed)
• base - Shared library visibility macros

Guides

• Getting Started - Installation, build, and basic usage
• Architecture - System design, memory model, and data flow
• Common Patterns - Recipes for frequent tasks
• Examples - Walkthrough of the example programs

Reading Order

New users:

1. Getting Started
2. parser
3. node
4. generator

Advanced topics:

1. filter - Complex queries
2. type_info - Type introspection details
3. tags - Annotation patterns
4. preprocess - Macro debugging