# SDL3 Parser - C to Zig Binding Generator

A robust parser that automatically generates idiomatic Zig bindings from SDL3 C header files.

## Overview

The SDL3 Parser analyzes C header files and generates type-safe Zig code with proper naming conventions, memory safety, and zero-cost abstractions. It handles opaque types, enums, structs, flags, and function declarations.

## Features

- ✅ **Automatic binding generation** - Parse C headers and output Zig code
- ✅ **Idiomatic naming** - Converts C naming to Zig conventions
- ✅ **Type safety** - Generates packed structs for flags, enums with backing types
- ✅ **Zero overhead** - Inline function wrappers with proper casts
- ✅ **Memory safe** - No memory leaks, validated with GPA
- ✅ **Well tested** - 18+ unit tests, integration tested with SDL_gpu.h

## Quick Start

### Build

```bash
cd lib/sdl3/parser
zig build
```

### Parse a Header

```bash
# Generate Zig bindings
zig build run -- ../SDL/include/SDL3/SDL_gpu.h > output/gpu.zig

# With C mocks (planned feature)
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --mocks
```

### Run Tests

```bash
# Unit tests
zig build test

# Test harness (planned)
cd test_project
zig build test
```

## Output Example

**Input (C):**
```c
typedef struct SDL_GPUDevice SDL_GPUDevice;

typedef enum SDL_GPUPrimitiveType {
    SDL_GPU_PRIMITIVETYPE_TRIANGLELIST,
    SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP,
} SDL_GPUPrimitiveType;

typedef Uint32 SDL_GPUTextureUsageFlags;
#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0)
#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1)

extern SDL_DECLSPEC SDL_GPUDevice* SDLCALL SDL_CreateGPUDevice(bool debug_mode);
```

**Output (Zig):**
```zig
pub const GPUDevice = opaque {};

pub const GPUPrimitiveType = enum(c_int) {
    primitivetypeTrianglelist,
    primitivetypeTrianglestrip,
};

pub const GPUTextureUsageFlags = packed struct(u32) {
    textureusageSampler: bool = false,
    textureusageColorTarget: bool = false,
    pad0: u29 = 0,
    rsvd: bool = false,
};

pub inline fn createGPUDevice(debug_mode: bool) ?*GPUDevice {
    return @ptrCast(c.SDL_CreateGPUDevice(debug_mode));
}
```

## Architecture

The parser consists of four main components:

1. **Scanner** (`patterns.zig`) - Lexical analysis and pattern matching
2. **Naming** (`naming.zig`) - C to Zig name conversion
3. **Types** (`types.zig`) - C to Zig type mapping
4. **CodeGen** (`codegen.zig`) - Zig code generation

See [Architecture](architecture.md) for details.

## Documentation

- [Architecture](architecture.md) - System design and components
- [Usage Guide](usage.md) - Detailed usage instructions
- [Naming Conventions](naming.md) - How C names map to Zig
- [Test Harness Plan](../TEST_HARNESS_PLAN_V2.md) - Planned testing infrastructure

## Project Status

### Completed ✅
- Core parser functionality
- All C declaration types supported
- Proper naming conventions
- Memory leak free
- Comprehensive unit tests
- Integration tested with SDL_gpu.h

### Planned 🚧
- C mock generation (`--mocks` flag)
- Complete test harness with linkage testing
- Golden file regression testing
- Multiple header support
- Performance benchmarking

## Requirements

- Zig 0.14+ (tested with 0.15.2)
- SDL3 headers (for input)
- No runtime dependencies

## Contributing

The parser is currently under active development. See the [Test Harness Plan](../TEST_HARNESS_PLAN_V2.md) for upcoming features.

## Recent Changes

### Version 2024-01 (Current)
- Fixed critical flag parsing bug (empty structs)
- Fixed invalid identifier generation (numeric prefixes)
- Implemented "first underscore" naming rule
- Added 13 new unit tests
- Memory leak fixes
- Comprehensive documentation

See [IMPLEMENTATION_COMPLETE.md](../IMPLEMENTATION_COMPLETE.md) for detailed changes.

## License

Part of the Backlog game engine project.