C_projet/CLAUDE.md
2026-11-04 18:00:08 +01:00

397 lines
11 KiB
Markdown

# C Object-Oriented Architecture
This project uses an object-oriented design pattern in C based on opaque pointers and vtables for method dispatch and polymorphism.
## Project Structure
```
.
├── src/ # Implementation files (.c)
├── src/include/ # Protected headers (protected_*.h)
├── include/ # Public API headers (*.h)
├── CMakeLists.txt # Minimalist CMake configuration
└── CLAUDE.md # This file
```
## Type Definition Pattern
Each class follows an opaque pointer pattern to hide implementation details:
### Public Header (`include/class.h`)
```c
/* Opaque type definition - structure details hidden from users */
typedef struct _class_t class_t;
/* Vtable definition with function pointers - made public for polymorphism */
typedef struct {
void (*method_a)(const class_t *const self);
int (*method_b)(const class_t *const self, int arg);
} vtable_class_t;
/* Dispatcher functions - the ONLY way to access methods */
void class_method_a(const class_t *const self);
int class_method_b(const class_t *const self, int arg);
/* Constructors */
class_t* class_build_default(void);
class_t* class_build_logic(/* constructor arguments */);
/* Destructor */
void class_destroy(class_t *self);
```
### Protected Header (`src/include/protected_class.h`)
```c
#ifndef PROTECTED_CLASS_H
#define PROTECTED_CLASS_H
#include "class.h"
/* Real structure definition - only visible to implementation and children */
struct _class_t {
vtable_class_t vtable; /* Virtual table as first field */
/* ... other members ... */
};
/* Protected constructors for use by child classes */
class_t* class_init_default(void);
class_t* class_init_logic(/* constructor arguments */);
#endif
```
**IMPORTANT**: `protected_class.h` must NEVER be included in `class.h` or any other public `.h` file.
### Implementation (`src/class.c`)
```c
#include "class.h" /* For function prototypes and public typedefs */
#include "protected_class.h" /* For structure definition */
/* Private (static) implementation */
static void _class_method_a_impl(const class_t *const self) {
/* Implementation */
}
static int _class_method_b_impl(const class_t *const self, int arg) {
/* Implementation */
}
/* Default vtable with standard implementations */
static const vtable_class_t class_default_vtable = {
.method_a = _class_method_a_impl,
.method_b = _class_method_b_impl,
};
/* Constructors */
class_t* class_build_default(void) {
return class_init_default();
}
class_t* class_build_logic(/* args */) {
/* Validation and setup if needed */
return class_init_logic(/* args */);
}
/* Protected constructor with actual initialization logic */
class_t* class_init_default(void) {
class_t *self = malloc(sizeof(class_t));
if (!self) return NULL;
/* Initialize vtable with default implementation */
self->vtable = class_default_vtable;
/* Initialize other members */
return self;
}
class_t* class_init_logic(/* args */) {
/* Similar to init_default but with custom initialization */
}
/* Destructor */
class_t* class_destroy(class_t *self) {
if (!self) return NULL;
/* Clean up resources */
free(self);
return NULL;
}
/* Dispatcher functions - delegate to vtable */
void class_method_a(const class_t *const self) {
return self->vtable.method_a(self);
}
int class_method_b(const class_t *const self, int arg) {
return self->vtable.method_b(self, arg);
}
```
## Inheritance Pattern
### Single Inheritance via Vtable Extension
Child classes extend a parent's vtable by embedding the parent vtable as the first field (named `super`):
### Child Public Header (`include/child.h`)
```c
typedef struct _child_t child_t;
/* Child vtable includes parent vtable and new methods */
typedef struct {
vtable_class_t super; /* Parent vtable as first field */
void (*method_c)(const child_t *const self);
} vtable_child_t;
/* Only dispatch NEW methods - parent methods are accessed via parent dispatcher */
void child_method_c(const child_t *const self);
/* Constructors */
child_t* child_build_default(void);
child_t* child_build_logic(/* args */);
/* Destructor */
child_t* child_destroy(child_t *self);
```
### Child Protected Header (`src/include/protected_child.h`)
```c
#ifndef PROTECTED_CHILD_H
#define PROTECTED_CHILD_H
#include "child.h"
#include "protected_class.h" /* Include parent's protected header */
struct _child_t {
vtable_child_t vtable;
/* ... child-specific members ... */
};
child_t* child_init_default(void);
child_t* child_init_logic(/* args */);
#endif
```
### Child Implementation (`src/child.c`)
```c
#include "child.h"
#include "protected_child.h"
static void _child_method_c_impl(const child_t *const self) {
/* Implementation */
}
static const vtable_child_t child_default_vtable = {
.super = class_default_vtable, /* Use parent's default vtable */
.method_c = _child_method_c_impl,
};
child_t* child_init_default(void) {
child_t *self = malloc(sizeof(child_t));
if (!self) return NULL;
/* Assign child vtable (which includes parent vtable) */
self->vtable = child_default_vtable;
/* Initialize child-specific members */
return self;
}
child_t* child_destroy(child_t *self) {
if (!self) return NULL;
/* Clean up child resources */
free(self);
return NULL;
}
void child_method_c(const child_t *const self) {
return self->vtable.method_c(self);
}
```
### Using Parent Methods from Child Code
When child code needs to call parent methods, cast and use the parent dispatcher:
```c
/* In child implementation or user code */
child_t *obj = child_build_default();
/* Call parent method through explicit cast */
class_method_a((const class_t *const) obj);
/* Call child method */
child_method_c(obj);
obj = child_destroy(obj);
```
**Note**: Each class only provides dispatchers for its own methods. There are NO child dispatchers that call parent dispatchers—the programmer is responsible for explicit parent method calls via casting.
## Method Visibility
### Private Methods (Static)
- Declared and defined in `.c` files only
- Prefixed with `_` (e.g., `_class_method_impl`)
- Not visible outside the implementation file
- Used as vtable function implementations
### Protected Methods
- Declared in `src/include/protected_class.h`
- Prefixed with class name, no underscore (e.g., `class_init_default`)
- Used by child classes and implementations
- Constructors and initialization helpers typically protected
### Public Methods
- Declared in `include/class.h`
- Dispatcher functions for vtable methods
- User-facing constructors and destructors
- The primary API of the class
## Virtual Table Access
Virtual table members are **NEVER accessed directly**. Access is always through dispatcher functions:
```c
/* WRONG - don't do this */
self->vtable.method_a(self);
/* RIGHT - always use dispatchers */
class_method_a(self);
```
This ensures:
- Proper abstraction and encapsulation
- Consistent method resolution
- Easy to maintain and debug
## Default Vtable Pattern
Each implementation file defines a static const vtable with default function pointers, avoiding manual vtable initialization in each constructor:
```c
/* In src/class.c */
static const vtable_class_t class_default_vtable = {
.method_a = _class_method_a_error,
.method_b = _class_method_b_default,
};
```
Protected constructors then simply assign this default vtable to newly allocated instances:
```c
class_t* class_init_default(void) {
class_t *self = malloc(sizeof(class_t));
if (!self) return NULL;
self->vtable = class_default_vtable; /* Assign default vtable */
/* Initialize other members */
return self;
}
```
This pattern:
- Reduces code duplication across multiple constructors
- Ensures vtable consistency across object instances
- Simplifies maintenance of method implementations
## Method Naming Conventions for Base Classes
Base classes should use specific naming conventions for default method implementations to indicate whether a method is abstract or has a default implementation:
### Abstract Methods (No Implementation)
Abstract methods that must be overridden by child classes are named with `_error` suffix:
```c
static void _class_method_a_error(const class_t *const self) {
fprintf(stderr, "ERROR: method_a() must be specialized in a child class\n");
assert(0);
}
static const vtable_class_t class_default_vtable = {
.method_a = _class_method_a_error,
.method_b = _class_method_b_default,
};
```
When an abstract method is called without being overridden, the error function prints a descriptive message and fails with `assert(0)`.
### Methods with Default Behavior
Methods that have a default implementation are named with `_default` suffix:
```c
static void _class_method_b_default(const class_t *const self) {
/* Default implementation */
}
static const vtable_class_t class_default_vtable = {
.method_a = _class_method_a_error,
.method_b = _class_method_b_default,
};
```
Child classes can override `_class_method_b_default` if they need specialized behavior, or inherit the default by reusing the parent's vtable entry.
**Naming Summary**:
- `class_method_error` — Abstract method requiring specialization
- `class_method_default` — Method with default implementation
## Constructor/Destructor Conventions
### Constructors
- `class_t* class_build_default(void)` — Public default constructor
- Typically a thin wrapper calling protected `class_init_default()`
- May include validation before calling the protected method
- `class_t* class_build_logic(/* args */)` — Public specialized constructor
- For constructors with specific arguments
- Typically wraps `class_init_logic(/* args */)`
- `class_t* class_init_default(void)` — Protected default constructor
- Contains actual construction logic
- Allocation, vtable initialization, member setup
- Called by public constructor or child classes
- `class_t* class_init_logic(/* args */)` — Protected specialized constructor
- Protected variant for child classes to reuse construction logic
### Destructors
- `void class_destroy(class_t *self)` — Public and protected
- Returns void.
- Cleans up resources and frees memory
## Summary Checklist
- [ ] Structure `struct _class_t` declared in `protected_class.h`
- [ ] Typedef `typedef struct _class_t class_t;` in public `class.h`
- [ ] Vtable typedef in public `class.h`
- [ ] Vtable as first field of real structure
- [ ] Dispatcher functions in public header and implementation
- [ ] Private implementations as static functions with `_` prefix
- [ ] Protected methods (constructors) declared in protected header
- [ ] Public API (dispatchers, public constructors/destructors) in public header
- [ ] Child classes embed parent vtable as `super` field
- [ ] No `#include "protected_*.h"` in any public header
- [ ] Implementation files include both public and protected headers