Implementation:Google deepmind Dm control Header Parsing

Knowledge Sources	Google_deepmind_Dm_control
Domains	Robotics Simulation, Code Generation
Last Updated	2026-02-15 04:00 GMT

Overview

This module defines comprehensive pyparsing grammars and type-mapping dictionaries for parsing MuJoCo C header files, enabling automatic generation of Python bindings.

Description

The header_parsing module provides the lexical foundation for the dm_control autowrap system. It uses the pyparsing library to build a hierarchy of parsers from primitive tokens (names, integers, floats, array dimensions) up to complex C constructs such as preprocessor directives, type declarations, enum definitions, struct definitions, function declarations, and MuJoCo-specific X-macro patterns.

The module defines three type-mapping dictionaries: C_TO_CTYPES maps C type names (e.g., int, double, char) to their ctypes equivalents; CTYPES_PTRS maps pointer types; and CTYPES_TO_NUMPY maps ctypes to NumPy dtypes. These enable the autowrap system to produce correct type annotations in generated Python code.

Key grammar constructs include: DEF_FLAG and DEF_CONST for #define macros; COND_DECL using recursive _nested_if_else and _nested_ifn_else helpers for #ifdef/#ifndef blocks; ENUM_DECL for typedef enums with explicit values, bitshift expressions, and comments; NESTED_STRUCTS for possibly nested struct declarations with anonymous union support; XMACRO and XMEMBER for MuJoCo X-macro patterns encoding array shape information; and MJAPI_FUNCTION_DECL for public API function signatures.

Usage

Use this module when you need to parse MuJoCo C header files to extract type definitions, constants, enumerations, struct layouts, function signatures, or X-macro declarations for the purpose of automatically generating Python/ctypes bindings.

Code Reference

Source Location

• Repository: Google_deepmind_Dm_control
• File: dm_control/autowrap/header_parsing.py
• Lines: 1-335

Signature

# Type mapping dictionaries
C_TO_CTYPES = {
    "int": "ctypes.c_int",
    "unsigned int": "ctypes.c_uint",
    "char": "ctypes.c_char",
    "unsigned char": "ctypes.c_ubyte",
    "size_t": "ctypes.c_size_t",
    "float": "ctypes.c_float",
    "double": "ctypes.c_double",
    "void": "None",
}

CTYPES_PTRS = {"None": "ctypes.c_void_p"}

CTYPES_TO_NUMPY = {
    "ctypes.c_int": "np.intc",
    "ctypes.c_uint": "np.uintc",
    "ctypes.c_ubyte": "np.ubyte",
    "ctypes.c_float": "np.float32",
    "ctypes.c_double": "np.float64",
}

# Recursive parser helpers
def _nested_scopes(opening, closing, body): ...
def _nested_if_else(if_, pred, else_, endif, match_if_true, match_if_false): ...
def _nested_ifn_else(ifn_, pred, else_, endif, match_if_true, match_if_false): ...

# Key grammar objects (all pyparsing.ParserElement):
DEF_FLAG       # Parses #define flag macros
DEF_CONST      # Parses #define constant macros
COND_DECL      # Parses conditional (#ifdef/#ifndef) declarations
STRUCT_MEMBER  # Parses struct member declarations
NESTED_STRUCTS # Parses nested struct declarations
ENUM_DECL      # Parses typedef enum declarations
XMACRO         # Parses MuJoCo X-macro blocks
MJAPI_FUNCTION_DECL  # Parses MJAPI function declarations
FUNCTION_PTR_TYPE_DECL  # Parses function pointer type declarations

Import

from dm_control.autowrap import header_parsing

I/O Contract

Inputs

Name	Type	Required	Description
C header text	str	Yes	Raw text content of a MuJoCo C header file to be parsed by any of the grammar objects

Outputs

Name	Type	Description
parse result	pyparsing.ParseResults	Structured parse tree containing named fields (e.g., name, typename, value, comment, members) extracted from matched grammar constructs

Usage Examples

Basic Usage

from dm_control.autowrap import header_parsing

# Parse a #define constant
result = header_parsing.DEF_CONST.parseString(
    '#define mjMINVAL    1E-14       // minimum value in any denominator'
)
print(result[0].name)     # 'mjMINVAL'
print(result[0].value)    # '1E-14'
print(result[0].comment)  # 'minimum value in any denominator'

# Parse a typedef enum
enum_text = """typedef enum mjtWarning {
  mjWARN_INERTIA    = 0,       // inertia error
  mjWARN_BADQPOS    = 1,       // bad qpos
} mjtWarning;"""
result = header_parsing.ENUM_DECL.parseString(enum_text)
print(result[0].typename)  # 'mjtWarning'

# Look up ctypes equivalents
ctype = header_parsing.C_TO_CTYPES['double']  # 'ctypes.c_double'
nptype = header_parsing.CTYPES_TO_NUMPY[ctype]  # 'np.float64'